fix: auto-refresh stale agent token on WebSocket failure

.trajectories/completed/2026-03/traj_dsxbsapslsw1.json

@@ -0,0 +1,25 @@
+{
+  "id": "traj_dsxbsapslsw1",
+  "version": 1,
+  "task": {
+    "title": "Fix PR #67 stale token refresh issues"
+  },
+  "status": "completed",
+  "startedAt": "2026-03-13T09:05:55.670Z",
+  "agents": [],
+  "chapters": [],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/relay-dashboard",
+  "tags": [],
+  "_trace": {
+    "startRef": "33cbb014460b89278818a04839905bbbffedf965",
+    "endRef": "33cbb014460b89278818a04839905bbbffedf965"
+  },
+  "completedAt": "2026-03-13T09:17:17.835Z",
+  "retrospective": {
+    "summary": "Fixed stale Relaycast token recovery by preserving refreshed identities in memory for file-backed configs, forcing refresh to bypass stale file tokens, and hardening the client recovery loop with retries, delayed forced refresh, and BroadcastChannel sync. Added server and provider regression tests.",
+    "approach": "Standard approach",
+    "confidence": 0.92
+  }
+}

.trajectories/completed/2026-03/traj_dsxbsapslsw1.md

@@ -0,0 +1,14 @@
+# Trajectory: Fix PR #67 stale token refresh issues
+
+> **Status:** ✅ Completed
+> **Confidence:** 92%
+> **Started:** March 13, 2026 at 10:05 AM
+> **Completed:** March 13, 2026 at 10:17 AM
+
+---
+
+## Summary
+
+Fixed stale Relaycast token recovery by preserving refreshed identities in memory for file-backed configs, forcing refresh to bypass stale file tokens, and hardening the client recovery loop with retries, delayed forced refresh, and BroadcastChannel sync. Added server and provider regression tests.
+
+**Approach:** Standard approach

.trajectories/completed/2026-03/traj_f2usn5o9quex.json

@@ -0,0 +1,25 @@
+{
+  "id": "traj_f2usn5o9quex",
+  "version": 1,
+  "task": {
+    "title": "Fix act warnings in orchestrator hook tests"
+  },
+  "status": "completed",
+  "startedAt": "2026-03-13T10:14:20.556Z",
+  "agents": [],
+  "chapters": [],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/relay-dashboard",
+  "tags": [],
+  "_trace": {
+    "startRef": "e030b271700ee089d621adee91a33065d8ba64c9",
+    "endRef": "e030b271700ee089d621adee91a33065d8ba64c9"
+  },
+  "completedAt": "2026-03-13T10:14:29.070Z",
+  "retrospective": {
+    "summary": "Removed useOrchestrator act warnings by using React Testing Library waitFor in the tests and revalidated the full dashboard suite.",
+    "approach": "Standard approach",
+    "confidence": 0.97
+  }
+}

.trajectories/completed/2026-03/traj_f2usn5o9quex.md

@@ -0,0 +1,14 @@
+# Trajectory: Fix act warnings in orchestrator hook tests
+
+> **Status:** ✅ Completed
+> **Confidence:** 97%
+> **Started:** March 13, 2026 at 11:14 AM
+> **Completed:** March 13, 2026 at 11:14 AM
+
+---
+
+## Summary
+
+Removed useOrchestrator act warnings by using React Testing Library waitFor in the tests and revalidated the full dashboard suite.
+
+**Approach:** Standard approach

.trajectories/completed/2026-03/traj_k9ydnx0mf6qs.json

@@ -0,0 +1,53 @@
+{
+  "id": "traj_k9ydnx0mf6qs",
+  "version": 1,
+  "task": {
+    "title": "Replace stale-token heuristics with deterministic Relaycast auth recovery"
+  },
+  "status": "completed",
+  "startedAt": "2026-03-13T09:27:01.188Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-03-13T09:34:52.649Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_7ejlsneroeje",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-03-13T09:34:52.649Z",
+      "events": [
+        {
+          "ts": 1773394492650,
+          "type": "decision",
+          "content": "Remove all dashboard-server reliance on file-backed Relaycast credentials and keep config strictly in memory/env/broker bootstrap.: Remove all dashboard-server reliance on file-backed Relaycast credentials and keep config strictly in memory/env/broker bootstrap.",
+          "raw": {
+            "question": "Remove all dashboard-server reliance on file-backed Relaycast credentials and keep config strictly in memory/env/broker bootstrap.",
+            "chosen": "Remove all dashboard-server reliance on file-backed Relaycast credentials and keep config strictly in memory/env/broker bootstrap.",
+            "alternatives": [],
+            "reasoning": "The product contract is that relaycast.json should not exist; reading it or passing it as an SDK cache path reintroduces hidden state and stale-token behavior"
+          },
+          "significance": "high"
+        }
+      ],
+      "endedAt": "2026-03-13T09:34:52.652Z"
+    }
+  ],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/relay-dashboard",
+  "tags": [],
+  "_trace": {
+    "startRef": "33cbb014460b89278818a04839905bbbffedf965",
+    "endRef": "33cbb014460b89278818a04839905bbbffedf965"
+  },
+  "completedAt": "2026-03-13T09:34:52.652Z",
+  "retrospective": {
+    "summary": "Removed relaycast.json from the dashboard server flow. Runtime config now comes only from in-memory/env/broker bootstrap, helper clients no longer point the SDK at a relaycast.json cache path, file-based error text was removed, and server tests were updated to validate the no-file credential flow. Verified dashboard-server typecheck and full test suite.",
+    "approach": "Standard approach",
+    "confidence": 0.95
+  }
+}

.trajectories/completed/2026-03/traj_k9ydnx0mf6qs.md

@@ -0,0 +1,31 @@
+# Trajectory: Replace stale-token heuristics with deterministic Relaycast auth recovery
+
+> **Status:** ✅ Completed
+> **Confidence:** 95%
+> **Started:** March 13, 2026 at 10:27 AM
+> **Completed:** March 13, 2026 at 10:34 AM
+
+---
+
+## Summary
+
+Removed relaycast.json from the dashboard server flow. Runtime config now comes only from in-memory/env/broker bootstrap, helper clients no longer point the SDK at a relaycast.json cache path, file-based error text was removed, and server tests were updated to validate the no-file credential flow. Verified dashboard-server typecheck and full test suite.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Remove all dashboard-server reliance on file-backed Relaycast credentials and keep config strictly in memory/env/broker bootstrap.
+- **Chose:** Remove all dashboard-server reliance on file-backed Relaycast credentials and keep config strictly in memory/env/broker bootstrap.
+- **Reasoning:** The product contract is that relaycast.json should not exist; reading it or passing it as an SDK cache path reintroduces hidden state and stale-token behavior
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Remove all dashboard-server reliance on file-backed Relaycast credentials and keep config strictly in memory/env/broker bootstrap.: Remove all dashboard-server reliance on file-backed Relaycast credentials and keep config strictly in memory/env/broker bootstrap.

.trajectories/completed/2026-03/traj_kc2cciszqofd.json

@@ -0,0 +1,53 @@
+{
+  "id": "traj_kc2cciszqofd",
+  "version": 1,
+  "task": {
+    "title": "Add integration tests for Relaycast token rotation recovery"
+  },
+  "status": "completed",
+  "startedAt": "2026-03-13T09:37:37.366Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-03-13T09:48:53.576Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_yua4vdj6ntlh",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-03-13T09:48:53.576Z",
+      "events": [
+        {
+          "ts": 1773395333577,
+          "type": "decision",
+          "content": "Added a real dashboard-provider integration test with a fake Relaycast backend: Added a real dashboard-provider integration test with a fake Relaycast backend",
+          "raw": {
+            "question": "Added a real dashboard-provider integration test with a fake Relaycast backend",
+            "chosen": "Added a real dashboard-provider integration test with a fake Relaycast backend",
+            "alternatives": [],
+            "reasoning": "This covers the real dashboard server, RelayConfigProvider, SDK HTTP retry path, and wsToken wiring without depending on external Relaycast infrastructure."
+          },
+          "significance": "high"
+        }
+      ],
+      "endedAt": "2026-03-13T09:48:59.904Z"
+    }
+  ],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/relay-dashboard",
+  "tags": [],
+  "_trace": {
+    "startRef": "108216be1a9b43c23125be078e9392f641676991",
+    "endRef": "108216be1a9b43c23125be078e9392f641676991"
+  },
+  "completedAt": "2026-03-13T09:48:59.904Z",
+  "retrospective": {
+    "summary": "Added dashboard integration coverage for Relaycast token invalidation and refresh.",
+    "approach": "Standard approach",
+    "confidence": 0.92
+  }
+}

.trajectories/completed/2026-03/traj_kc2cciszqofd.md

@@ -0,0 +1,31 @@
+# Trajectory: Add integration tests for Relaycast token rotation recovery
+
+> **Status:** ✅ Completed
+> **Confidence:** 92%
+> **Started:** March 13, 2026 at 10:37 AM
+> **Completed:** March 13, 2026 at 10:48 AM
+
+---
+
+## Summary
+
+Added dashboard integration coverage for Relaycast token invalidation and refresh.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Added a real dashboard-provider integration test with a fake Relaycast backend
+- **Chose:** Added a real dashboard-provider integration test with a fake Relaycast backend
+- **Reasoning:** This covers the real dashboard server, RelayConfigProvider, SDK HTTP retry path, and wsToken wiring without depending on external Relaycast infrastructure.
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Added a real dashboard-provider integration test with a fake Relaycast backend: Added a real dashboard-provider integration test with a fake Relaycast backend

.trajectories/completed/2026-03/traj_ytxbp9dpsji7.json

@@ -0,0 +1,25 @@
+{
+  "id": "traj_ytxbp9dpsji7",
+  "version": 1,
+  "task": {
+    "title": "Review PR #67 risk analysis"
+  },
+  "status": "completed",
+  "startedAt": "2026-03-13T08:55:30.959Z",
+  "agents": [],
+  "chapters": [],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/relay-dashboard",
+  "tags": [],
+  "_trace": {
+    "startRef": "33cbb014460b89278818a04839905bbbffedf965",
+    "endRef": "33cbb014460b89278818a04839905bbbffedf965"
+  },
+  "completedAt": "2026-03-13T09:03:47.730Z",
+  "retrospective": {
+    "summary": "Reviewed PR #67. Found a high-risk file-backed refresh gap and medium-risk retry/rotation behavior concerns. Verified both packages typecheck, dashboard tests pass, and dashboard-server tests pass when allowed to bind local ports.",
+    "approach": "Standard approach",
+    "confidence": 0.88
+  }
+}

.trajectories/completed/2026-03/traj_ytxbp9dpsji7.md

@@ -0,0 +1,14 @@
+# Trajectory: Review PR #67 risk analysis
+
+> **Status:** ✅ Completed
+> **Confidence:** 88%
+> **Started:** March 13, 2026 at 09:55 AM
+> **Completed:** March 13, 2026 at 10:03 AM
+
+---
+
+## Summary
+
+Reviewed PR #67. Found a high-risk file-backed refresh gap and medium-risk retry/rotation behavior concerns. Verified both packages typecheck, dashboard tests pass, and dashboard-server tests pass when allowed to bind local ports.
+
+**Approach:** Standard approach

.trajectories/index.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "lastUpdated": "2026-03-04T17:40:13.495Z",
+  "lastUpdated": "2026-03-13T10:14:29.128Z",
   "trajectories": {
     "traj_3q3jtxrg7enr": {
       "title": "Refactor channel system: remove legacy general broadcast, make Activity feed show events only, #general is real channel",
@@ -134,6 +134,41 @@
       "startedAt": "2026-03-04T17:39:54.323Z",
       "completedAt": "2026-03-04T17:40:13.402Z",
       "path": "/Users/khaliqgant/Projects/agent-workforce/relay-dashboard/.trajectories/completed/2026-03/traj_rn2cf74da1bo.json"
+    },
+    "traj_ytxbp9dpsji7": {
+      "title": "Review PR #67 risk analysis",
+      "status": "completed",
+      "startedAt": "2026-03-13T08:55:30.959Z",
+      "completedAt": "2026-03-13T09:03:47.730Z",
+      "path": "/Users/khaliqgant/Projects/relay-dashboard/.trajectories/completed/2026-03/traj_ytxbp9dpsji7.json"
+    },
+    "traj_dsxbsapslsw1": {
+      "title": "Fix PR #67 stale token refresh issues",
+      "status": "completed",
+      "startedAt": "2026-03-13T09:05:55.670Z",
+      "completedAt": "2026-03-13T09:17:17.835Z",
+      "path": "/Users/khaliqgant/Projects/relay-dashboard/.trajectories/completed/2026-03/traj_dsxbsapslsw1.json"
+    },
+    "traj_k9ydnx0mf6qs": {
+      "title": "Replace stale-token heuristics with deterministic Relaycast auth recovery",
+      "status": "completed",
+      "startedAt": "2026-03-13T09:27:01.188Z",
+      "completedAt": "2026-03-13T09:34:52.652Z",
+      "path": "/Users/khaliqgant/Projects/relay-dashboard/.trajectories/completed/2026-03/traj_k9ydnx0mf6qs.json"
+    },
+    "traj_kc2cciszqofd": {
+      "title": "Add integration tests for Relaycast token rotation recovery",
+      "status": "completed",
+      "startedAt": "2026-03-13T09:37:37.366Z",
+      "completedAt": "2026-03-13T09:48:59.904Z",
+      "path": "/Users/khaliqgant/Projects/relay-dashboard/.trajectories/completed/2026-03/traj_kc2cciszqofd.json"
+    },
+    "traj_f2usn5o9quex": {
+      "title": "Fix act warnings in orchestrator hook tests",
+      "status": "completed",
+      "startedAt": "2026-03-13T10:14:20.556Z",
+      "completedAt": "2026-03-13T10:14:29.070Z",
+      "path": "/Users/khaliqgant/Projects/relay-dashboard/.trajectories/completed/2026-03/traj_f2usn5o9quex.json"
     }
   }
 }

packages/dashboard-server/src/lib/types.ts

@@ -79,9 +79,9 @@ export interface DashboardServerOptions {
   relayUrl?: string;
   /** Path to static files directory (default: ../out) */
   staticDir?: string;
-  /** Data directory containing relaycast.json credentials */
+  /** Data directory for dashboard state such as logs and spawned agent metadata */
   dataDir?: string;
-  /** Relaycast API key — overrides relaycast.json and RELAY_API_KEY env var */
+  /** Relaycast API key — seeds the in-memory config and overrides RELAY_API_KEY env var */
   relayApiKey?: string;
   /** Enable verbose logging */
   verbose?: boolean;
@@ -115,6 +115,7 @@ export interface RouteContext {
   resolveRelaycastConfig: () => RelaycastConfig | null;
   setRelayApiKey: (apiKey: string) => void;
   setRelayAgentIdentity: (token: string, name: string) => void;
+  clearCachedAgentToken: () => void;
   getRelaycastSnapshot: () => Promise<DashboardSnapshot>;
   getRelaycastChannels: () => Promise<{ channels: DashboardChannel[]; archivedChannels: DashboardChannel[] }>;
   sendRelaycastMessage: (params: { to: string; message: string; from?: string; thread?: string }) => Promise<