uv-suite 0.28.0 → 0.30.0

package/skills/understand/modes/stack.md

@@ -0,0 +1,41 @@
+# Stack mode
+
+Map an entire tech stack — multiple services, how they connect, and the system-level
+architecture.
+
+The orchestrator has already loaded for you: the target (`$ARGUMENTS`), the chosen
+`MODE`, the session output directory, the target's CLAUDE.md / DANGER-ZONES.md, Graphify
+availability, the **service discovery + Dockerfile/infra/contract listings**, and any
+prior `map-stack.md` artifacts. Use them; don't re-fetch.
+
+## Process
+
+If Graphify is available (see the orchestrator's availability check), run
+`graphify run [target] --directed` for a unified cross-service graph and fold its
+findings into the map below.
+
+1. **Inventory every service** — name, language/framework, what it does, how it deploys.
+2. **Map connections BETWEEN services** — REST/HTTP base URLs and clients, gRPC/proto
+   stubs, message queues (Kafka/RabbitMQ/SQS topics), shared databases, shared internal
+   libraries, service URLs in env vars.
+3. **Trace the data flow** — where data enters, how it moves, where it ends up.
+
+## Output
+
+Write the full map to `map-stack.md` inside the session output directory printed by the
+orchestrator (e.g. `uv-out/sessions/<sid>/map-stack.md`), stamped with provenance
+frontmatter (`session`, `skill: understand`, `created`). Include:
+
+- A **System Architecture Diagram** (Mermaid): every service as a node, connections
+  labeled (REST, gRPC, Kafka, shared DB), external deps, data stores.
+- A **Stack Inventory Table**: Service | Language | Framework | Database | Deploys to | Depends on | Depended on by.
+- A **Connection Matrix**: which services talk to which, and how.
+- **Danger Zones**: single points of failure, high-inbound-dependency services, shared
+  databases, missing monitoring/health checks.
+
+## Report back
+
+After writing the file, print only a one-line pointer to the terminal — do not repeat
+the map. For example:
+
+> Map written to `uv-out/sessions/<sid>/map-stack.md` — go check it.

package/skills/uv-help/SKILL.md

@@ -28,8 +28,7 @@ Every skill accepts free-form arguments to direct the agent. Examples shown belo
 
 | Skill | What it does | Example |
 |-------|-------------|---------|
-| `/map-codebase [focus]` | Build a knowledge graph of the codebase | `/map-codebase focus on the auth flow and session management` |
-| `/map-stack [dir]` | Map multiple services and their connections | `/map-stack show how layer3-max calls layer2-pie` |
+| `/understand [target]` | Map a codebase or stack (auto-detects scope) | `/understand focus on the auth flow and session management` |
 
 ### Plan
 
@@ -42,8 +41,10 @@ Every skill accepts free-form arguments to direct the agent. Examples shown belo
 
 | Skill | What it does | Example |
 |-------|-------------|---------|
-| `/write-tests [target]` | Generate tests matching project conventions | `/write-tests src/auth/login.ts focus on error paths` |
-| `/write-evals [prompt]` | Write AI/LLM evaluation cases | `/write-evals test the search ranking prompt for adversarial inputs` |
+| `/test [target]` | Generate tests matching project conventions | `/test src/auth/login.ts focus on error paths` |
+| `/test --unit [target]` | Write unit tests | `/test --unit src/auth/login.ts focus on error paths` |
+| `/test --integration [target]` | Write integration tests | `/test --integration the checkout flow end to end` |
+| `/test --eval [prompt]` | Write AI/LLM evaluation cases | `/test --eval test the search ranking prompt for adversarial inputs` |
 | `/prototype [concept]` | Build a static React prototype | `/prototype event booking app with calendar and payment flow` |
 
 ### Review
@@ -51,8 +52,8 @@ Every skill accepts free-form arguments to direct the agent. Examples shown belo
 | Skill | What it does | Example |
 |-------|-------------|---------|
 | `/review [focus]` | Code review: correctness, security, perf, slop | `/review pay attention to the new database migration` |
-| `/slop-check [target]` | Detect 6 categories of AI-generated slop | `/slop-check src/components/ check for over-engineering` |
-| `/security-review [target]` | OWASP audit, dependency scan, secret detection | `/security-review src/payments/ focus on webhook signature validation` |
+| `/review --slop [target]` | Detect 6 categories of AI-generated slop | `/review --slop src/components/ check for over-engineering` |
+| `/review --security [target]` | OWASP audit, dependency scan, secret detection | `/review --security src/payments/ focus on webhook signature validation` |
 
 ### Ship
 
@@ -65,31 +66,45 @@ Every skill accepts free-form arguments to direct the agent. Examples shown belo
 
 | Skill | What it does | Example |
 |-------|-------------|---------|
-| `/checkpoint [label]` | Save session state for next time | `/checkpoint auth-refactor` |
-| `/restore` | Load latest checkpoint at session start | `/restore` |
+| `/session init` | Start a new session and set up artifacts | `/session init` |
+| `/session checkpoint [label]` | Save session state for next time | `/session checkpoint auth-refactor` |
+| `/session restore` | Load latest checkpoint at session start | `/session restore` |
+| `/session end` | Wrap up and persist final session state | `/session end` |
+| `/session auto` | Auto-checkpoint on a cadence during work | `/session auto` |
+
+### QA
+
+| Skill | What it does | Example |
+|-------|-------------|---------|
+| `/qa [target]` | Manual/exploratory QA of a change or flow | `/qa walk through the new checkout flow` |
+
+### Util
+
+| Skill | What it does | Example |
+|-------|-------------|---------|
+| `/confirm [question]` | Ask for explicit confirmation before acting | `/confirm before deleting the staging database` |
+| `/uv-help [topic]` | Show all UV Suite skills, agents, and hooks | `/uv-help review` |
 
 ## Agents (spawned by skills)
 
 | Agent | Model | Used by |
 |-------|-------|---------|
-| Cartographer | Opus | /map-codebase, /map-stack |
+| Cartographer | Opus | /understand |
 | Spec Writer | Opus | /spec |
 | Architect | Opus | /architect |
 | Reviewer | Opus | /review, /investigate |
-| Test Writer | Sonnet | /write-tests |
-| Eval Writer | Opus | /write-evals |
-| Anti-Slop Guard | Opus | /slop-check |
+| Test Writer | Sonnet | /test |
+| Eval Writer | Opus | /test --eval |
+| Anti-Slop Guard | Opus | /review --slop |
 | Prototype Builder | Sonnet | /prototype |
-| DevOps | Opus | (direct invocation) |
-| Security | Opus | /security-review |
 
 ## Hooks (automatic, you don't invoke these)
 
-!`ls .claude/hooks/*.sh 2>/dev/null | while read f; do echo "- $(basename $f)"; done || echo "No hooks installed"`
+!`ls .claude/hooks/ 2>/dev/null | grep '\.sh$' | sed 's/^/- /' || echo "No hooks installed"`
 
 ## Guardrails (anti-slop rules, active as context)
 
-!`ls .claude/rules/*.md 2>/dev/null | while read f; do echo "- $(basename $f .md)"; done || echo "No guardrails installed"`
+!`ls .claude/rules/ 2>/dev/null | sed -n 's/\.md$//p' | sed 's/^/- /' || echo "No guardrails installed"`
 
 ## Personas
 
@@ -102,13 +117,21 @@ Every skill accepts free-form arguments to direct the agent. Examples shown belo
 
 ## Artifacts
 
-All agent output goes to `uv-out/`. Agents read each other's prior output automatically.
+All agent output goes to `uv-out/sessions/<session-id>/`, so every artifact is attributable
+to the session that produced it; `uv-out/current` points at the active session. Skills read
+each other's prior output automatically (current session first, then prior sessions).
+
+### This session's artifacts
+
+!`ls -R uv-out/current 2>/dev/null | head -20 || echo "No artifacts yet — run a skill to generate some"`
+
+### All sessions
 
-!`ls uv-out/*.md uv-out/**/*.md 2>/dev/null | head -15 || echo "No artifacts yet — run a skill to generate some"`
+!`ls -1 uv-out/sessions 2>/dev/null | head -15 || echo "No sessions yet"`
 
 ## Tips
 
 - **Direct the agent:** Every skill accepts arguments. "/review" does a generic review. "/review focus on the error handling in the retry logic" gives targeted results.
-- **Run in parallel:** "Run /review, /slop-check, and /security-review in parallel" — Claude spawns all three simultaneously.
-- **Checkpoint before stopping:** "/checkpoint" saves your session state. "/restore" loads it next time.
+- **Run in parallel:** "Run /review, /review --slop, and /review --security in parallel" — Claude spawns all three simultaneously. `--slop` and `--security` are modes of `/review`, not separate skills. Ambient slop detection also runs automatically as a PostToolUse hook on every write.
+- **Checkpoint before stopping:** "/session checkpoint" saves your session state. "/session restore" loads it next time.
 - **Use the right persona:** `uvs spike` for research, `uvs pro` for production code, `uvs auto` to let it run.

package/uv.sh

@@ -44,7 +44,7 @@ case "$1" in
     echo "  Session metadata:"
     echo "    On launch you'll be prompted for name, kind, purpose, and"
     echo "    priority. Press Enter to skip any field; you'll be reminded"
-    echo "    until the session is named. Use /session-init to relabel."
+    echo "    until the session is named. Use /session init to relabel."
     echo "    Set UVS_NO_PROMPT=1 to suppress prompts entirely."
     echo ""
     exit 0
@@ -151,6 +151,39 @@ echo "$UVS_SESSION_ID" > "$STATE_DIR/current-session.txt"
 
 SETTINGS=".claude/personas/$PERSONA.json"
 
+# Launch the session, transparently wrapped in a tmux session so Watchtower
+# can attach to / observe the live session. Invisible to the user (status bar
+# off, lands them straight in the session). Falls back to a plain exec when
+# tmux is unavailable, UVS_NO_TMUX is set, or we're already inside the wrapper.
+launch_session() {
+  if command -v tmux >/dev/null 2>&1 && [ -z "$UVS_NO_TMUX" ] && [ -z "$UVS_IN_TMUX" ]; then
+    local socket="uvs"
+    local tname="uvs_$UVS_SESSION_ID"
+    local wt_url="${UVS_WATCHTOWER_URL:-http://localhost:4200}"
+
+    # Build the launch command, exporting the session id + re-entry guard and
+    # safely quoting every argument for the shell tmux spawns.
+    local launch_cmd
+    printf -v launch_cmd 'UVS_SESSION_ID=%q UVS_IN_TMUX=1 exec' "$UVS_SESSION_ID"
+    local arg
+    for arg in "$@"; do
+      printf -v launch_cmd '%s %q' "$launch_cmd" "$arg"
+    done
+
+    tmux -L "$socket" new-session -d -s "$tname" -c "$PWD" "$launch_cmd"
+    tmux -L "$socket" set -t "$tname" status off 2>/dev/null
+
+    curl -s "$wt_url/sessions/register" \
+      -H 'Content-Type: application/json' \
+      -d "{\"id\":\"$UVS_SESSION_ID\",\"tmux\":\"$tname\",\"pid\":$$,\"cwd\":\"$PWD\"}" \
+      >/dev/null 2>&1 || true
+
+    exec tmux -L "$socket" attach -t "$tname"
+  fi
+
+  exec "$@"
+}
+
 if [ "$TOOL" = "claude" ]; then
   # --- Claude Code ---
   if ! command -v claude &>/dev/null; then
@@ -167,7 +200,7 @@ if [ "$TOOL" = "claude" ]; then
   echo "UV Suite | Claude Code | $LABEL"
   echo "Session: ${UVS_SESSION_ID:0:8}${UVS_NAME:+ — $UVS_NAME}"
   echo ""
-  exec claude --settings "$SETTINGS" "$@"
+  launch_session claude --settings "$SETTINGS" "$@"
 
 elif [ "$TOOL" = "codex" ]; then
   # --- OpenAI Codex ---
@@ -188,5 +221,5 @@ elif [ "$TOOL" = "codex" ]; then
   echo "UV Suite | Codex | $LABEL"
   echo "Session: ${UVS_SESSION_ID:0:8}${UVS_NAME:+ — $UVS_NAME}"
   echo ""
-  exec codex $CODEX_ARGS "$@"
+  launch_session codex $CODEX_ARGS "$@"
 fi

package/watchtower/Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.12-slim
+WORKDIR /srv
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY schema.sql .
+COPY app ./app
+COPY static ./static
+EXPOSE 4200
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "4200"]

package/watchtower/README.md

@@ -0,0 +1,78 @@
+# Watchtower (Python control plane)
+
+Observability **and control** for UV Suite sessions. Hooks push events; the dashboard
+observes *and* acts — checkpoint a session, close it, or approve one that's blocked waiting
+for a human — from the browser.
+
+FastAPI + Postgres. A hook insert fires `pg_notify`; a listener forwards it to connected
+dashboards over WebSocket (no polling).
+
+## Run
+
+```bash
+cd watchtower
+docker compose up --build      # Postgres + the service on :4200
+# open http://localhost:4200
+```
+
+Local (without Docker), against your own Postgres:
+```bash
+export DATABASE_URL=postgresql://watchtower:watchtower@localhost:5432/watchtower
+uv run --with-requirements requirements.txt uvicorn app.main:app --host 127.0.0.1 --port 4200
+```
+> Bind control to **127.0.0.1** — the control API can checkpoint/kill/approve sessions.
+
+## How sessions become controllable
+
+`uvs <tool> <persona>` launches the session inside a transparent tmux (`tmux -L uvs`,
+status bar off) and registers it, so Watchtower can `send-keys`/`kill-session` against it.
+No tmux (or `UVS_NO_TMUX=1`) → plain launch; checkpoint still works (out-of-band), close
+works via PID, approve is unavailable from the UI.
+
+## API
+
+| Group | Endpoints |
+|---|---|
+| Ingest | `POST /events`, `POST /sessions/register`, `POST /approvals`, `POST /sessions/{id}/state` |
+| Query | `GET /sessions`, `/sessions/{id}`, `/sessions/{id}/events`, `/sessions/{id}/artifacts`, `/approvals?status=` |
+| Stream | `WS /live` |
+| Control | `POST /sessions/{id}/checkpoint \| close \| approve`, `POST /sessions/spawn` |
+
+## The three control actions
+- **Checkpoint** — out-of-band: built from recent events + git state, written to
+  `uv-out/sessions/<id>/checkpoints/`. Instant, works for any session.
+- **Close** — checkpoint, then `tmux kill-session` (owned) or `SIGTERM` (by PID).
+- **Approve** — a `Notification` hook reports the pending permission request; the dashboard
+  shows it; clicking Approve/Deny `send-keys` the answer into the session's pane.
+
+## Layout
+```
+app/
+  main.py            app wiring + lifespan + dashboard serving
+  db.py              asyncpg pool + NOTIFY → WebSocket broadcaster
+  models.py          request models
+  routers/           ingest.py · query.py · stream.py · control.py
+  services/          checkpoint.py (out-of-band) · tmux.py (send-keys/kill/capture)
+static/dashboard.html
+schema.sql · Dockerfile · docker-compose.yml · requirements.txt
+```
+
+## Status / follow-ups
+- The `Notification` hook (`hooks/watchtower-notify.sh`) still needs wiring into
+  `personas/*.json` (a `Notification` event entry) for approve to fire.
+- The approve keystroke map (`y`/`n`) is a placeholder — Claude Code's permission UI may
+  use arrow-select + Enter. Validate against the installed version (`capture_pane` shows it).
+- The semantic (haiku) checkpoint summary is a TODO; v1 checkpoints are mechanical.
+- Supersedes the old Node `server.js`/`dashboard.html`/`*-runner.js` (kept for now).
+
+## Legacy fallback (Node)
+
+The original Node Watchtower lives under `watchtower/legacy/` as a fallback that needs
+**no Docker/Postgres**:
+
+```bash
+uvs watch --legacy        # runs legacy/server.js on :4200 (flat events.json, SSE)
+```
+
+`uvs watch` (no flag) runs the Python service. The legacy one is observe-only (no control
+plane) and is kept while the Python service is validated in real use.

package/watchtower/app/db.py

@@ -0,0 +1,85 @@
+"""Async Postgres layer + a NOTIFY → WebSocket broadcaster.
+
+A hook insert calls `notify()` which `pg_notify`s on CHANNEL; a dedicated listener
+connection forwards each payload to the Broadcaster, which fans it out to connected
+WebSocket subscribers. No polling.
+"""
+import asyncio
+import json
+import os
+
+import asyncpg
+
+DATABASE_URL = os.environ.get(
+    "DATABASE_URL", "postgresql://watchtower:watchtower@localhost:5432/watchtower"
+)
+CHANNEL = "watchtower_events"
+SCHEMA_PATH = os.path.join(os.path.dirname(__file__), "..", "schema.sql")
+
+pool: asyncpg.Pool | None = None
+
+
+class Broadcaster:
+    """Fan out NOTIFY payloads (JSON strings) to subscribed WebSocket clients."""
+
+    def __init__(self) -> None:
+        self._subs: set[asyncio.Queue] = set()
+
+    def subscribe(self) -> asyncio.Queue:
+        q: asyncio.Queue = asyncio.Queue(maxsize=1000)
+        self._subs.add(q)
+        return q
+
+    def unsubscribe(self, q: asyncio.Queue) -> None:
+        self._subs.discard(q)
+
+    def publish(self, payload: str) -> None:
+        for q in list(self._subs):
+            try:
+                q.put_nowait(payload)
+            except asyncio.QueueFull:
+                pass  # slow consumer — drop rather than block ingest
+
+
+broadcaster = Broadcaster()
+
+
+async def init_pool() -> None:
+    global pool
+    async def _init(con):
+        await con.set_type_codec(
+            "jsonb", encoder=json.dumps, decoder=json.loads, schema="pg_catalog"
+        )
+
+    pool = await asyncpg.create_pool(DATABASE_URL, min_size=1, max_size=10, init=_init)
+    with open(SCHEMA_PATH) as f:
+        schema = f.read()
+    async with pool.acquire() as con:
+        await con.execute(schema)
+
+
+async def listen_notify() -> None:
+    """Dedicated connection LISTENing on CHANNEL; forwards payloads to the broadcaster."""
+    con = await asyncpg.connect(DATABASE_URL)
+    await con.add_listener(CHANNEL, lambda *args: broadcaster.publish(args[-1]))
+    try:
+        while True:
+            await asyncio.sleep(3600)
+    finally:
+        await con.close()
+
+
+async def close_pool() -> None:
+    if pool:
+        await pool.close()
+
+
+async def db() -> asyncpg.Connection:
+    """FastAPI dependency: yields a pooled connection."""
+    async with pool.acquire() as con:
+        yield con
+
+
+async def notify(con: asyncpg.Connection, payload: dict) -> None:
+    """Emit a NOTIFY so the stream router pushes this to dashboards."""
+    await con.execute("SELECT pg_notify($1, $2)", CHANNEL, json.dumps(payload, default=str))

package/watchtower/app/main.py

@@ -0,0 +1,45 @@
+"""Watchtower service entrypoint. Wires the routers built independently in app/routers/."""
+import asyncio
+import os
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from app import db
+from app.routers import control, ingest, query, stream
+
+STATIC_DIR = os.path.join(os.path.dirname(__file__), "..", "static")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await db.init_pool()
+    listener = asyncio.create_task(db.listen_notify())
+    try:
+        yield
+    finally:
+        listener.cancel()
+        await db.close_pool()
+
+
+app = FastAPI(title="Watchtower", version="1.0.0", lifespan=lifespan)
+
+app.include_router(ingest.router)
+app.include_router(query.router)
+app.include_router(stream.router)
+app.include_router(control.router)
+
+
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+
+@app.get("/")
+async def dashboard() -> FileResponse:
+    return FileResponse(os.path.join(STATIC_DIR, "dashboard.html"))
+
+
+@app.get("/health")
+async def health() -> dict:
+    return {"status": "ok"}

package/watchtower/app/models.py

@@ -0,0 +1,49 @@
+"""Request/response models. Kept permissive — hook payloads carry arbitrary extra keys."""
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+
+class EventIn(BaseModel):
+    """A hook event. Most fields arrive inside the raw hook JSON; we pull out the
+    common columns and keep the whole thing in `payload`."""
+    model_config = ConfigDict(extra="allow")
+
+    event_type: str = "Unknown"
+    uvs_session_id: str | None = None
+    tool_name: str | None = None
+    command: str | None = None
+
+
+class SessionRegister(BaseModel):
+    id: str
+    name: str | None = None
+    persona: str | None = None
+    cwd: str | None = None
+    worktree: str | None = None
+    branch: str | None = None
+    pid: int | None = None
+    tmux_target: str | None = None
+
+
+class StateUpdate(BaseModel):
+    state: Literal["active", "idle", "awaiting_human", "terminated"]
+
+
+class ApprovalIn(BaseModel):
+    session_id: str
+    tool_name: str | None = None
+    command: str | None = None
+    request: dict[str, Any] | None = None
+
+
+class ApprovalDecision(BaseModel):
+    decision: Literal["approve", "deny"]
+    decided_by: str | None = None
+
+
+class SpawnRequest(BaseModel):
+    tool: Literal["claude", "codex"] = "claude"
+    persona: str = "professional"
+    cwd: str | None = None
+    task: str | None = None

package/watchtower/app/routers/control.py

@@ -0,0 +1,144 @@
+"""Control router: drives sessions (spawn, close, approve, checkpoint).
+
+# SECURITY: these routes act on the host — they spawn processes, send keystrokes,
+# kill PIDs, and write files. They must NOT be exposed to the network. The service
+# is started with `--host 127.0.0.1`; keep it bound to localhost.
+"""
+import asyncio
+import os
+import shutil
+import signal
+import uuid
+
+import asyncpg
+from fastapi import APIRouter, Depends, HTTPException
+
+from app import db
+from app.models import ApprovalDecision, SpawnRequest
+from app.services import checkpoint, tmux
+
+router = APIRouter()
+
+# Claude Code's permission gate is a numbered arrow-select menu confirmed with Enter and
+# cancelled with Esc (verified live: the trust-folder and tool-permission prompts use the
+# same widget — it is NOT a y/n prompt). Approve = select option 1 ("Yes") + Enter;
+# deny = Esc. This is the one part coupled to the tool's TUI; revisit if the widget changes.
+
+
+async def _load_session(id: str, con: asyncpg.Connection) -> dict:
+    row = await con.fetchrow("SELECT * FROM sessions WHERE id = $1", id)
+    if row is None:
+        raise HTTPException(status_code=404, detail=f"session {id} not found")
+    return dict(row)
+
+
+@router.post("/sessions/{id}/checkpoint")
+async def checkpoint_session(id: str, con: asyncpg.Connection = Depends(db.db)) -> dict:
+    session = await _load_session(id, con)
+    path = await checkpoint.write_checkpoint(session)
+    await db.notify(con, {"type": "checkpoint", "session_id": id, "path": path})
+    return {"path": path}
+
+
+@router.post("/sessions/{id}/close")
+async def close_session(id: str, con: asyncpg.Connection = Depends(db.db)) -> dict:
+    session = await _load_session(id, con)
+
+    path = await checkpoint.write_checkpoint(session)
+
+    terminated_via = None
+    if session.get("tmux_target"):
+        await asyncio.to_thread(tmux.kill_session, session["tmux_target"])
+        terminated_via = "tmux"
+    elif session.get("pid"):
+        try:
+            os.kill(session["pid"], signal.SIGTERM)
+            terminated_via = "pid"
+        except ProcessLookupError:
+            terminated_via = "pid_gone"
+
+    await con.execute(
+        "UPDATE sessions SET state = 'terminated', ended_at = now() WHERE id = $1", id
+    )
+    await db.notify(con, {"type": "session", "session_id": id, "state": "terminated"})
+    return {"ok": True, "checkpoint": path, "terminated_via": terminated_via}
+
+
+@router.post("/sessions/{id}/approve")
+async def approve_session(
+    id: str, decision: ApprovalDecision, con: asyncpg.Connection = Depends(db.db)
+) -> dict:
+    session = await _load_session(id, con)
+
+    if not session.get("tmux_target"):
+        raise HTTPException(
+            status_code=400,
+            detail="session not owned by Watchtower; approve in the terminal",
+        )
+
+    approval = await con.fetchrow(
+        """SELECT id FROM approvals
+            WHERE session_id = $1 AND status = 'pending'
+         ORDER BY created_at DESC
+            LIMIT 1""",
+        id,
+    )
+    if approval is None:
+        raise HTTPException(status_code=404, detail="no pending approval for session")
+
+    target = session["tmux_target"]
+    # Read the current prompt before answering (surfaced for debugging / UI).
+    prompt = await asyncio.to_thread(tmux.capture_pane, target)
+    if decision.decision == "approve":
+        await asyncio.to_thread(tmux.send_keys, target, "1", True)        # select "Yes" + Enter
+    else:
+        await asyncio.to_thread(tmux.send_keys, target, "Escape", False)  # Esc cancels → reject
+
+    new_status = "approved" if decision.decision == "approve" else "denied"
+    await con.execute(
+        """UPDATE approvals
+              SET status = $2, decided_by = $3, decided_at = now()
+            WHERE id = $1""",
+        approval["id"], new_status, decision.decided_by,
+    )
+    await con.execute("UPDATE sessions SET state = 'active' WHERE id = $1", id)
+    await db.notify(con, {
+        "type": "approval",
+        "session_id": id,
+        "status": new_status,
+    })
+    return {"ok": True, "status": new_status, "prompt": prompt[-500:]}
+
+
+@router.post("/sessions/spawn")
+async def spawn_session(req: SpawnRequest, con: asyncpg.Connection = Depends(db.db)) -> dict:
+    if not tmux.has_tmux():
+        raise HTTPException(status_code=400, detail="tmux not available; cannot spawn")
+
+    id = uuid.uuid4().hex
+    cwd = req.cwd or os.getcwd()
+
+    # Prefer the real `uvs <tool> <persona>` launcher; fall back to the bare tool.
+    if shutil.which("uvs"):
+        launch = f"uvs {req.tool} {req.persona}"
+    else:
+        launch = req.tool
+    cmd = f"UVS_SESSION_ID={id} {launch}"
+
+    try:
+        target = await asyncio.to_thread(tmux.spawn, id, cmd, cwd)
+    except RuntimeError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    await con.execute(
+        """INSERT INTO sessions (id, persona, cwd, tmux_target, state)
+           VALUES ($1, $2, $3, $4, 'active')
+           ON CONFLICT (id) DO UPDATE SET
+             persona     = COALESCE($2, sessions.persona),
+             cwd         = COALESCE($3, sessions.cwd),
+             tmux_target = $4,
+             state       = 'active'""",
+        id, req.persona, cwd, target,
+    )
+    await db.notify(con, {"type": "session", "session_id": id, "state": "active"})
+    return {"id": id, "tmux_target": target}