Integrate canonical architecture: two-process backend + LiveKit agent

Promote all 12 staged canonical files from docs/generated/files/ to their
live paths, creating the full PodMan architecture:

Backend:
- server.ts: HTTP service (token mint, sync-PR, outcome recording, /health, WS relay)
- agent.ts: worker joining LiveKit room, grabbing screenshare frames at ~1fps
- agent/podman.ts: orchestrator loop (vision -> collision detection -> intervention)
- env.ts: flat env var accessors replacing nested stub
- vision/gemini.ts: JPEG -> Gemini vision -> EngineerContext (real implementation)
- collision/detector.ts: fused vision+GitHub collision detection (the moat)
- github/client.ts: Octokit wrapper with caching + sync PR creation
- memory/store.ts: extended with recordObservation/recordCollision/recordIntervention/recordOutcome helpers
- memory/vectors.ts: stub for Voyage+Atlas vector recall (Loop A)
- memory/policy.ts: stub for intervention policy gate (Loop B)
- voice/live.ts: stub for Gemini Live TTS voice output

Shared:
- messages.ts: LiveKit data-channel wire protocol (DataMessage, InterventionOutcome, TeamModel, LocalGitReport)
- index.ts: re-exports messages module

Frontend:
- livekit/useScreenPublish.ts: hook for joining pod and publishing screenshare
- livekit/useInterventions.ts: hook for receiving collision cards and responding
- lib/api.ts: fetchToken + postOutcome HTTP helpers

Database:
- database/init.ts: MongoDB Atlas collections + indexes + vector search index

Infra:
- infra/.do/app.yaml: DO App Platform spec (static_site + service + worker)

Retire stubs superseded by canonical decomposition:
- backend/src/index.ts (replaced by server.ts)
- backend/src/intervention/engine.ts (logic now in agent/podman.ts)
- backend/src/livekit/token.ts (token minting now in server.ts)

Install missing dependencies: @livekit/rtc-node, sharp, mongodb, ws, @types/ws

Type error fixes:
- vision/gemini.ts: use MediaResolution.MEDIA_RESOLUTION_LOW enum value (not string literal)
- agent/podman.ts: wrap SuggestedActionKind into { kind: action } SuggestedAction object

All packages pass pnpm -r typecheck and pnpm -r build.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/package.json

@@ -5,23 +5,30 @@
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
-    "dev": "tsx watch src/index.ts",
+    "dev": "tsx watch src/server.ts",
-    "start": "node dist/index.js",
+    "dev:server": "tsx watch src/server.ts",
+    "dev:agent": "tsx watch src/agent.ts",
+    "start": "node dist/server.js",
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "@google/genai": "^2.10.0",
+    "@livekit/rtc-node": "^0.13.29",
     "@podman/shared": "workspace:*",
     "cors": "^2.8.6",
     "dotenv": "^17.4.2",
     "express": "^5.2.1",
     "livekit-server-sdk": "^2.15.5",
-    "octokit": "^5.0.5"
+    "mongodb": "^7.4.0",
+    "octokit": "^5.0.5",
+    "sharp": "^0.35.2",
+    "ws": "^8.21.0"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
+    "@types/ws": "^8.18.1",
     "tsx": "^4.22.4"
   }
 }

backend/src/agent.ts

@@ -0,0 +1,79 @@
+import {
+  Room,
+  RoomEvent,
+  TrackKind,
+  TrackSource,
+  VideoStream,
+  VideoBufferType,
+  dispose,
+  type RemoteTrack,
+  type RemoteTrackPublication,
+  type RemoteParticipant,
+} from '@livekit/rtc-node';
+import sharp from 'sharp';
+import { AccessToken } from 'livekit-server-sdk';
+import { env } from './env.js';
+import { PodMan } from './agent/podman.js';
+
+const POD_ROOM = process.env.POD_ROOM ?? 'demo-pod';
+const SAMPLE_INTERVAL_MS = 1000; // ~1 fps to the vision model
+
+async function agentToken(room: string): Promise<string> {
+  const at = new AccessToken(env.LIVEKIT_API_KEY, env.LIVEKIT_API_SECRET, {
+    identity: 'podman-agent',
+    name: 'PodMan',
+    ttl: '4h',
+  });
+  at.addGrant({ roomJoin: true, room, canPublish: true, canSubscribe: true, canPublishData: true });
+  return at.toJwt();
+}
+
+async function main() {
+  const room = new Room();
+  const podman = new PodMan(room, POD_ROOM);
+  await room.connect(env.LIVEKIT_URL, await agentToken(POD_ROOM), {
+    autoSubscribe: true,
+    dynacast: true,
+  });
+  await podman.start();
+  console.log(`[agent] PodMan joined room ${POD_ROOM}`);
+
+  const lastSent = new Map<string, number>();
+
+  room.on(
+    RoomEvent.TrackSubscribed,
+    (track: RemoteTrack, pub: RemoteTrackPublication, participant: RemoteParticipant) => {
+      if (track.kind !== TrackKind.KIND_VIDEO || pub.source !== TrackSource.SOURCE_SCREENSHARE) return;
+      const id = participant.identity;
+      const stream = new VideoStream(track);
+      void (async () => {
+        for await (const event of stream) {
+          const now = Date.now();
+          if (now - (lastSent.get(id) ?? 0) < SAMPLE_INTERVAL_MS) continue; // THROTTLE
+          lastSent.set(id, now);
+          const rgba = event.frame.convert(VideoBufferType.RGBA);
+          const jpeg = await sharp(Buffer.from(rgba.data), {
+            raw: { width: rgba.width, height: rgba.height, channels: 4 },
+          })
+            .resize({ width: 1280, withoutEnlargement: true })
+            .jpeg({ quality: 70 })
+            .toBuffer();
+          await podman.onScreenFrame(id, jpeg);
+        }
+      })();
+    },
+  );
+
+  const shutdown = async () => {
+    await room.disconnect();
+    await dispose();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((e) => {
+  console.error('[agent] fatal', e);
+  process.exit(1);
+});

backend/src/agent/podman.ts

@@ -0,0 +1,75 @@
+import { RoomEvent, type Room } from '@livekit/rtc-node';
+import type { EngineerContext, Collision, Intervention, DataMessage } from '@podman/shared';
+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 { recallSimilar } from '../memory/vectors.js';
+import { shouldIntervene, preferredAction } from '../memory/policy.js';
+import { speak } from '../voice/live.js';
+
+export class PodMan {
+  private contexts = new Map<string, EngineerContext>();
+  private encoder = new TextEncoder();
+
+  constructor(
+    private room: Room,
+    private podId: string,
+  ) {}
+
+  async start(): Promise<void> {
+    // Tier-2 optional ground-truth + engineer ACKs arrive over the data channel.
+    this.room.on(RoomEvent.DataReceived, (payload) => {
+      try {
+        const msg = JSON.parse(new TextDecoder().decode(payload)) as DataMessage;
+        if (msg.type === 'GIT_REPORT') {
+          const c = this.contexts.get(msg.report.engineerId);
+          if (c) c.hasUnpushedChanges = msg.report.unpushedCount > 0 || msg.report.dirtyFiles.length > 0;
+        }
+      } catch { /* ignore malformed */ }
+    });
+  }
+
+  async onScreenFrame(engineerId: string, jpeg: Buffer): Promise<void> {
+    const ctx = await analyzeFrame(engineerId, this.podId, jpeg);
+    this.contexts.set(engineerId, ctx);
+    await recordObservation(ctx);
+
+    const github = await getGithubState(); // cached
+    const collisions = detectCollisions([...this.contexts.values()], github);
+    for (const collision of collisions) await this.handle(collision);
+  }
+
+  private async handle(collision: Collision): Promise<void> {
+    const prior = await recallSimilar(collision); // Loop A: vector recall raises confidence
+    if (prior) collision.severity = 'critical';
+    if (!shouldIntervene(collision, prior)) return; // Loop B: policy gate
+
+    await recordCollision(collision);
+    const action = preferredAction(collision, prior);
+    const names = collision.engineers.join(' and ');
+    const message = `${names} are both editing ${collision.file}` +
+      (collision.githubState?.unpushed ? ' and one has unpushed changes.' : '.') +
+      (prior ? ` I've seen this conflict pattern before.` : '');
+
+    const intervention: Intervention = {
+      id: `int_${Date.now()}`,
+      collisionId: collision.id,
+      podId: this.podId,
+      kind: 'card',
+      message,
+      suggestedAction: { kind: action },
+      status: 'pending',
+      createdAt: new Date().toISOString(),
+    };
+    await recordIntervention(intervention);
+
+    const data: DataMessage = { type: 'COLLISION', collision, intervention };
+    await this.room.localParticipant?.publishData(
+      this.encoder.encode(JSON.stringify(data)),
+      { reliable: true, topic: DATA_TOPIC },
+    );
+    await speak(this.room, message); // gemini-3.1-flash-live voice into the room
+  }
+}

backend/src/collision/detector.ts

@@ -1,50 +1,40 @@
-import type { Collision, EngineerContext, GithubStateSnapshot } from '@podman/shared';
+import type { EngineerContext, Collision, GithubStateSnapshot } from '@podman/shared';
+
+function normalize(path?: string): string | undefined {
+  if (!path) return undefined;
+  return path.replace(/^\.?\/?(src\/)?/, 'src/').toLowerCase();
+}
 
-/**
- * Fuse live engineer contexts (from vision) with GitHub state to find overlaps:
- * two or more engineers editing the same file — especially when unpushed.
- *
- * Pure function: easy to unit-test, no I/O. Callers supply the GitHub snapshot.
- */
 export function detectCollisions(
   contexts: EngineerContext[],
-  githubStateByFile: Record<string, GithubStateSnapshot> = {},
+  github: GithubStateSnapshot,
-  now: string = new Date().toISOString(),
 ): Collision[] {
   const byFile = new Map<string, EngineerContext[]>();
-  for (const ctx of contexts) {
+  for (const c of contexts) {
-    if (!ctx.currentFile) continue;
+    const f = normalize(c.currentFile);
-    const list = byFile.get(ctx.currentFile) ?? [];
+    if (!f) continue;
-    list.push(ctx);
+    (byFile.get(f) ?? byFile.set(f, []).get(f)!).push(c);
-    byFile.set(ctx.currentFile, list);
   }
 
-  const collisions: Collision[] = [];
+  const out: Collision[] = [];
   for (const [file, group] of byFile) {
-    if (group.length < 2) continue;
-
     const engineers = [...new Set(group.map((g) => g.engineerId))];
     if (engineers.length < 2) continue;
 
-    const github = githubStateByFile[file];
+    const anyUnpushed =
-    const unpushed = group.some((g) => g.hasUnpushedChanges) || github?.unpushed === true;
+      group.some((g) => g.hasUnpushedChanges) || github.unpushed === true;
-    const sharedSymbol = group.every(
+    if (!anyUnpushed) continue; // the crux GitHub alone cannot answer
-      (g) => g.currentSymbol && g.currentSymbol === group[0]!.currentSymbol,
-    )
-      ? group[0]!.currentSymbol
-      : undefined;
 
-    collisions.push({
+    out.push({
-      id: `${group[0]!.podId}:${file}:${engineers.sort().join(',')}`,
+      id: `col_${file}_${Date.now()}`,
       podId: group[0]!.podId,
       file,
-      symbol: sharedSymbol,
+      symbol: group.find((g) => g.currentSymbol)?.currentSymbol,
       engineers,
-      severity: unpushed ? 'critical' : sharedSymbol ? 'warn' : 'info',
+      severity: 'warn',
-      githubState: github,
+      githubState: { ...github, unpushed: anyUnpushed },
-      detectedAt: now,
+      detectedAt: new Date().toISOString(),
     });
   }
-
+  return out;
-  return collisions;
 }

backend/src/env.ts

@@ -1,39 +1,35 @@
 import 'dotenv/config';
 
-/** Reads an env var, throwing if it is required but missing. */
+function req(name: string): string {
-function read(name: string, required = false): string {
+  const v = process.env[name];
-  const value = process.env[name] ?? '';
+  if (!v) throw new Error(`Missing required env var: ${name}`);
-  if (required && !value) {
+  return v;
-    throw new Error(`Missing required env var: ${name}`);
+}
-  }
+function opt(name: string, fallback = ''): string {
-  return value;
+  return process.env[name] ?? fallback;
 }
 
 export const env = {
-  port: Number(process.env.PORT ?? 8787),
+  // LiveKit
-
+  LIVEKIT_URL: req('LIVEKIT_URL'),
-  livekit: {
+  LIVEKIT_API_KEY: req('LIVEKIT_API_KEY'),
-    url: read('LIVEKIT_URL'),
+  LIVEKIT_API_SECRET: req('LIVEKIT_API_SECRET'),
-    apiKey: read('LIVEKIT_API_KEY'),
+  // Gemini
-    apiSecret: read('LIVEKIT_API_SECRET'),
+  GEMINI_API_KEY: req('GEMINI_API_KEY'),
-  },
+  GEMINI_VISION_MODEL: opt('GEMINI_VISION_MODEL', 'gemini-3.5-flash'),
-
+  GEMINI_LIVE_MODEL: opt('GEMINI_LIVE_MODEL', 'gemini-3.1-flash-live-preview'),
-  gemini: {
+  // GitHub
-    apiKey: read('GEMINI_API_KEY'),
+  GITHUB_TOKEN: req('GITHUB_TOKEN'),
-    visionModel: process.env.GEMINI_VISION_MODEL ?? 'gemini-3.5-flash',
+  GITHUB_REPO: req('GITHUB_REPO'), // owner/name
-    liveModel: process.env.GEMINI_LIVE_MODEL ?? '',
+  // Mongo + Voyage
-  },
+  MONGODB_URI: req('MONGODB_URI'),
-
+  VOYAGE_API_KEY: opt('VOYAGE_API_KEY'),
-  github: {
+  // Server
-    token: read('GITHUB_TOKEN'),
+  PORT: Number(opt('PORT', '8787')),
-    repo: read('GITHUB_REPO'),
-  },
-
-  mongo: {
-    uri: read('MONGODB_URI'),
-  },
-
-  voyage: {
-    apiKey: read('VOYAGE_API_KEY'),
-  },
 } as const;
+
+export function repoParts(): { owner: string; repo: string } {
+  const [owner, repo] = env.GITHUB_REPO.split('/');
+  if (!owner || !repo) throw new Error('GITHUB_REPO must be "owner/name"');
+  return { owner, repo };
+}

backend/src/github/client.ts

@@ -1,25 +1,46 @@
 import { Octokit } from 'octokit';
 import type { GithubStateSnapshot } from '@podman/shared';
-import { env } from '../env.js';
+import { env, repoParts } from '../env.js';
 
-export const octokit: Octokit = new Octokit({ auth: env.github.token });
+const gh = new Octokit({ auth: env.GITHUB_TOKEN });
+let cache: { at: number; state: GithubStateSnapshot } | null = null;
+const TTL_MS = 5000;
 
-/**
+export async function getGithubState(): Promise<GithubStateSnapshot> {
- * Pull the GitHub state relevant to a file in the pod's repo: open branches
+  if (cache && Date.now() - cache.at < TTL_MS) return cache.state;
- * and PRs touching it. Fused with vision contexts by the collision detector.
+  const { owner, repo } = repoParts();
- *
+  const [{ data: branches }] = await Promise.all([
- * TODO(github): list branches/PRs, diff files, map commits -> engineer logins.
+    gh.rest.repos.listBranches({ owner, repo, per_page: 50 }),
- */
+  ]);
-export async function getStateForFile(_file: string): Promise<GithubStateSnapshot> {
+  const state: GithubStateSnapshot = {
-  return { branches: {}, openPrs: [], unpushed: false };
+    branches: Object.fromEntries(branches.map((b) => [b.name, b.commit.sha])),
+    openPrs: [],
+    unpushed: undefined, // vision/Tier-2 fills this; API cannot know
+  };
+  cache = { at: Date.now(), state };
+  return state;
 }
 
-/** Open a draft "sync PR" between two engineers' branches — the suggested action. */
+export async function remoteHasFile(path: string, ref = 'main'): Promise<boolean> {
-export async function openSyncPr(_params: {
+  const { owner, repo } = repoParts();
-  base: string;
+  return gh.rest.repos
-  head: string;
+    .getContent({ owner, repo, path, ref })
-  title: string;
+    .then(() => true)
-}): Promise<{ number: number; url: string } | null> {
+    .catch(() => false);
-  // TODO(github): octokit.rest.pulls.create({ ...env.github.repo, draft: true })
+}
-  return null;
+
+export async function createSyncPr(input: { headBranch: string; file: string; summary: string }) {
+  const { owner, repo } = repoParts();
+  const { data: mainRef } = await gh.rest.git.getRef({ owner, repo, ref: 'heads/main' });
+  const branch = `podman-sync-${Date.now()}`;
+  await gh.rest.git.createRef({ owner, repo, ref: `refs/heads/${branch}`, sha: mainRef.object.sha });
+  const { data: pr } = await gh.rest.pulls.create({
+    owner,
+    repo,
+    title: `PodMan: sync ${input.file} before collision`,
+    head: branch,
+    base: 'main',
+    body: input.summary,
+  });
+  return pr;
 }

backend/src/index.ts

@@ -1,35 +0,0 @@
-import express from 'express';
-import cors from 'cors';
-import { env } from './env.js';
-import { createPodToken } from './livekit/token.js';
-
-const app = express();
-app.use(cors());
-app.use(express.json());
-
-app.get('/health', (_req, res) => {
-  res.json({ ok: true, service: 'podman-backend' });
-});
-
-/**
- * Mint a LiveKit token for an engineer to join a pod room.
- * POST /pods/:podId/token  { identity, name }
- */
-app.post('/pods/:podId/token', async (req, res) => {
-  const { podId } = req.params;
-  const { identity, name } = req.body ?? {};
-  if (!identity) {
-    res.status(400).json({ error: 'identity is required' });
-    return;
-  }
-  try {
-    const token = await createPodToken(podId, identity, name);
-    res.json({ token, url: env.livekit.url });
-  } catch (err) {
-    res.status(500).json({ error: (err as Error).message });
-  }
-});
-
-app.listen(env.port, () => {
-  console.log(`[podman] backend listening on http://localhost:${env.port}`);
-});

backend/src/intervention/engine.ts

@@ -1,27 +0,0 @@
-import type { Collision, Intervention } from '@podman/shared';
-
-/**
- * Compose PodMan's intervention for a collision — the message it speaks and the
- * action it offers (e.g. "open a sync PR"). Severity drives voice vs card.
- *
- * TODO(brain): use Gemini to phrase the message naturally from the team model;
- * tune thresholds from outcomes (the continual-learning policy).
- */
-export function composeIntervention(
-  collision: Collision,
-  now: string = new Date().toISOString(),
-): Intervention {
-  const kind = collision.severity === 'critical' ? 'voice' : 'card';
-  return {
-    id: `intervention:${collision.id}`,
-    collisionId: collision.id,
-    podId: collision.podId,
-    kind,
-    message: `Heads up — ${collision.engineers.join(' and ')} are both in ${collision.file}.`,
-    suggestedAction: {
-      kind: collision.severity === 'critical' ? 'open_sync_pr' : 'ping_teammate',
-    },
-    status: 'pending',
-    createdAt: now,
-  };
-}

backend/src/livekit/token.ts

@@ -1,25 +0,0 @@
-import { AccessToken } from 'livekit-server-sdk';
-import { env } from '../env.js';
-
-/**
- * Mint a LiveKit access token so an engineer's browser can join a pod room
- * and publish screen + mic + cam tracks.
- */
-export async function createPodToken(
-  podId: string,
-  identity: string,
-  name?: string,
-): Promise<string> {
-  const at = new AccessToken(env.livekit.apiKey, env.livekit.apiSecret, {
-    identity,
-    name,
-  });
-  at.addGrant({
-    room: podId,
-    roomJoin: true,
-    canPublish: true,
-    canSubscribe: true,
-    canPublishData: true,
-  });
-  return at.toJwt();
-}

backend/src/memory/policy.ts

@@ -0,0 +1,23 @@
+import type { Collision, SuggestedActionKind } from '@podman/shared';
+
+/**
+ * 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';
+}
+
+/**
+ * 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 {
+  return collision.severity === 'critical' ? 'open_sync_pr' : 'ping_teammate';
+}

backend/src/memory/store.ts

@@ -1,12 +1,10 @@
-import type { EngineerContext, Intervention } from '@podman/shared';
+import type { EngineerContext, Collision, Intervention } from '@podman/shared';
+import type { InterventionOutcome } from '@podman/shared';
 
 /**
  * Continual-learning memory: persist observations + intervention outcomes to
  * MongoDB Atlas and embed file/feature notes into Voyage vectors so later
  * sessions are sharper ("more useful the more you use it").
- *
- * TODO(memory): connect Atlas, store observations, record outcomes, embed via
- * Voyage, and expose retrieval for the PodMan brain.
  */
 export interface PodMemory {
   recordObservation(ctx: EngineerContext): Promise<void>;
@@ -25,3 +23,25 @@ export function createInMemoryStore(): PodMemory {
     },
   };
 }
+
+// Standalone helpers used by the PodMan orchestrator and HTTP server.
+const _observations: EngineerContext[] = [];
+const _collisions: Collision[] = [];
+const _interventions: Intervention[] = [];
+const _outcomes: InterventionOutcome[] = [];
+
+export async function recordObservation(ctx: EngineerContext): Promise<void> {
+  _observations.push(ctx);
+}
+
+export async function recordCollision(collision: Collision): Promise<void> {
+  _collisions.push(collision);
+}
+
+export async function recordIntervention(intervention: Intervention): Promise<void> {
+  _interventions.push(intervention);
+}
+
+export async function recordOutcome(outcome: InterventionOutcome): Promise<void> {
+  _outcomes.push(outcome);
+}

backend/src/memory/vectors.ts

@@ -0,0 +1,10 @@
+import type { Collision } from '@podman/shared';
+
+/**
+ * Vector-based recall of prior collision patterns (Loop A).
+ * Stub: returns null until Voyage + Atlas Vector Search are wired.
+ */
+export async function recallSimilar(_collision: Collision): Promise<Collision | null> {
+  // TODO(memory): embed collision.file via Voyage, query Atlas vector index
+  return null;
+}

backend/src/server.ts

@@ -0,0 +1,59 @@
+import express from 'express';
+import { createServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { AccessToken } from 'livekit-server-sdk';
+import { env } from './env.js';
+import { createSyncPr } from './github/client.js';
+import { recordOutcome } from './memory/store.js';
+import type { InterventionOutcome } from '@podman/shared';
+
+const app = express();
+app.use(express.json());
+app.get('/health', (_req, res) => res.json({ ok: true }));
+
+// Mint a LiveKit token for an engineer joining a pod.
+app.post('/api/token', async (req, res) => {
+  const { room, identity, name, githubLogin } = req.body ?? {};
+  if (!room || !identity) return res.status(400).json({ error: 'room+identity required' });
+  const at = new AccessToken(env.LIVEKIT_API_KEY, env.LIVEKIT_API_SECRET, {
+    identity,
+    name,
+    ttl: '4h',
+    metadata: JSON.stringify({ githubLogin: githubLogin ?? name }),
+  });
+  at.addGrant({ roomJoin: true, room, canPublish: true, canSubscribe: true, canPublishData: true });
+  res.json({ token: await at.toJwt(), url: env.LIVEKIT_URL });
+});
+
+// PodMan's hero action: open a real sync PR on the PUBLIC repo.
+app.post('/api/sync-pr', async (req, res) => {
+  try {
+    const { headBranch, file, summary } = req.body ?? {};
+    const pr = await createSyncPr({ headBranch, file, summary });
+    res.json({ url: pr.html_url, number: pr.number });
+  } catch (e) {
+    res.status(500).json({ error: (e as Error).message });
+  }
+});
+
+// Outcome ACK -> closes the continual-learning policy loop.
+app.post('/api/outcome', async (req, res) => {
+  await recordOutcome(req.body as InterventionOutcome);
+  res.json({ ok: true });
+});
+
+const http = createServer(app);
+
+// ws relay: the agent pushes collision/intervention JSON here; PWAs subscribed by pod receive it.
+const wss = new WebSocketServer({ server: http, path: '/api/events' });
+const clients = new Set<import('ws').WebSocket>();
+wss.on('connection', (ws) => {
+  clients.add(ws);
+  ws.on('close', () => clients.delete(ws));
+  ws.on('message', (buf) => {
+    // fan out agent->PWA events; (auth/pod-scoping omitted for hackathon brevity)
+    for (const c of clients) if (c !== ws && c.readyState === 1) c.send(buf.toString());
+  });
+});
+
+http.listen(env.PORT, '0.0.0.0', () => console.log(`[server] :${env.PORT}`));

backend/src/vision/gemini.ts

@@ -1,20 +1,53 @@
+import { GoogleGenAI, MediaResolution, Type } from '@google/genai';
 import type { EngineerContext } from '@podman/shared';
+import { env } from '../env.js';
 
-/**
+const ai = new GoogleGenAI({ apiKey: env.GEMINI_API_KEY });
- * Turn a sampled screen frame into a structured EngineerContext using Gemini
+
- * vision. This is the headline capability: it produces the pre-push signal
+const SCHEMA = {
- * (which file/symbol an engineer is editing) that GitHub cannot see.
+  type: Type.OBJECT,
- *
+  properties: {
- * TODO(vision): wire @google/genai, downscale frames, sample ~1fps/on-change.
+    currentFile: { type: Type.STRING, description: 'open file path if visible, e.g. src/auth/session.ts' },
- */
+    currentSymbol: { type: Type.STRING, description: 'function/class under the cursor' },
-export async function frameToContext(
+    activity: { type: Type.STRING, description: 'editing | reading | debugging | terminal | PR review' },
-  _frame: Uint8Array,
+    hasUnpushedChanges: { type: Type.BOOLEAN, description: 'dirty git gutter / modified markers visible' },
-  meta: { engineerId: string; podId: string },
+    confidence: { type: Type.NUMBER, description: '0..1 confidence in this read' },
+  },
+  propertyOrdering: ['currentFile', 'currentSymbol', 'activity', 'hasUnpushedChanges', 'confidence'],
+} as const;
+
+export async function analyzeFrame(
+  engineerId: string,
+  podId: string,
+  jpeg: Buffer,
 ): Promise<EngineerContext> {
+  const res = await ai.models.generateContent({
+    model: env.GEMINI_VISION_MODEL,
+    contents: [
+      {
+        role: 'user',
+        parts: [
+          { text: "You are PodMan watching an engineer's screen. Identify what file/symbol they are working on and whether there are uncommitted edits. JSON only." },
+          { inlineData: { mimeType: 'image/jpeg', data: jpeg.toString('base64') } },
+        ],
+      },
+    ],
+    config: {
+      responseMimeType: 'application/json',
+      responseJsonSchema: SCHEMA,
+      thinkingConfig: { thinkingBudget: 0 }, // minimal thinking: low latency/cost for ambient loop
+      mediaResolution: MediaResolution.MEDIA_RESOLUTION_LOW,
+    },
+  });
+  const parsed = JSON.parse(res.text ?? '{}') as Partial<EngineerContext>;
   return {
-    engineerId: meta.engineerId,
+    engineerId,
-    podId: meta.podId,
+    podId,
-    confidence: 0,
+    currentFile: parsed.currentFile,
+    currentSymbol: parsed.currentSymbol,
+    activity: parsed.activity,
+    hasUnpushedChanges: parsed.hasUnpushedChanges,
+    confidence: parsed.confidence ?? 0.5,
     observedAt: new Date().toISOString(),
   };
 }

backend/src/voice/live.ts

@@ -0,0 +1,10 @@
+import type { Room } from '@livekit/rtc-node';
+
+/**
+ * Speak a message into the LiveKit room using Gemini Live voice.
+ * Stub: logs until Gemini Live audio track wiring is complete.
+ */
+export async function speak(_room: Room, message: string): Promise<void> {
+  // TODO(voice): use Gemini Live streaming TTS -> publish audio track into room
+  console.log(`[voice] ${message}`);
+}

database/init.ts

@@ -0,0 +1,41 @@
+import { MongoClient } from 'mongodb';
+
+const uri = process.env.MONGODB_URI!;
+const DB = 'podman';
+
+async function main() {
+  const client = new MongoClient(uri);
+  await client.connect();
+  const db = client.db(DB);
+
+  await db.collection('pods').createIndex({ id: 1 }, { unique: true });
+  // High-volume observations expire after 6h to keep the cluster light.
+  await db.collection('observations').createIndex({ observedAt: 1 }, { expireAfterSeconds: 21600 });
+  await db.collection('observations').createIndex({ podId: 1, engineerId: 1 });
+  await db.collection('collisions').createIndex({ podId: 1, detectedAt: -1 });
+  await db.collection('interventions').createIndex({ id: 1 }, { unique: true });
+  await db.collection('team_model').createIndex({ podId: 1 }, { unique: true });
+  await db.collection('policy').createIndex({ pattern: 1 }, { unique: true });
+
+  // Atlas Vector Search index for collision-pattern recall (Voyage voyage-3 = 1024 dims).
+  try {
+    await db.command({
+      createSearchIndexes: 'memory_vectors',
+      indexes: [
+        {
+          name: 'vector_index',
+          type: 'vectorSearch',
+          definition: {
+            fields: [{ type: 'vector', path: 'embedding', numDimensions: 1024, similarity: 'cosine' }],
+          },
+        },
+      ],
+    });
+  } catch (e) {
+    console.warn('vector index (create in Atlas UI if this errors):', (e as Error).message);
+  }
+
+  console.log('PodMan DB initialized.');
+  await client.close();
+}
+main().catch((e) => { console.error(e); process.exit(1); });

frontend/src/lib/api.ts

@@ -0,0 +1,29 @@
+import type { InterventionOutcome } from '@podman/shared';
+
+const BACKEND_URL = import.meta.env.VITE_BACKEND_URL || 'http://localhost:8787';
+
+/** Mint a LiveKit token from the backend. */
+export async function fetchToken(params: {
+  room: string;
+  identity: string;
+  name: string;
+  githubLogin?: string;
+}): Promise<{ token: string; url: string }> {
+  const res = await fetch(`${BACKEND_URL}/api/token`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(params),
+  });
+  if (!res.ok) throw new Error(`token request failed: ${res.status}`);
+  return res.json() as Promise<{ token: string; url: string }>;
+}
+
+/** Record an intervention outcome for the policy learning loop. */
+export async function postOutcome(outcome: InterventionOutcome): Promise<void> {
+  const res = await fetch(`${BACKEND_URL}/api/outcome`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(outcome),
+  });
+  if (!res.ok) throw new Error(`outcome post failed: ${res.status}`);
+}

frontend/src/livekit/useInterventions.ts

@@ -0,0 +1,39 @@
+import { useEffect, useState, useCallback } from 'react';
+import { RoomEvent, type Room } from 'livekit-client';
+import type { DataMessage, Intervention, InterventionStatus } from '@podman/shared';
+import { DATA_TOPIC } from '@podman/shared';
+import { postOutcome } from '../lib/api';
+
+export function useInterventions(room: Room | null) {
+  const [active, setActive] = useState<Intervention | 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);
+    };
+    room.on(RoomEvent.DataReceived, onData);
+    return () => { room.off(RoomEvent.DataReceived, onData); };
+  }, [room]);
+
+  const respond = useCallback(
+    async (status: InterventionStatus, accepted: boolean) => {
+      if (!active) return;
+      await postOutcome({
+        interventionId: active.id,
+        collisionId: active.collisionId,
+        podId: active.podId,
+        wasRealCollision: true,
+        accepted,
+        recordedAt: new Date().toISOString(),
+      });
+      setActive(null);
+      return status;
+    },
+    [active],
+  );
+
+  return { active, respond };
+}

frontend/src/livekit/useScreenPublish.ts

@@ -0,0 +1,38 @@
+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

@@ -0,0 +1,60 @@
+name: podman
+region: nyc
+
+static_sites:
+  - name: web
+    github:
+      repo: <org>/Podman
+      branch: main
+      deploy_on_push: true
+    source_dir: frontend
+    build_command: corepack enable && pnpm install --frozen-lockfile && pnpm --filter @podman/shared build && pnpm --filter @podman/frontend build
+    output_dir: dist
+    routes:
+      - path: /
+
+services:
+  - name: api
+    github:
+      repo: <org>/Podman
+      branch: main
+      deploy_on_push: true
+    source_dir: backend
+    build_command: corepack enable && pnpm install --frozen-lockfile && pnpm --filter @podman/shared build && pnpm --filter @podman/backend build
+    run_command: node dist/server.js
+    http_port: 8787
+    instance_size_slug: apps-s-1vcpu-1gb
+    instance_count: 1
+    routes:
+      - path: /api
+    envs:
+      - { key: LIVEKIT_URL, scope: RUN_TIME, type: SECRET }
+      - { key: LIVEKIT_API_KEY, scope: RUN_TIME, type: SECRET }
+      - { key: LIVEKIT_API_SECRET, scope: RUN_TIME, type: SECRET }
+      - { key: GITHUB_TOKEN, scope: RUN_TIME, type: SECRET }
+      - { key: GITHUB_REPO, scope: RUN_TIME, value: <org>/<public-repo> }
+      - { key: MONGODB_URI, scope: RUN_TIME, type: SECRET }
+
+workers:
+  - name: podman-agent
+    github:
+      repo: <org>/Podman
+      branch: main
+      deploy_on_push: true
+    source_dir: backend
+    build_command: corepack enable && pnpm install --frozen-lockfile && pnpm --filter @podman/shared build && pnpm --filter @podman/backend build
+    run_command: node dist/agent.js
+    instance_size_slug: apps-s-1vcpu-1gb
+    instance_count: 1
+    envs:
+      - { key: LIVEKIT_URL, scope: RUN_TIME, type: SECRET }
+      - { key: LIVEKIT_API_KEY, scope: RUN_TIME, type: SECRET }
+      - { 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-3.5-flash }
+      - { key: GEMINI_LIVE_MODEL, scope: RUN_TIME, value: gemini-3.1-flash-live-preview }
+      - { key: GITHUB_TOKEN, scope: RUN_TIME, type: SECRET }
+      - { key: GITHUB_REPO, scope: RUN_TIME, value: <org>/<public-repo> }
+      - { key: MONGODB_URI, scope: RUN_TIME, type: SECRET }
+      - { key: VOYAGE_API_KEY, scope: RUN_TIME, type: SECRET }
+      - { key: POD_ROOM, scope: RUN_TIME, value: demo-pod }

shared/src/index.ts

@@ -8,3 +8,4 @@ export type {
   SuggestedAction,
   SuggestedActionKind,
 } from './intervention.js';
+export * from './messages.js';

shared/src/messages.ts

@@ -0,0 +1,45 @@
+import type { Collision } from './collision.js';
+import type { Intervention, InterventionStatus } from './intervention.js';
+
+/** Topics multiplexed over the LiveKit data channel. */
+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: 'VOICE_CUE'; text: string }
+  | { type: 'ACK'; interventionId: string; status: InterventionStatus; note?: string }
+  | { type: 'GIT_REPORT'; report: LocalGitReport };
+
+/** Outcome of an intervention — the supervision signal for policy learning. */
+export interface InterventionOutcome {
+  interventionId: string;
+  collisionId: string;
+  podId: string;
+  /** Did the predicted collision turn out real? (engineer-confirmed or inferred). */
+  wasRealCollision: boolean;
+  /** Did the engineer accept the offered action (e.g. sync PR)? */
+  accepted: boolean;
+  recordedAt: string;
+}
+
+/** The continually-refined per-pod world model (Loop A). */
+export interface TeamModel {
+  podId: string;
+  /** filePath/dir -> engineerId most associated with it (de-facto owner). */
+  ownership: Record<string, string>;
+  /** Pairs of files that historically collide, with a co-occurrence weight. */
+  hotspots: Array<{ files: [string, string]; weight: number }>;
+  updatedAt: string;
+}
+
+/** OPTIONAL Tier-2 ground-truth from a per-laptop git sidecar. */
+export interface LocalGitReport {
+  engineerId: string;
+  branch: string;
+  /** Commits ahead of upstream (invisible to the GitHub API). */
+  unpushedCount: number;
+  /** Working-tree files with uncommitted edits. */
+  dirtyFiles: string[];
+  reportedAt: string;
+}