agent-relay 1.2.0 → 1.3.0

package/.trajectories/completed/2026-01/traj_t1yy8m7hbuxp.md

@@ -0,0 +1,32 @@
+# Trajectory: Implement GitHub repo permission API via Nango for dashboard access
+
+> **Status:** ✅ Completed
+> **Task:** agent-relay-460
+> **Confidence:** 90%
+> **Started:** January 5, 2026 at 10:10 PM
+> **Completed:** January 5, 2026 at 10:13 PM
+
+---
+
+## Summary
+
+Implemented GitHub repo permission API via Nango for dashboard access control. Added checkUserRepoAccess() and listUserAccessibleRepos() to NangoService, plus three API endpoints: GET /api/repos/check-access/:owner/:repo, GET /api/repos/accessible, POST /api/repos/check-access-bulk
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Implemented three new Nango-based API endpoints for GitHub repo permissions
+- **Chose:** Implemented three new Nango-based API endpoints for GitHub repo permissions
+- **Reasoning:** Used user's OAuth connection via Nango proxy to check repo access. Endpoints: /api/repos/check-access/:owner/:repo, /api/repos/accessible, /api/repos/check-access-bulk
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Implemented three new Nango-based API endpoints for GitHub repo permissions: Implemented three new Nango-based API endpoints for GitHub repo permissions

package/.trajectories/completed/2026-01/traj_tmux_orchestrator_analysis.json

@@ -0,0 +1,84 @@
+{
+  "id": "traj_tmux_orchestrator_analysis",
+  "title": "Tmux-Orchestrator competitive analysis",
+  "task": "analyze-tmux-orchestrator",
+  "status": "completed",
+  "startedAt": "2026-01-04T09:00:00.000Z",
+  "completedAt": "2026-01-04T09:30:00.000Z",
+  "confidence": 0.9,
+  "summary": "Competitive analysis of Tmux-Orchestrator validated our architecture - real-time messaging + continuity already covers their solutions",
+  "decisions": [
+    {
+      "decision": "Continuity context already works on spawn - no new feature needed",
+      "reasoning": "PtyWrapper.injectContinuityContext() already loads ledger + handoff and injects on agent spawn",
+      "timestamp": "2026-01-04T09:15:00.000Z"
+    },
+    {
+      "decision": "Use trajectories for learnings instead of separate learning repository",
+      "reasoning": "Trajectories already capture learnings via trail complete --learnings. Just need search functionality.",
+      "timestamp": "2026-01-04T09:20:00.000Z"
+    },
+    {
+      "decision": "Self-scheduling is the key missing feature for 24/7 autonomy",
+      "reasoning": "Tmux-Orchestrator's schedule_with_note.sh enables agents to wake themselves up. We need ->relay:schedule command.",
+      "timestamp": "2026-01-04T09:25:00.000Z"
+    },
+    {
+      "decision": "Skip git commit tracking - requires git worktree architecture we don't have",
+      "reasoning": "Tmux-Orchestrator's 30-minute commit rule assumes per-agent git worktrees. Not applicable to our current single-repo model.",
+      "timestamp": "2026-01-04T09:28:00.000Z"
+    },
+    {
+      "decision": "No beads needed - our architecture already covers their solutions",
+      "reasoning": "Self-scheduling solved by real-time messaging (agents wake each other). Context notes solved by continuity. Analysis validated our approach rather than finding gaps.",
+      "timestamp": "2026-01-04T09:35:00.000Z"
+    }
+  ],
+  "learnings": [
+    "Tmux-Orchestrator pioneered 24/7 autonomous agent operation using tmux persistence + self-scheduling",
+    "Real-time messaging replaces scheduling - agents can wake each other instantly instead of scheduling delayed self-messages",
+    "Our continuity system (ledger + handoff injection on spawn) covers their context notes pattern",
+    "Fixed 3-tier hierarchy (Orchestrator→PM→Engineer) solves context window limits but is less flexible than relay's any-topology approach",
+    "Shell script + timing delays (~500ms) is simpler but 100x slower than our Unix socket (<5ms)",
+    "Self-scheduling with context notes is the killer feature for autonomous operation",
+    "Our continuity system (ledger + handoff) already covers spawn context injection",
+    "Trajectory learnings field already exists - just need search/index functionality"
+  ],
+  "chapters": [
+    {
+      "phase": "plan",
+      "agent": "default",
+      "events": [
+        "Fetched Tmux-Orchestrator README and CLAUDE.md from GitHub",
+        "Reviewed existing competitive analyses format (GASTOWN.md, MCP_AGENT_MAIL.md)"
+      ]
+    },
+    {
+      "phase": "execute",
+      "agent": "default",
+      "events": [
+        "Created docs/competitive/TMUX_ORCHESTRATOR.md with full analysis",
+        "Updated OVERVIEW.md comparison matrix with Tmux-Orchestrator",
+        "Updated README.md with new analysis link"
+      ]
+    },
+    {
+      "phase": "execute",
+      "agent": "default",
+      "events": [
+        "Created 5 beads for features to adopt",
+        "Reviewed existing continuity system - found spawn context already works",
+        "Updated beads to reflect existing functionality"
+      ]
+    },
+    {
+      "phase": "review",
+      "agent": "default",
+      "events": [
+        "Confirmed PtyWrapper.injectContinuityContext() handles spawn context",
+        "Confirmed trajectories already capture learnings field",
+        "Identified self-scheduling as the truly new feature needed"
+      ]
+    }
+  ]
+}

package/.trajectories/completed/2026-01/traj_tmux_orchestrator_analysis.md

@@ -0,0 +1,109 @@
+# Trajectory: Tmux-Orchestrator competitive analysis
+
+> **Status:** Completed
+> **Task:** analyze-tmux-orchestrator
+> **Started:** January 4, 2026 at 09:00 AM
+> **Completed:** January 4, 2026 at 09:30 AM
+> **Confidence:** 0.9
+
+---
+
+## Summary
+
+Comprehensive competitive analysis of Tmux-Orchestrator vs Agent Relay, identified key features to adopt.
+
+---
+
+## Key Decisions
+
+### 1. Continuity context already works on spawn - no new feature needed
+- **Reasoning:** PtyWrapper.injectContinuityContext() already loads ledger + handoff and injects on agent spawn
+
+### 2. Use trajectories for learnings instead of separate learning repository
+- **Reasoning:** Trajectories already capture learnings via trail complete --learnings. Just need search functionality.
+
+### 3. Self-scheduling is the key missing feature for 24/7 autonomy
+- **Reasoning:** Tmux-Orchestrator's schedule_with_note.sh enables agents to wake themselves up. We need ->relay:schedule command.
+
+### 4. Skip git commit tracking - requires git worktree architecture we don't have
+- **Reasoning:** Tmux-Orchestrator's 30-minute commit rule assumes per-agent git worktrees. Not applicable to our current single-repo model.
+
+---
+
+## Learnings
+
+1. **Tmux-Orchestrator pioneered 24/7 autonomous agent operation** using tmux persistence + self-scheduling
+
+2. **Git commit tracking requires per-agent worktrees** - their 30-min rule isn't applicable without that architecture
+
+3. **Fixed 3-tier hierarchy** (Orchestrator→PM→Engineer) solves context window limits but is less flexible than relay's any-topology approach
+
+4. **Shell script + timing delays (~500ms)** is simpler but 100x slower than our Unix socket (<5ms)
+
+5. **Self-scheduling with context notes** is the killer feature for autonomous operation
+
+6. **Our continuity system already covers spawn context** - ledger + handoff injection works
+
+7. **Trajectory learnings field already exists** - just need search/index functionality
+
+---
+
+## Chapters
+
+### 1. Plan
+*Agent: default*
+
+- Fetched Tmux-Orchestrator README and CLAUDE.md from GitHub
+- Reviewed existing competitive analyses format (GASTOWN.md, MCP_AGENT_MAIL.md)
+
+### 2. Execute
+*Agent: default*
+
+- Created docs/competitive/TMUX_ORCHESTRATOR.md with full analysis
+- Updated OVERVIEW.md comparison matrix with Tmux-Orchestrator
+- Updated README.md with new analysis link
+
+### 3. Execute
+*Agent: default*
+
+- Created 5 beads for features to adopt
+- Reviewed existing continuity system - found spawn context already works
+- Updated beads to reflect existing functionality
+
+### 4. Review
+*Agent: default*
+
+- Confirmed PtyWrapper.injectContinuityContext() handles spawn context
+- Confirmed trajectories already capture learnings field
+- Identified self-scheduling as the truly new feature needed
+
+---
+
+## Beads Created
+
+**None** - Analysis validated our existing architecture covers their solutions.
+
+### What They Built vs What We Have
+
+| Their Solution | Our Solution |
+|----------------|--------------|
+| Self-scheduling (wake up) | Real-time messaging (agents wake each other) |
+| Context notes for spawn | Continuity injection (ledger + handoff) |
+| Git commit tracking | N/A (needs worktrees) |
+| LEARNINGS.md | Trajectories with learnings field |
+| ~500ms timing delays | <5ms Unix socket |
+
+### Key Insight
+Tmux-Orchestrator pioneered autonomous agents with shell scripts. Our architecture (real-time messaging + continuity) is the next evolution - we've already solved their problems more elegantly.
+
+---
+
+## Files Changed
+
+- `docs/competitive/TMUX_ORCHESTRATOR.md` - New analysis (600+ lines)
+- `docs/competitive/README.md` - Added to table
+- `docs/competitive/OVERVIEW.md` - Added to comparison matrix
+
+---
+
+*Trajectory completed 2026-01-04*

package/.trajectories/completed/2026-01/traj_u9n9eqasw16k.json

@@ -0,0 +1,53 @@
+{
+  "id": "traj_u9n9eqasw16k",
+  "version": 1,
+  "task": {
+    "title": "Backend trajectory data-loading fix review",
+    "source": {
+      "system": "plain",
+      "id": "backend-review"
+    }
+  },
+  "status": "completed",
+  "startedAt": "2026-01-03T14:40:11.376Z",
+  "agents": [
+    {
+      "name": "CodeReviewer",
+      "role": "lead",
+      "joinedAt": "2026-01-03T14:40:11.377Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_xfg9tvbm40wy",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-01-03T14:41:43.249Z",
+      "events": [
+        {
+          "ts": 1767451303250,
+          "type": "decision",
+          "content": "Active trajectories lose status coloring: Active trajectories lose status coloring",
+          "raw": {
+            "question": "Active trajectories lose status coloring",
+            "chosen": "Active trajectories lose status coloring",
+            "alternatives": [],
+            "reasoning": "mapEventStatus doesn't map 'active' so in-progress runs show no status indicator"
+          },
+          "significance": "high"
+        }
+      ],
+      "endedAt": "2026-01-03T14:41:50.001Z"
+    }
+  ],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/agent-workforce/relay",
+  "tags": [],
+  "completedAt": "2026-01-03T14:41:50.001Z",
+  "retrospective": {
+    "summary": "Reviewed backend filesystem trajectory loading; flagged missing 'active' status mapping",
+    "approach": "Standard approach",
+    "confidence": 0.78
+  }
+}

package/.trajectories/completed/2026-01/traj_u9n9eqasw16k.md

@@ -0,0 +1,32 @@
+# Trajectory: Backend trajectory data-loading fix review
+
+> **Status:** ✅ Completed
+> **Task:** backend-review
+> **Confidence:** 78%
+> **Started:** January 3, 2026 at 03:40 PM
+> **Completed:** January 3, 2026 at 03:41 PM
+
+---
+
+## Summary
+
+Reviewed backend filesystem trajectory loading; flagged missing 'active' status mapping
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Active trajectories lose status coloring
+- **Chose:** Active trajectories lose status coloring
+- **Reasoning:** mapEventStatus doesn't map 'active' so in-progress runs show no status indicator
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Active trajectories lose status coloring: Active trajectories lose status coloring

package/.trajectories/completed/2026-01/traj_ub8csuv3lcv4.json

@@ -0,0 +1,53 @@
+{
+  "id": "traj_ub8csuv3lcv4",
+  "version": 1,
+  "task": {
+    "title": "Fix WebSocket disconnections for workspace instances",
+    "source": {
+      "system": "plain",
+      "id": "workspace-websocket-stability"
+    }
+  },
+  "status": "completed",
+  "startedAt": "2026-01-06T18:13:23.603Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-01-06T18:13:35.723Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_e4vj0j8ig7ma",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-01-06T18:13:35.723Z",
+      "events": [
+        {
+          "ts": 1767723215725,
+          "type": "decision",
+          "content": "Add ping/pong keepalive to main and bridge WebSockets: Add ping/pong keepalive to main and bridge WebSockets",
+          "raw": {
+            "question": "Add ping/pong keepalive to main and bridge WebSockets",
+            "chosen": "Add ping/pong keepalive to main and bridge WebSockets",
+            "alternatives": [],
+            "reasoning": "Main dashboard and bridge WebSocket endpoints were missing ping/pong keepalive, while logs and presence endpoints had it. Without keepalive, TCP/proxy timeouts kill idle connections (typically 60-120s)."
+          },
+          "significance": "high"
+        }
+      ],
+      "endedAt": "2026-01-06T18:16:51.462Z"
+    }
+  ],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/home/user/relay",
+  "tags": [],
+  "completedAt": "2026-01-06T18:16:51.462Z",
+  "retrospective": {
+    "summary": "Added ping/pong keepalive to main and bridge WebSockets to fix connection instability",
+    "approach": "Standard approach",
+    "confidence": 0.9
+  }
+}

package/.trajectories/completed/2026-01/traj_ub8csuv3lcv4.md

@@ -0,0 +1,32 @@
+# Trajectory: Fix WebSocket disconnections for workspace instances
+
+> **Status:** ✅ Completed
+> **Task:** workspace-websocket-stability
+> **Confidence:** 90%
+> **Started:** January 6, 2026 at 06:13 PM
+> **Completed:** January 6, 2026 at 06:16 PM
+
+---
+
+## Summary
+
+Added ping/pong keepalive to main and bridge WebSockets to fix connection instability
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Add ping/pong keepalive to main and bridge WebSockets
+- **Chose:** Add ping/pong keepalive to main and bridge WebSockets
+- **Reasoning:** Main dashboard and bridge WebSocket endpoints were missing ping/pong keepalive, while logs and presence endpoints had it. Without keepalive, TCP/proxy timeouts kill idle connections (typically 60-120s).
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Add ping/pong keepalive to main and bridge WebSockets: Add ping/pong keepalive to main and bridge WebSockets

package/.trajectories/completed/2026-01/traj_uc29tlso8i9s.json

@@ -0,0 +1,186 @@
+{
+  "id": "traj_uc29tlso8i9s",
+  "version": 1,
+  "task": {
+    "title": "Production-ready SSH tunneling for Codex OAuth with security hardening"
+  },
+  "status": "completed",
+  "startedAt": "2026-01-07T10:08:04.299Z",
+  "agents": [
+    {
+      "name": "khaliqgant",
+      "role": "lead",
+      "joinedAt": "2026-01-07T10:08:04.300Z"
+    },
+    {
+      "name": "default",
+      "role": "contributor",
+      "joinedAt": "2026-01-07T10:08:04.710Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_8omowh9k21wa",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-01-07T10:08:04.710Z",
+      "events": [
+        {
+          "ts": 1767780484710,
+          "type": "decision",
+          "content": "Changed UsageBanner intro bonus from purple to cyan: Changed UsageBanner intro bonus from purple to cyan",
+          "raw": {
+            "question": "Changed UsageBanner intro bonus from purple to cyan",
+            "chosen": "Changed UsageBanner intro bonus from purple to cyan",
+            "alternatives": [],
+            "reasoning": "Brand consistency - cyan is primary accent color, purple was off-brand"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780493469,
+          "type": "decision",
+          "content": "Added landing page auth check - shows Go to App when logged in: Added landing page auth check - shows Go to App when logged in",
+          "raw": {
+            "question": "Added landing page auth check - shows Go to App when logged in",
+            "chosen": "Added landing page auth check - shows Go to App when logged in",
+            "alternatives": [],
+            "reasoning": "Better UX for returning users who shouldn't see Sign In buttons"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780494224,
+          "type": "decision",
+          "content": "Expose SSH port 2222 publicly on Fly.io via TCP service: Expose SSH port 2222 publicly on Fly.io via TCP service",
+          "raw": {
+            "question": "Expose SSH port 2222 publicly on Fly.io via TCP service",
+            "chosen": "Expose SSH port 2222 publicly on Fly.io via TCP service",
+            "alternatives": [],
+            "reasoning": "Internal .internal hostnames aren't routable from user machines. Public SSH with unique passwords per workspace is secure enough for production."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780500783,
+          "type": "decision",
+          "content": "Updated CTA terminal to show realistic CLI flow (cloud link + send): Updated CTA terminal to show realistic CLI flow (cloud link + send)",
+          "raw": {
+            "question": "Updated CTA terminal to show realistic CLI flow (cloud link + send)",
+            "chosen": "Updated CTA terminal to show realistic CLI flow (cloud link + send)",
+            "alternatives": [],
+            "reasoning": "Previous mock commands were inaccurate. Now shows actual agent-relay cloud commands"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780501007,
+          "type": "decision",
+          "content": "Use deterministic password derivation instead of storage: Use deterministic password derivation instead of storage",
+          "raw": {
+            "question": "Use deterministic password derivation instead of storage",
+            "chosen": "Use deterministic password derivation instead of storage",
+            "alternatives": [],
+            "reasoning": "SHA-256(workspaceId + salt) produces unique passwords without database storage. Both cloud server and container can derive the same password independently. 96 bits of entropy is sufficient."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780508469,
+          "type": "decision",
+          "content": "Create shared ssh-security.ts utility: Create shared ssh-security.ts utility",
+          "raw": {
+            "question": "Create shared ssh-security.ts utility",
+            "chosen": "Create shared ssh-security.ts utility",
+            "alternatives": [],
+            "reasoning": "Password derivation was duplicated in provisioner and codex-auth-helper. Single source of truth prevents bugs if algorithm changes. Also adds startup validation."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780510961,
+          "type": "decision",
+          "content": "Fixed TypeScript error: Promise<never> to Promise<void>: Fixed TypeScript error: Promise<never> to Promise<void>",
+          "raw": {
+            "question": "Fixed TypeScript error: Promise<never> to Promise<void>",
+            "chosen": "Fixed TypeScript error: Promise<never> to Promise<void>",
+            "alternatives": [],
+            "reasoning": "Promise<never> caused control flow analysis to mark subsequent code as unreachable"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780517965,
+          "type": "decision",
+          "content": "Keep password-based SSH for now, defer key-based auth: Keep password-based SSH for now, defer key-based auth",
+          "raw": {
+            "question": "Keep password-based SSH for now, defer key-based auth",
+            "chosen": "Keep password-based SSH for now, defer key-based auth",
+            "alternatives": [],
+            "reasoning": "Password-based is simpler to implement and per-workspace unique passwords provide reasonable security. Key-based auth would require container-side authorized_keys management - tracked as future improvement in agent-relay-476."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780523070,
+          "type": "decision",
+          "content": "Settings page: replaced sidebar with always-visible horizontal tabs: Settings page: replaced sidebar with always-visible horizontal tabs",
+          "raw": {
+            "question": "Settings page: replaced sidebar with always-visible horizontal tabs",
+            "chosen": "Settings page: replaced sidebar with always-visible horizontal tabs",
+            "alternatives": [],
+            "reasoning": "Desktop sidebar wasn't rendering for user. Horizontal tabs provide consistent navigation on all screen sizes"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780530293,
+          "type": "decision",
+          "content": "Billing API: respect database user.plan when no Stripe subscription: Billing API: respect database user.plan when no Stripe subscription",
+          "raw": {
+            "question": "Billing API: respect database user.plan when no Stripe subscription",
+            "chosen": "Billing API: respect database user.plan when no Stripe subscription",
+            "alternatives": [],
+            "reasoning": "Allows manual plan overrides in database to take effect without Stripe subscription"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780538628,
+          "type": "decision",
+          "content": "Billing panel: dynamic tier descriptions and smart plan recommendations: Billing panel: dynamic tier descriptions and smart plan recommendations",
+          "raw": {
+            "question": "Billing panel: dynamic tier descriptions and smart plan recommendations",
+            "chosen": "Billing panel: dynamic tier descriptions and smart plan recommendations",
+            "alternatives": [],
+            "reasoning": "Fixed hardcoded Free tier text. Only highlight upgrades, not downgrades (no Pro promotion to Team users)"
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1767780548294,
+          "type": "decision",
+          "content": "Aligned workspace Codex auth with /app onboarding: Aligned workspace Codex auth with /app onboarding",
+          "raw": {
+            "question": "Aligned workspace Codex auth with /app onboarding",
+            "chosen": "Aligned workspace Codex auth with /app onboarding",
+            "alternatives": [],
+            "reasoning": "Added supportsDeviceFlow prop to ProviderAuthFlow to match /app page props"
+          },
+          "significance": "high"
+        }
+      ],
+      "endedAt": "2026-01-07T10:09:10.870Z"
+    }
+  ],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/agent-workforce/relay",
+  "tags": [],
+  "completedAt": "2026-01-07T10:09:10.870Z",
+  "retrospective": {
+    "summary": "Implemented production-ready SSH tunneling for Codex OAuth. Key changes: (1) Exposed SSH port 2222 publicly on Fly.io via TCP service, (2) Changed from .internal to .fly.dev hostname for public routing, (3) Created shared ssh-security.ts with deterministic password derivation (SHA-256 of workspaceId + salt), (4) Added startup validation for SSH_PASSWORD_SALT env var, (5) Created beads for future improvements: rate limiting, key-based auth, time-limited access.",
+    "approach": "Standard approach",
+    "confidence": 0.85
+  }
+}

package/.trajectories/completed/2026-01/traj_uc29tlso8i9s.md

@@ -0,0 +1,86 @@
+# Trajectory: Production-ready SSH tunneling for Codex OAuth with security hardening
+
+> **Status:** ✅ Completed
+> **Confidence:** 85%
+> **Started:** January 7, 2026 at 11:08 AM
+> **Completed:** January 7, 2026 at 11:09 AM
+
+---
+
+## Summary
+
+Implemented production-ready SSH tunneling for Codex OAuth. Key changes: (1) Exposed SSH port 2222 publicly on Fly.io via TCP service, (2) Changed from .internal to .fly.dev hostname for public routing, (3) Created shared ssh-security.ts with deterministic password derivation (SHA-256 of workspaceId + salt), (4) Added startup validation for SSH_PASSWORD_SALT env var, (5) Created beads for future improvements: rate limiting, key-based auth, time-limited access.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Changed UsageBanner intro bonus from purple to cyan
+- **Chose:** Changed UsageBanner intro bonus from purple to cyan
+- **Reasoning:** Brand consistency - cyan is primary accent color, purple was off-brand
+
+### Added landing page auth check - shows Go to App when logged in
+- **Chose:** Added landing page auth check - shows Go to App when logged in
+- **Reasoning:** Better UX for returning users who shouldn't see Sign In buttons
+
+### Expose SSH port 2222 publicly on Fly.io via TCP service
+- **Chose:** Expose SSH port 2222 publicly on Fly.io via TCP service
+- **Reasoning:** Internal .internal hostnames aren't routable from user machines. Public SSH with unique passwords per workspace is secure enough for production.
+
+### Updated CTA terminal to show realistic CLI flow (cloud link + send)
+- **Chose:** Updated CTA terminal to show realistic CLI flow (cloud link + send)
+- **Reasoning:** Previous mock commands were inaccurate. Now shows actual agent-relay cloud commands
+
+### Use deterministic password derivation instead of storage
+- **Chose:** Use deterministic password derivation instead of storage
+- **Reasoning:** SHA-256(workspaceId + salt) produces unique passwords without database storage. Both cloud server and container can derive the same password independently. 96 bits of entropy is sufficient.
+
+### Create shared ssh-security.ts utility
+- **Chose:** Create shared ssh-security.ts utility
+- **Reasoning:** Password derivation was duplicated in provisioner and codex-auth-helper. Single source of truth prevents bugs if algorithm changes. Also adds startup validation.
+
+### Fixed TypeScript error: Promise<never> to Promise<void>
+- **Chose:** Fixed TypeScript error: Promise<never> to Promise<void>
+- **Reasoning:** Promise<never> caused control flow analysis to mark subsequent code as unreachable
+
+### Keep password-based SSH for now, defer key-based auth
+- **Chose:** Keep password-based SSH for now, defer key-based auth
+- **Reasoning:** Password-based is simpler to implement and per-workspace unique passwords provide reasonable security. Key-based auth would require container-side authorized_keys management - tracked as future improvement in agent-relay-476.
+
+### Settings page: replaced sidebar with always-visible horizontal tabs
+- **Chose:** Settings page: replaced sidebar with always-visible horizontal tabs
+- **Reasoning:** Desktop sidebar wasn't rendering for user. Horizontal tabs provide consistent navigation on all screen sizes
+
+### Billing API: respect database user.plan when no Stripe subscription
+- **Chose:** Billing API: respect database user.plan when no Stripe subscription
+- **Reasoning:** Allows manual plan overrides in database to take effect without Stripe subscription
+
+### Billing panel: dynamic tier descriptions and smart plan recommendations
+- **Chose:** Billing panel: dynamic tier descriptions and smart plan recommendations
+- **Reasoning:** Fixed hardcoded Free tier text. Only highlight upgrades, not downgrades (no Pro promotion to Team users)
+
+### Aligned workspace Codex auth with /app onboarding
+- **Chose:** Aligned workspace Codex auth with /app onboarding
+- **Reasoning:** Added supportsDeviceFlow prop to ProviderAuthFlow to match /app page props
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Changed UsageBanner intro bonus from purple to cyan: Changed UsageBanner intro bonus from purple to cyan
+- Added landing page auth check - shows Go to App when logged in: Added landing page auth check - shows Go to App when logged in
+- Expose SSH port 2222 publicly on Fly.io via TCP service: Expose SSH port 2222 publicly on Fly.io via TCP service
+- Updated CTA terminal to show realistic CLI flow (cloud link + send): Updated CTA terminal to show realistic CLI flow (cloud link + send)
+- Use deterministic password derivation instead of storage: Use deterministic password derivation instead of storage
+- Create shared ssh-security.ts utility: Create shared ssh-security.ts utility
+- Fixed TypeScript error: Promise<never> to Promise<void>: Fixed TypeScript error: Promise<never> to Promise<void>
+- Keep password-based SSH for now, defer key-based auth: Keep password-based SSH for now, defer key-based auth
+- Settings page: replaced sidebar with always-visible horizontal tabs: Settings page: replaced sidebar with always-visible horizontal tabs
+- Billing API: respect database user.plan when no Stripe subscription: Billing API: respect database user.plan when no Stripe subscription
+- Billing panel: dynamic tier descriptions and smart plan recommendations: Billing panel: dynamic tier descriptions and smart plan recommendations
+- Aligned workspace Codex auth with /app onboarding: Aligned workspace Codex auth with /app onboarding