docs: Activity State Detection proposal for Progress Tracker sidecar

.claude/rules/react-dashboard.md

@@ -54,6 +54,38 @@ paths:
 - Handle loading and error states appropriately
 - Use `try/catch` for async operations
 
+## Next.js App Router
+
+- Pages using `useSearchParams()` MUST be wrapped in a `<Suspense>` boundary for static generation
+- Pattern: Create a `{Page}Content` component that uses the hook, wrap it in `<Suspense>` in the default export
+- Always provide a loading fallback component
+
+```tsx
+// Required pattern for useSearchParams
+import { Suspense } from 'react';
+import { useSearchParams } from 'next/navigation';
+
+function PageLoading() {
+  return <div>Loading...</div>;
+}
+
+function PageContent() {
+  const searchParams = useSearchParams();
+  const param = searchParams.get('param');
+  // ... component logic
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<PageLoading />}>
+      <PageContent />
+    </Suspense>
+  );
+}
+```
+
+- See `app/cloud/link/page.tsx` and `app/login/page.tsx` for examples
+
 ## Common Patterns
 
 ```tsx

.github/workflows/docker.yml

@@ -121,8 +121,14 @@ jobs:
   update-workspaces:
     runs-on: ubuntu-latest
     needs: [build-and-push]
-    # Only run on main branch pushes, not releases or manual runs
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    # Only run on main branch pushes when build-and-push succeeded
+    # Note: Can't use success() here because it checks the entire dependency chain,
+    # including build-base which is often skipped. Use explicit result check instead.
+    if: |
+      always() &&
+      needs.build-and-push.result == 'success' &&
+      github.event_name == 'push' &&
+      github.ref == 'refs/heads/main'
     steps:
       - name: Update workspace images
         env:
@@ -139,7 +145,7 @@ jobs:
           response=$(curl -s -w "\n%{http_code}" -X POST "${CLOUD_API_URL}/api/admin/workspaces/update-image" \
             -H "x-admin-secret: ${ADMIN_API_SECRET}" \
             -H "Content-Type: application/json" \
-            -d '{"image": "ghcr.io/agentworkforce/relay-workspace:latest", "skipRestart": true}')
+            -d '{"image": "ghcr.io/agentworkforce/relay-workspace:latest", "skipRestart": false}')
 
           http_code=$(echo "$response" | tail -n1)
           body=$(echo "$response" | sed '$d')

.github/workflows/migrations.yml

@@ -0,0 +1,64 @@
+name: Database Migrations
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/cloud/db/**'
+      - 'drizzle.config.ts'
+      - '.github/workflows/migrations.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'src/cloud/db/**'
+      - 'drizzle.config.ts'
+      - '.github/workflows/migrations.yml'
+  # Allow manual trigger
+  workflow_dispatch:
+
+jobs:
+  migrations:
+    name: Run Migrations
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: agent_relay
+          POSTGRES_PASSWORD: test_password
+          POSTGRES_DB: agent_relay_test
+        ports:
+          - 5432:5432
+        # Health check to wait for postgres to be ready
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Run migrations
+        env:
+          DATABASE_URL: postgres://agent_relay:test_password@localhost:5432/agent_relay_test
+        run: node scripts/run-migrations.js
+
+      - name: Verify schema
+        env:
+          DATABASE_URL: postgres://agent_relay:test_password@localhost:5432/agent_relay_test
+        run: node scripts/verify-schema.js

.trajectories/completed/2026-01/traj_oszg9flv74pk.json

@@ -0,0 +1,73 @@
+{
+  "id": "traj_oszg9flv74pk",
+  "version": 1,
+  "task": {
+    "title": "Fix cloud link authentication flow"
+  },
+  "status": "completed",
+  "startedAt": "2026-01-08T09:01:35.826Z",
+  "agents": [
+    {
+      "name": "khaliqgant",
+      "role": "lead",
+      "joinedAt": "2026-01-08T09:01:35.827Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_fnyyswrra94t",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-01-08T09:01:42.677Z",
+      "events": [
+        {
+          "ts": 1767862902677,
+          "type": "decision",
+          "content": "Fixed cloud link page auth check: Fixed cloud link page auth check",
+          "raw": {
+            "question": "Fixed cloud link page auth check",
+            "chosen": "Fixed cloud link page auth check",
+            "alternatives": [],
+            "reasoning": "checkAuth() was looking for data.userId but /api/auth/session returns { authenticated: true, user: { id } }. Changed to check data.authenticated && data.user?.id"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767862908073,
+          "type": "decision",
+          "content": "Added return URL support to login page: Added return URL support to login page",
+          "raw": {
+            "question": "Added return URL support to login page",
+            "chosen": "Added return URL support to login page",
+            "alternatives": [],
+            "reasoning": "Login page ignored ?return= query param, always redirecting to /app after auth. Added useSearchParams to read return URL and redirect back (e.g., to cloud link page)"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767862912381,
+          "type": "decision",
+          "content": "Wrapped login page in Suspense boundary: Wrapped login page in Suspense boundary",
+          "raw": {
+            "question": "Wrapped login page in Suspense boundary",
+            "chosen": "Wrapped login page in Suspense boundary",
+            "alternatives": [],
+            "reasoning": "useSearchParams requires Suspense for Next.js static generation. Created LoginContent component wrapped in Suspense with LoginLoading fallback"
+          },
+          "significance": "high"
+        }
+      ],
+      "endedAt": "2026-01-08T09:01:57.389Z"
+    }
+  ],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/agent-workforce/relay",
+  "tags": [],
+  "completedAt": "2026-01-08T09:01:57.389Z",
+  "retrospective": {
+    "summary": "Fixed two bugs in cloud link flow: 1) Auth check used wrong response shape 2) Login page ignored return URL param. Also added Suspense boundary for Next.js static gen.",
+    "approach": "Standard approach",
+    "confidence": 0.9
+  }
+}

.trajectories/completed/2026-01/traj_oszg9flv74pk.md

@@ -0,0 +1,41 @@
+# Trajectory: Fix cloud link authentication flow
+
+> **Status:** ✅ Completed
+> **Confidence:** 90%
+> **Started:** January 8, 2026 at 10:01 AM
+> **Completed:** January 8, 2026 at 10:01 AM
+
+---
+
+## Summary
+
+Fixed two bugs in cloud link flow: 1) Auth check used wrong response shape 2) Login page ignored return URL param. Also added Suspense boundary for Next.js static gen.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Fixed cloud link page auth check
+- **Chose:** Fixed cloud link page auth check
+- **Reasoning:** checkAuth() was looking for data.userId but /api/auth/session returns { authenticated: true, user: { id } }. Changed to check data.authenticated && data.user?.id
+
+### Added return URL support to login page
+- **Chose:** Added return URL support to login page
+- **Reasoning:** Login page ignored ?return= query param, always redirecting to /app after auth. Added useSearchParams to read return URL and redirect back (e.g., to cloud link page)
+
+### Wrapped login page in Suspense boundary
+- **Chose:** Wrapped login page in Suspense boundary
+- **Reasoning:** useSearchParams requires Suspense for Next.js static generation. Created LoginContent component wrapped in Suspense with LoginLoading fallback
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Fixed cloud link page auth check: Fixed cloud link page auth check
+- Added return URL support to login page: Added return URL support to login page
+- Wrapped login page in Suspense boundary: Wrapped login page in Suspense boundary

.trajectories/completed/2026-01/traj_rsavt0jipi3c.json

@@ -0,0 +1,109 @@
+{
+  "id": "traj_rsavt0jipi3c",
+  "version": 1,
+  "task": {
+    "title": "Power agent session - ready for tasks"
+  },
+  "status": "completed",
+  "startedAt": "2026-01-08T07:54:35.678Z",
+  "agents": [
+    {
+      "name": "khaliqgant",
+      "role": "lead",
+      "joinedAt": "2026-01-08T07:54:35.679Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_cgughl8lm8b5",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-01-08T08:04:56.261Z",
+      "events": [
+        {
+          "ts": 1767859496262,
+          "type": "decision",
+          "content": "Fixed cloud link auth flow - two bugs: Fixed cloud link auth flow - two bugs",
+          "raw": {
+            "question": "Fixed cloud link auth flow - two bugs",
+            "chosen": "Fixed cloud link auth flow - two bugs",
+            "alternatives": [],
+            "reasoning": "1) Cloud link page checked for data.userId but API returns data.authenticated + data.user.id. 2) Login page ignored return URL param, so after login it went to /app instead of back to cloud link page"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767859507874,
+          "type": "decision",
+          "content": "Fixed login page return URL support: Fixed login page return URL support",
+          "raw": {
+            "question": "Fixed login page return URL support",
+            "chosen": "Fixed login page return URL support",
+            "alternatives": [],
+            "reasoning": "Added useSearchParams to read return query param and redirect back after login instead of always going to /app"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767860361297,
+          "type": "decision",
+          "content": "Added Suspense boundary to login page: Added Suspense boundary to login page",
+          "raw": {
+            "question": "Added Suspense boundary to login page",
+            "chosen": "Added Suspense boundary to login page",
+            "alternatives": [],
+            "reasoning": "useSearchParams requires Suspense for Next.js static generation - wrapped LoginContent in Suspense with LoginLoading fallback"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767860499290,
+          "type": "decision",
+          "content": "Added useSearchParams/Suspense rule to react-dashboard.md: Added useSearchParams/Suspense rule to react-dashboard.md",
+          "raw": {
+            "question": "Added useSearchParams/Suspense rule to react-dashboard.md",
+            "chosen": "Added useSearchParams/Suspense rule to react-dashboard.md",
+            "alternatives": [],
+            "reasoning": "Prevents future build failures - useSearchParams requires Suspense boundary for Next.js static generation"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767861773992,
+          "type": "decision",
+          "content": "Changed update-workspaces condition to use explicit result check: Changed update-workspaces condition to use explicit result check",
+          "raw": {
+            "question": "Changed update-workspaces condition to use explicit result check",
+            "chosen": "Changed update-workspaces condition to use explicit result check",
+            "alternatives": [],
+            "reasoning": "success() checks entire dependency chain including skipped build-base. Using always() + needs.build-and-push.result == 'success' checks only direct dependency"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767862760607,
+          "type": "decision",
+          "content": "Changed skipRestart to false in update-workspaces: Changed skipRestart to false in update-workspaces",
+          "raw": {
+            "question": "Changed skipRestart to false in update-workspaces",
+            "chosen": "Changed skipRestart to false in update-workspaces",
+            "alternatives": [],
+            "reasoning": "If no active agents, workspace should restart immediately to apply new image since there's no work to disrupt"
+          },
+          "significance": "high"
+        }
+      ],
+      "endedAt": "2026-01-08T09:01:29.981Z"
+    }
+  ],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/agent-workforce/relay",
+  "tags": [],
+  "completedAt": "2026-01-08T09:01:29.981Z",
+  "retrospective": {
+    "summary": "General session - mixed work on cloud link auth, docker workflow, and React rules",
+    "approach": "Standard approach",
+    "confidence": 0.7
+  }
+}