feat: agent execution scaffold — sessions DB, API, and Browse/Agent/Terminal UI

Session model:
- agent_sessions table (auto-created on first use): id, project_id,
  app_name, app_path, task, status, output (JSONB log), changed_files,
  error, timestamps
- POST /agent/sessions — create session, fires off to agent-runner
  (gracefully degrades when runner not yet wired)
- GET  /agent/sessions — list sessions newest first
- GET  /agent/sessions/[id] — full session state for polling
- PATCH /agent/sessions/[id] — internal: agent-runner appends output lines
- POST /agent/sessions/[id]/stop — stop running session

Build > Code section now has three mode tabs:
- Browse — existing file tree + code viewer
- Agent — task input, session list sidebar, live output stream,
           changed files panel, Approve & commit / Open in Theia actions,
           2s polling (Phase 3 will replace with WebSocket)
- Terminal — xterm.js placeholder (Phase 4)

Architecture documented in AGENT_EXECUTION_ARCHITECTURE.md

Made-with: Cursor

app/[workspace]/project/[projectId]/build/page.tsx

@@ -209,6 +209,299 @@ function LayoutsContent({ surfaces, projectId, workspace, activeSurfaceId, onSel
   );
 }
 
+// ── Shared mode tab bar ───────────────────────────────────────────────────────
+
+type CodeMode = "browse" | "agent" | "terminal";
+
+function ModeTabs({ mode, onChange }: { mode: CodeMode; onChange: (m: CodeMode) => void }) {
+  const tabs: { id: CodeMode; label: string }[] = [
+    { id: "browse",   label: "Browse" },
+    { id: "agent",    label: "Agent" },
+    { id: "terminal", label: "Terminal" },
+  ];
+  return (
+    <div style={{ display: "flex", borderBottom: "1px solid #e8e4dc", background: "#fff", flexShrink: 0, padding: "0 16px" }}>
+      {tabs.map(t => (
+        <button key={t.id} onClick={() => onChange(t.id)} style={{
+          padding: "10px 14px", border: "none", background: "transparent", cursor: "pointer",
+          fontSize: "0.76rem", fontWeight: mode === t.id ? 600 : 450,
+          color: mode === t.id ? "#1a1a1a" : "#a09a90",
+          borderBottom: mode === t.id ? "2px solid #1a1a1a" : "2px solid transparent",
+          fontFamily: "Outfit, sans-serif", whiteSpace: "nowrap",
+        }}>
+          {t.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+// ── Agent mode ────────────────────────────────────────────────────────────────
+
+interface AgentSession {
+  id: string;
+  app_name: string;
+  task: string;
+  status: "pending" | "running" | "done" | "failed" | "stopped";
+  output: Array<{ ts: string; type: string; text: string }>;
+  changed_files: Array<{ path: string; status: string }>;
+  error: string | null;
+  created_at: string;
+  started_at: string | null;
+  completed_at: string | null;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  running: "#3d5afe", done: "#2e7d32", failed: "#c62828", stopped: "#a09a90", pending: "#d4a04a",
+};
+const STATUS_LABELS: Record<string, string> = {
+  running: "Running", done: "Done", failed: "Failed", stopped: "Stopped", pending: "Starting…",
+};
+const FILE_STATUS_COLORS: Record<string, string> = { added: "#2e7d32", modified: "#d4a04a", deleted: "#c62828" };
+
+function elapsed(start: string | null): string {
+  if (!start) return "";
+  const s = Math.floor((Date.now() - new Date(start).getTime()) / 1000);
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+}
+
+function AgentMode({ projectId, appName, appPath }: { projectId: string; appName: string; appPath: string }) {
+  const [task, setTask] = useState("");
+  const [sessions, setSessions] = useState<AgentSession[]>([]);
+  const [activeSessionId, setActiveSessionId] = useState<string | null>(null);
+  const [activeSession, setActiveSession] = useState<AgentSession | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [loadingSessions, setLoadingSessions] = useState(true);
+  const outputRef = useCallback((el: HTMLDivElement | null) => {
+    if (el) el.scrollTop = el.scrollHeight;
+  }, []);
+
+  // Load session list
+  useEffect(() => {
+    if (!appName) return;
+    setLoadingSessions(true);
+    fetch(`/api/projects/${projectId}/agent/sessions`)
+      .then(r => r.json())
+      .then(d => { setSessions(d.sessions ?? []); setLoadingSessions(false); })
+      .catch(() => setLoadingSessions(false));
+  }, [projectId, appName]);
+
+  // Poll active session
+  useEffect(() => {
+    if (!activeSessionId) return;
+    const poll = async () => {
+      const r = await fetch(`/api/projects/${projectId}/agent/sessions/${activeSessionId}`);
+      const d = await r.json();
+      if (d.session) setActiveSession(d.session);
+    };
+    poll();
+    const id = setInterval(() => {
+      poll();
+      if (activeSession?.status && !["running", "pending"].includes(activeSession.status)) clearInterval(id);
+    }, 2000);
+    return () => clearInterval(id);
+  }, [activeSessionId, projectId, activeSession?.status]);
+
+  const handleRun = async () => {
+    if (!task.trim() || !appName) return;
+    setSubmitting(true);
+    try {
+      const r = await fetch(`/api/projects/${projectId}/agent/sessions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ appName, appPath, task }),
+      });
+      const d = await r.json();
+      if (d.sessionId) {
+        setActiveSessionId(d.sessionId);
+        setTask("");
+        // Refresh list
+        const list = await fetch(`/api/projects/${projectId}/agent/sessions`).then(r2 => r2.json());
+        setSessions(list.sessions ?? []);
+      }
+    } finally { setSubmitting(false); }
+  };
+
+  const handleStop = async () => {
+    if (!activeSessionId) return;
+    await fetch(`/api/projects/${projectId}/agent/sessions/${activeSessionId}/stop`, { method: "POST" });
+    setActiveSession(prev => prev ? { ...prev, status: "stopped" } : null);
+  };
+
+  if (!appName) {
+    return (
+      <div style={{ flex: 1, display: "flex", alignItems: "center", justifyContent: "center", flexDirection: "column", gap: 10, padding: 40, textAlign: "center" }}>
+        <div style={{ fontSize: "0.88rem", fontWeight: 600, color: "#1a1a1a", fontFamily: "Outfit, sans-serif" }}>Select an app first</div>
+        <div style={{ fontSize: "0.78rem", color: "#a09a90", fontFamily: "Outfit, sans-serif" }}>Choose an app from the left nav to run agent tasks against it.</div>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ flex: 1, display: "flex", overflow: "hidden" }}>
+      {/* Session list sidebar */}
+      <div style={{ width: 220, flexShrink: 0, borderRight: "1px solid #e8e4dc", background: "#faf8f5", display: "flex", flexDirection: "column", overflow: "hidden" }}>
+        <div style={{ padding: "10px 12px 8px", borderBottom: "1px solid #e8e4dc", fontSize: "0.65rem", fontWeight: 700, color: "#a09a90", letterSpacing: "0.08em", textTransform: "uppercase", fontFamily: "Outfit, sans-serif" }}>
+          Sessions
+        </div>
+        <div style={{ flex: 1, overflow: "auto" }}>
+          {loadingSessions && <div style={{ padding: "12px", fontSize: "0.72rem", color: "#b5b0a6", fontFamily: "Outfit, sans-serif" }}>Loading…</div>}
+          {!loadingSessions && sessions.length === 0 && (
+            <div style={{ padding: "16px 12px", fontSize: "0.73rem", color: "#b5b0a6", fontFamily: "Outfit, sans-serif", lineHeight: 1.5 }}>No sessions yet. Run your first task below.</div>
+          )}
+          {sessions.map(s => (
+            <button key={s.id} onClick={() => { setActiveSessionId(s.id); setActiveSession(s); }} style={{
+              width: "100%", textAlign: "left", padding: "10px 12px", border: "none", cursor: "pointer",
+              background: activeSessionId === s.id ? "#f0ece4" : "transparent",
+              borderBottom: "1px solid #f0ece4",
+            }}
+              onMouseEnter={e => { if (activeSessionId !== s.id) (e.currentTarget as HTMLElement).style.background = "#f6f4f0"; }}
+              onMouseLeave={e => { if (activeSessionId !== s.id) (e.currentTarget as HTMLElement).style.background = "transparent"; }}
+            >
+              <div style={{ display: "flex", alignItems: "center", gap: 6, marginBottom: 3 }}>
+                <span style={{ width: 6, height: 6, borderRadius: "50%", background: STATUS_COLORS[s.status] ?? "#a09a90", flexShrink: 0, display: "inline-block" }} />
+                <span style={{ fontSize: "0.65rem", color: STATUS_COLORS[s.status] ?? "#a09a90", fontFamily: "Outfit, sans-serif", fontWeight: 600 }}>{STATUS_LABELS[s.status] ?? s.status}</span>
+              </div>
+              <div style={{ fontSize: "0.73rem", color: "#1a1a1a", fontFamily: "Outfit, sans-serif", overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{s.task}</div>
+              <div style={{ fontSize: "0.65rem", color: "#a09a90", marginTop: 2, fontFamily: "Outfit, sans-serif" }}>{new Date(s.created_at).toLocaleTimeString()}</div>
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* Main panel */}
+      <div style={{ flex: 1, display: "flex", flexDirection: "column", overflow: "hidden" }}>
+        {/* Active session view */}
+        {activeSession ? (
+          <>
+            {/* Session header */}
+            <div style={{ padding: "12px 20px", borderBottom: "1px solid #e8e4dc", background: "#fff", display: "flex", alignItems: "center", gap: 12, flexShrink: 0 }}>
+              <span style={{ width: 8, height: 8, borderRadius: "50%", background: STATUS_COLORS[activeSession.status], flexShrink: 0, display: "inline-block" }} />
+              <span style={{ fontSize: "0.8rem", fontWeight: 600, color: "#1a1a1a", fontFamily: "Outfit, sans-serif", flex: 1, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{activeSession.task}</span>
+              {activeSession.started_at && (
+                <span style={{ fontSize: "0.7rem", color: "#a09a90", fontFamily: "Outfit, sans-serif", whiteSpace: "nowrap" }}>
+                  {["running", "pending"].includes(activeSession.status) ? `${elapsed(activeSession.started_at)} elapsed` : elapsed(activeSession.started_at)}
+                </span>
+              )}
+              {["running", "pending"].includes(activeSession.status) && (
+                <button onClick={handleStop} style={{ padding: "4px 12px", background: "#fee2e2", color: "#c62828", border: "1px solid #fca5a5", borderRadius: 5, fontSize: "0.72rem", cursor: "pointer", fontFamily: "Outfit, sans-serif", whiteSpace: "nowrap" }}>
+                  Stop
+                </button>
+              )}
+            </div>
+
+            {/* Output stream */}
+            <div ref={outputRef} style={{ flex: 1, overflow: "auto", background: "#1a1a1a", padding: "16px 20px", fontFamily: "IBM Plex Mono, monospace", fontSize: "0.72rem", lineHeight: 1.6 }}>
+              {activeSession.output.length === 0 && (
+                <span style={{ color: "#555" }}>Starting agent…</span>
+              )}
+              {activeSession.output.map((line, i) => {
+                const color = line.type === "error" ? "#f87171" : line.type === "stderr" ? "#fb923c"
+                  : line.type === "info" ? "#60a5fa" : line.type === "step" ? "#a78bfa" : "#d4d4d4";
+                const prefix = line.type === "step" ? "▶ " : line.type === "error" ? "✗ "
+                  : line.type === "info" ? "→ " : "  ";
+                return (
+                  <div key={i} style={{ color, marginBottom: 1 }}>
+                    {prefix}{line.text}
+                  </div>
+                );
+              })}
+              {["running", "pending"].includes(activeSession.status) && (
+                <span style={{ color: "#555", animation: "pulse 1.5s infinite" }}>▌</span>
+              )}
+            </div>
+
+            {/* Changed files */}
+            {activeSession.changed_files.length > 0 && (
+              <div style={{ borderTop: "1px solid #e8e4dc", background: "#fff", padding: "12px 20px", flexShrink: 0 }}>
+                <div style={{ fontSize: "0.65rem", fontWeight: 700, color: "#a09a90", letterSpacing: "0.08em", textTransform: "uppercase", fontFamily: "Outfit, sans-serif", marginBottom: 8 }}>Changed Files</div>
+                <div style={{ display: "flex", flexWrap: "wrap", gap: 6 }}>
+                  {activeSession.changed_files.map((f, i) => (
+                    <div key={i} style={{ display: "flex", alignItems: "center", gap: 5, background: "#faf8f5", border: "1px solid #e8e4dc", borderRadius: 5, padding: "3px 8px" }}>
+                      <span style={{ color: FILE_STATUS_COLORS[f.status] ?? "#a09a90", fontSize: "0.65rem", fontWeight: 700 }}>{f.status === "added" ? "+" : f.status === "deleted" ? "−" : "~"}</span>
+                      <span style={{ fontFamily: "IBM Plex Mono, monospace", fontSize: "0.7rem", color: "#4a4640" }}>{f.path}</span>
+                    </div>
+                  ))}
+                </div>
+                {activeSession.status === "done" && (
+                  <div style={{ marginTop: 12, display: "flex", gap: 8 }}>
+                    <button style={{ padding: "7px 16px", background: "#1a1a1a", color: "#fff", border: "none", borderRadius: 7, fontSize: "0.75rem", fontWeight: 600, cursor: "pointer", fontFamily: "Outfit, sans-serif" }}>
+                      Approve &amp; commit
+                    </button>
+                    <button style={{ padding: "7px 16px", background: "#f0ece4", color: "#1a1a1a", border: "1px solid #e8e4dc", borderRadius: 7, fontSize: "0.75rem", cursor: "pointer", fontFamily: "Outfit, sans-serif" }}>
+                      Open in Theia →
+                    </button>
+                  </div>
+                )}
+              </div>
+            )}
+          </>
+        ) : (
+          <div style={{ flex: 1, display: "flex", alignItems: "center", justifyContent: "center", color: "#b5b0a6", fontSize: "0.8rem", fontFamily: "Outfit, sans-serif" }}>
+            Select a session or run a new task
+          </div>
+        )}
+
+        {/* Task input */}
+        <div style={{ borderTop: "1px solid #e8e4dc", background: "#fff", padding: "12px 16px", flexShrink: 0 }}>
+          <div style={{ display: "flex", gap: 8, alignItems: "flex-end" }}>
+            <textarea
+              value={task}
+              onChange={e => setTask(e.target.value)}
+              onKeyDown={e => { if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) handleRun(); }}
+              placeholder={`Tell the agent what to build in ${appName || "this app"}…`}
+              rows={2}
+              style={{
+                flex: 1, resize: "none", border: "1px solid #e8e4dc", borderRadius: 8,
+                padding: "9px 12px", fontSize: "0.8rem", fontFamily: "Outfit, sans-serif",
+                color: "#1a1a1a", outline: "none", background: "#faf8f5",
+              }}
+            />
+            <button
+              onClick={handleRun}
+              disabled={submitting || !task.trim()}
+              style={{
+                padding: "10px 18px", background: task.trim() ? "#1a1a1a" : "#e8e4dc",
+                color: task.trim() ? "#fff" : "#a09a90", border: "none", borderRadius: 8,
+                fontSize: "0.78rem", fontWeight: 600, cursor: task.trim() ? "pointer" : "default",
+                fontFamily: "Outfit, sans-serif", whiteSpace: "nowrap",
+              }}
+            >
+              {submitting ? "Starting…" : "Run"}
+            </button>
+          </div>
+          <div style={{ fontSize: "0.65rem", color: "#b5b0a6", marginTop: 5, fontFamily: "Outfit, sans-serif" }}>
+            ⌘↵ to run · Session persists if you close the browser
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ── Terminal mode (Phase 4 placeholder) ───────────────────────────────────────
+
+function TerminalMode({ appName }: { appName: string }) {
+  return (
+    <div style={{ flex: 1, display: "flex", flexDirection: "column", background: "#1a1a1a", overflow: "hidden" }}>
+      <div style={{ flex: 1, display: "flex", alignItems: "center", justifyContent: "center", flexDirection: "column", gap: 14, padding: 40, textAlign: "center" }}>
+        <div style={{ width: 52, height: 52, borderRadius: 13, background: "#252526", display: "flex", alignItems: "center", justifyContent: "center", fontSize: "1.3rem" }}>⌨</div>
+        <div>
+          <div style={{ fontSize: "0.88rem", fontWeight: 600, color: "#d4d4d4", marginBottom: 6, fontFamily: "Outfit, sans-serif" }}>Terminal — Phase 4</div>
+          <div style={{ fontSize: "0.78rem", color: "#6b6560", maxWidth: 300, lineHeight: 1.6, fontFamily: "Outfit, sans-serif" }}>
+            {appName
+              ? `A live shell into the ${appName} container via xterm.js + Theia PTY. Coming in Phase 4.`
+              : "Select an app first, then open a live shell into its container."}
+          </div>
+        </div>
+        <div style={{ marginTop: 4, padding: "7px 18px", background: "#252526", color: "#555", borderRadius: 7, fontSize: "0.77rem", fontFamily: "Outfit, sans-serif" }}>Coming in Phase 4</div>
+      </div>
+    </div>
+  );
+}
+
 // ── Code content (file browser) ───────────────────────────────────────────────
 
 function CodeContent({ projectId, appName, rootPath }: { projectId: string; appName: string; rootPath: string }) {
@@ -356,6 +649,12 @@ function BuildHubInner() {
 
   const setSection = (s: string) => router.push(`/${workspace}/project/${projectId}/build?section=${s}`, { scroll: false });
 
+  const codeMode = (searchParams.get("mode") as CodeMode | null) ?? "browse";
+  const setCodeMode = (m: CodeMode) => {
+    const sp = new URLSearchParams({ section: "code", ...(activeApp ? { app: activeApp, root: activeRoot } : {}), mode: m });
+    router.push(`/${workspace}/project/${projectId}/build?${sp.toString()}`, { scroll: false });
+  };
+
   return (
     <div style={{ display: "flex", height: "100%", fontFamily: "Outfit, sans-serif", overflow: "hidden" }}>
 
@@ -397,7 +696,12 @@ function BuildHubInner() {
       {/* ── Content ── */}
       <div style={{ flex: 1, display: "flex", flexDirection: "column", overflow: "hidden", minWidth: 0 }}>
         {section === "code" && (
-          <CodeContent projectId={projectId} appName={activeApp} rootPath={activeRoot} />
+          <div style={{ flex: 1, display: "flex", flexDirection: "column", overflow: "hidden" }}>
+            <ModeTabs mode={codeMode} onChange={setCodeMode} />
+            {codeMode === "browse"   && <CodeContent projectId={projectId} appName={activeApp} rootPath={activeRoot} />}
+            {codeMode === "agent"    && <AgentMode projectId={projectId} appName={activeApp} appPath={activeRoot} />}
+            {codeMode === "terminal" && <TerminalMode appName={activeApp} />}
+          </div>
         )}
         {section === "layouts" && (
           <LayoutsContent surfaces={surfaces} projectId={projectId} workspace={workspace} activeSurfaceId={activeSurfaceId} onSelectSurface={id => { setActiveSurfaceId(id); navigate({ section: "layouts", surface: id }); }} />

app/api/projects/[projectId]/agent/sessions/[sessionId]/route.ts

@@ -0,0 +1,118 @@
+/**
+ * GET  /api/projects/[projectId]/agent/sessions/[sessionId]
+ *   Fetch a session's full state — status, output log, changed files.
+ *   Frontend polls this (or will switch to WebSocket in Phase 3).
+ *
+ * POST /api/projects/[projectId]/agent/sessions/[sessionId]/stop
+ *   (handled in /stop/route.ts)
+ */
+import { NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { authOptions } from "@/lib/auth/authOptions";
+import { query } from "@/lib/db-postgres";
+
+export async function GET(
+  _req: Request,
+  { params }: { params: Promise<{ projectId: string; sessionId: string }> }
+) {
+  try {
+    const { projectId, sessionId } = await params;
+    const session = await getServerSession(authOptions);
+    if (!session?.user?.email) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    const rows = await query<{
+      id: string;
+      app_name: string;
+      app_path: string;
+      task: string;
+      plan: unknown;
+      status: string;
+      output: Array<{ ts: string; type: string; text: string }>;
+      changed_files: Array<{ path: string; status: string }>;
+      error: string | null;
+      created_at: string;
+      started_at: string | null;
+      completed_at: string | null;
+    }>(
+      `SELECT s.id, s.app_name, s.app_path, s.task, s.plan,
+              s.status, s.output, s.changed_files, s.error,
+              s.created_at, s.started_at, s.completed_at
+       FROM agent_sessions s
+       JOIN fs_projects p ON p.id = s.project_id
+       JOIN fs_users u ON u.id = p.user_id
+       WHERE s.id = $1 AND s.project_id = $2 AND u.data->>'email' = $3
+       LIMIT 1`,
+      [sessionId, projectId, session.user.email]
+    );
+
+    if (rows.length === 0) {
+      return NextResponse.json({ error: "Session not found" }, { status: 404 });
+    }
+
+    return NextResponse.json({ session: rows[0] });
+  } catch (err) {
+    console.error("[agent/sessions/[id] GET]", err);
+    return NextResponse.json({ error: "Failed to fetch session" }, { status: 500 });
+  }
+}
+
+export async function PATCH(
+  req: Request,
+  { params }: { params: Promise<{ projectId: string; sessionId: string }> }
+) {
+  /**
+   * Internal endpoint called by vibn-agent-runner to append output lines
+   * and update status. Not exposed to users directly.
+   *
+   * Body: { status?, outputLine?, changedFile? }
+   */
+  try {
+    const { sessionId } = await params;
+    const body = await req.json() as {
+      status?: string;
+      outputLine?: { ts: string; type: string; text: string };
+      changedFile?: { path: string; status: string };
+      error?: string;
+    };
+
+    const updates: string[] = ["updated_at = now()"];
+    const values: unknown[] = [];
+    let idx = 1;
+
+    if (body.status) {
+      updates.push(`status = $${idx++}`);
+      values.push(body.status);
+      if (body.status === "done" || body.status === "failed" || body.status === "stopped") {
+        updates.push(`completed_at = now()`);
+      }
+    }
+
+    if (body.error) {
+      updates.push(`error = $${idx++}`);
+      values.push(body.error);
+    }
+
+    if (body.outputLine) {
+      updates.push(`output = output || $${idx++}::jsonb`);
+      values.push(JSON.stringify([body.outputLine]));
+    }
+
+    if (body.changedFile) {
+      updates.push(`changed_files = changed_files || $${idx++}::jsonb`);
+      values.push(JSON.stringify([body.changedFile]));
+    }
+
+    values.push(sessionId);
+    await query(
+      `UPDATE agent_sessions SET ${updates.join(", ")} WHERE id = $${idx}`,
+      values
+    );
+
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    console.error("[agent/sessions/[id] PATCH]", err);
+    return NextResponse.json({ error: "Failed to update session" }, { status: 500 });
+  }
+}

app/api/projects/[projectId]/agent/sessions/[sessionId]/stop/route.ts

@@ -0,0 +1,57 @@
+import { NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { authOptions } from "@/lib/auth/authOptions";
+import { query } from "@/lib/db-postgres";
+
+const AGENT_RUNNER_URL = process.env.AGENT_RUNNER_URL ?? "http://localhost:3333";
+
+export async function POST(
+  _req: Request,
+  { params }: { params: Promise<{ projectId: string; sessionId: string }> }
+) {
+  try {
+    const { projectId, sessionId } = await params;
+    const session = await getServerSession(authOptions);
+    if (!session?.user?.email) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    // Verify ownership
+    const rows = await query<{ status: string }>(
+      `SELECT s.status FROM agent_sessions s
+       JOIN fs_projects p ON p.id = s.project_id
+       JOIN fs_users u ON u.id = p.user_id
+       WHERE s.id = $1 AND s.project_id = $2 AND u.data->>'email' = $3 LIMIT 1`,
+      [sessionId, projectId, session.user.email]
+    );
+
+    if (rows.length === 0) {
+      return NextResponse.json({ error: "Session not found" }, { status: 404 });
+    }
+
+    if (rows[0].status !== "running" && rows[0].status !== "pending") {
+      return NextResponse.json({ error: "Session is not running" }, { status: 400 });
+    }
+
+    // Tell the agent runner to stop (best-effort)
+    fetch(`${AGENT_RUNNER_URL}/agent/stop`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ sessionId }),
+    }).catch(() => {});
+
+    // Mark as stopped in DB immediately
+    await query(
+      `UPDATE agent_sessions
+       SET status = 'stopped', completed_at = now(), updated_at = now(),
+           output = output || '[{"ts": "now", "type": "info", "text": "Stopped by user."}]'::jsonb
+       WHERE id = $1`,
+      [sessionId]
+    );
+
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    console.error("[agent/sessions/stop]", err);
+    return NextResponse.json({ error: "Failed to stop session" }, { status: 500 });
+  }
+}

app/api/projects/[projectId]/agent/sessions/route.ts

@@ -0,0 +1,170 @@
+/**
+ * Agent Sessions API
+ *
+ * POST /api/projects/[projectId]/agent/sessions
+ *   Create a new agent session and kick it off via vibn-agent-runner.
+ *   Body: { appName, appPath, task }
+ *
+ * GET /api/projects/[projectId]/agent/sessions
+ *   List all sessions for a project, newest first.
+ */
+import { NextResponse } from "next/server";
+import { getServerSession } from "next-auth";
+import { authOptions } from "@/lib/auth/authOptions";
+import { query } from "@/lib/db-postgres";
+
+const AGENT_RUNNER_URL = process.env.AGENT_RUNNER_URL ?? "http://localhost:3333";
+
+// Ensure the agent_sessions table exists (idempotent).
+async function ensureTable() {
+  await query(`
+    CREATE TABLE IF NOT EXISTS agent_sessions (
+      id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      project_id      UUID NOT NULL,
+      app_name        TEXT NOT NULL,
+      app_path        TEXT NOT NULL,
+      task            TEXT NOT NULL,
+      plan            JSONB,
+      status          TEXT NOT NULL DEFAULT 'pending',
+      output          JSONB NOT NULL DEFAULT '[]'::jsonb,
+      changed_files   JSONB NOT NULL DEFAULT '[]'::jsonb,
+      error           TEXT,
+      started_at      TIMESTAMPTZ,
+      completed_at    TIMESTAMPTZ,
+      created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+      updated_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+    );
+    CREATE INDEX IF NOT EXISTS agent_sessions_project_idx
+      ON agent_sessions(project_id, created_at DESC);
+  `, []);
+}
+
+// ── POST — create session ────────────────────────────────────────────────────
+
+export async function POST(
+  req: Request,
+  { params }: { params: Promise<{ projectId: string }> }
+) {
+  try {
+    const { projectId } = await params;
+    const session = await getServerSession(authOptions);
+    if (!session?.user?.email) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    const body = await req.json();
+    const { appName, appPath, task } = body as {
+      appName: string;
+      appPath: string;
+      task: string;
+    };
+
+    if (!appName || !appPath || !task?.trim()) {
+      return NextResponse.json({ error: "appName, appPath and task are required" }, { status: 400 });
+    }
+
+    await ensureTable();
+
+    // Verify ownership
+    const owns = await query<{ id: string }>(
+      `SELECT p.id FROM fs_projects p
+       JOIN fs_users u ON u.id = p.user_id
+       WHERE p.id = $1 AND u.data->>'email' = $2 LIMIT 1`,
+      [projectId, session.user.email]
+    );
+    if (owns.length === 0) {
+      return NextResponse.json({ error: "Project not found" }, { status: 404 });
+    }
+
+    // Create the session row
+    const rows = await query<{ id: string }>(
+      `INSERT INTO agent_sessions (project_id, app_name, app_path, task, status, started_at)
+       VALUES ($1, $2, $3, $4, 'running', now())
+       RETURNING id`,
+      [projectId, appName, appPath, task.trim()]
+    );
+    const sessionId = rows[0].id;
+
+    // Fire-and-forget: call agent-runner to start the execution loop
+    // The agent runner is responsible for updating the session row as it works.
+    fetch(`${AGENT_RUNNER_URL}/agent/execute`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        sessionId,
+        projectId,
+        appName,
+        appPath,
+        task: task.trim(),
+      }),
+    }).catch(err => {
+      // Agent runner may not be wired yet — log but don't fail
+      console.warn("[agent] runner not reachable:", err.message);
+      // Mark session as failed if runner unreachable
+      query(
+        `UPDATE agent_sessions
+         SET status = 'failed',
+             error = 'Agent runner not reachable',
+             completed_at = now(),
+             output = jsonb_build_array(jsonb_build_object(
+               'ts', now()::text,
+               'type', 'error',
+               'text', 'Agent runner service is not connected yet. Phase 2 implementation pending.'
+             ))
+         WHERE id = $1`,
+        [sessionId]
+      ).catch(() => {});
+    });
+
+    return NextResponse.json({ sessionId }, { status: 201 });
+  } catch (err) {
+    console.error("[agent/sessions POST]", err);
+    return NextResponse.json({ error: "Failed to create session" }, { status: 500 });
+  }
+}
+
+// ── GET — list sessions ──────────────────────────────────────────────────────
+
+export async function GET(
+  req: Request,
+  { params }: { params: Promise<{ projectId: string }> }
+) {
+  try {
+    const { projectId } = await params;
+    const session = await getServerSession(authOptions);
+    if (!session?.user?.email) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    await ensureTable();
+
+    const sessions = await query<{
+      id: string;
+      app_name: string;
+      task: string;
+      status: string;
+      created_at: string;
+      started_at: string | null;
+      completed_at: string | null;
+      output: Array<{ ts: string; type: string; text: string }>;
+      changed_files: Array<{ path: string; status: string }>;
+      error: string | null;
+    }>(
+      `SELECT s.id, s.app_name, s.task, s.status,
+              s.created_at, s.started_at, s.completed_at,
+              s.output, s.changed_files, s.error
+       FROM agent_sessions s
+       JOIN fs_projects p ON p.id = s.project_id
+       JOIN fs_users u ON u.id = p.user_id
+       WHERE s.project_id = $1 AND u.data->>'email' = $2
+       ORDER BY s.created_at DESC
+       LIMIT 50`,
+      [projectId, session.user.email]
+    );
+
+    return NextResponse.json({ sessions });
+  } catch (err) {
+    console.error("[agent/sessions GET]", err);
+    return NextResponse.json({ error: "Failed to list sessions" }, { status: 500 });
+  }
+}