Merge pull request #3 from ComposioHQ/main

merge

.changeset/fresh-fishes-help.md

@@ -1,12 +0,0 @@
----
-"@composio/ao-cli": patch
-"@composio/ao": patch
----
-
-Fix startup onboarding and install reliability:
-
-- Repair npm global install startup path by improving package resolution and web package discovery hints.
-- Make `ao start` prerequisite installs explicit and interactive for required tools (`tmux`, `git`) with clearer fallback guidance.
-- Keep `ao spawn` preflight check-only for `tmux` (no implicit install).
-- Remove redundant agent runtime re-detection during config generation.
-

.github/workflows/security.yml

@@ -22,13 +22,42 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0 # Full history for comprehensive scan
+          fetch-depth: 0 # Full history to ensure base/head SHAs are available for PR scans
+
+      - name: Install Gitleaks
+        run: |
+          set -euo pipefail
+          GITLEAKS_VERSION="8.24.3"
+          GITLEAKS_BASE_URL="https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}"
+          ARCHIVE_NAME="gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+
+          # Download gitleaks archive using the release filename so checksum verification works
+          curl -sSfL "${GITLEAKS_BASE_URL}/${ARCHIVE_NAME}" -o "${ARCHIVE_NAME}"
+
+          # Download the combined checksums file
+          curl -sSfL "${GITLEAKS_BASE_URL}/gitleaks_${GITLEAKS_VERSION}_checksums.txt" -o gitleaks_checksums.txt
+
+          # Verify checksum (sha256sum -c expects the filename in the checksums file to match the local file)
+          grep "${ARCHIVE_NAME}" gitleaks_checksums.txt | sha256sum -c -
+
+          # Extract the verified binary to a user-writable directory and add it to PATH
+          INSTALL_DIR="${RUNNER_TEMP}/gitleaks-bin"
+          mkdir -p "${INSTALL_DIR}"
+          tar -xzf "${ARCHIVE_NAME}" -C "${INSTALL_DIR}" gitleaks
+          echo "${INSTALL_DIR}" >> "${GITHUB_PATH}"
+
+          # Clean up
+          rm -f "${ARCHIVE_NAME}" gitleaks_checksums.txt
 
       - name: Run Gitleaks
-        uses: gitleaks/gitleaks-action@v2
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            # Ensure the base and head SHAs exist locally when checkout uses the PR merge ref
+            git fetch origin ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }} --depth=1
+            gitleaks detect --source . --verbose --log-opts "${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}"
+          else
+            gitleaks detect --source . --verbose
+          fi
 
   dependency-review:
     name: Dependency Review

agent-orchestrator.yaml.example

@@ -24,7 +24,7 @@ defaults:
   # worker:
   #   agent: codex
   workspace: worktree     # worktree | clone | copy
-  notifiers: [desktop]    # desktop | slack | discord | webhook | email
+  notifiers: [desktop]    # desktop | slack | discord | webhook | email | openclaw
 
 # Projects — at minimum, specify repo and path
 projects:
@@ -99,6 +99,14 @@ projects:
 #     plugin: slack
 #     webhook: ${SLACK_WEBHOOK_URL}
 #     channel: "#agent-updates"
+#
+#   openclaw:
+#     plugin: openclaw
+#     url: http://127.0.0.1:18789/hooks/agent  # Use https:// for remote (non-localhost) deployments
+#     token: ${OPENCLAW_HOOKS_TOKEN}
+#     retries: 3
+#     retryDelayMs: 1000
+#     wakeMode: now
 
 # Notification routing by priority
 # notificationRouting:

docs/openclaw-plugin-setup.md

@@ -0,0 +1,196 @@
+# OpenClaw Plugin Setup Guide
+
+How to set up the Agent Orchestrator (AO) plugin for OpenClaw so the AI bot delegates all coding work to AO agents.
+
+## Prerequisites
+
+- [OpenClaw](https://openclaw.ai) installed and running
+- [Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator) installed with `ao init` completed in your repo
+- `ao`, `gh`, `tmux`, and `node` available in PATH
+- GitHub CLI (`gh`) authenticated
+
+## 1. Install the Plugin
+
+```bash
+# From the agent-orchestrator repo
+cd openclaw-plugin
+openclaw plugins install .
+```
+
+Or manually copy the plugin files:
+
+```bash
+mkdir -p ~/.openclaw/extensions/agent-orchestrator
+cp openclaw-plugin/index.ts ~/.openclaw/extensions/agent-orchestrator/
+cp openclaw-plugin/openclaw.plugin.json ~/.openclaw/extensions/agent-orchestrator/
+cp openclaw-plugin/package.json ~/.openclaw/extensions/agent-orchestrator/
+```
+
+## 2. Install the Skill
+
+```bash
+mkdir -p ~/.openclaw/extensions/skills/agent-orchestrator
+cp skills/agent-orchestrator/SKILL.md ~/.openclaw/extensions/skills/agent-orchestrator/
+cp -r skills/agent-orchestrator/references ~/.openclaw/extensions/skills/agent-orchestrator/ 2>/dev/null
+```
+
+## 3. Configure OpenClaw
+
+Run `/ao setup` in any OpenClaw channel to auto-configure, or run these commands manually:
+
+### Required Settings
+
+```bash
+# 1. Plugin tools need "full" profile to be visible to the AI
+#    The "coding" profile only includes built-in tools, NOT plugin tools
+openclaw config set tools.profile "full"
+
+# 2. Plugin tools are optional by default — explicitly allow them
+openclaw config set tools.allow '["group:plugins"]'
+
+# 3. Trust the plugin
+openclaw config set plugins.allow '["agent-orchestrator"]'
+```
+
+### Required: Disable Conflicting Built-in Skills
+
+**Without these, the bot may ignore AO and write code directly.** Run once after setup:
+
+```bash
+# Prevent the bot from writing code directly — it should delegate to AO instead
+openclaw config set tools.deny '["exec", "write", "str_replace_based_edit_tool", "create_file", "str_replace_editor"]'
+
+# Disable the built-in coding skill (it tells the bot to use Codex/Claude Code directly, overriding AO)
+openclaw config set skills.entries.coding-agent.enabled false
+
+# Disable the built-in GitHub issues skill (it spawns OpenClaw sub-agents, bypassing AO)
+openclaw config set skills.entries.gh-issues.enabled false
+```
+
+### Optional Settings
+
+```bash
+# Discord: respond in server channels when @mentioned (default is DM-only)
+openclaw config set channels.discord.groupPolicy "open"
+# Read last 100 messages for context when @mentioned in a channel
+openclaw config set messages.groupChat.historyLimit 100
+```
+
+### Plugin Config (if `ao` isn't in PATH or repo isn't in default location)
+
+```bash
+# Set the path to the ao binary
+openclaw config set plugins.entries.agent-orchestrator.config.aoPath "/path/to/ao"
+
+# Set the working directory (must contain agent-orchestrator.yaml)
+openclaw config set plugins.entries.agent-orchestrator.config.aoCwd "/path/to/your/repo"
+
+# Set the path to gh binary (if not in PATH)
+openclaw config set plugins.entries.agent-orchestrator.config.ghPath "/path/to/gh"
+```
+
+## 4. Set Up Identity Files
+
+Create these files in `~/.openclaw/workspace/` to give the bot its personality and instructions:
+
+### IDENTITY.md
+
+```markdown
+# IDENTITY.md
+
+- **Name:** AO
+- **Creature:** AI Engineering Manager
+- **Vibe:** Sharp, concise, proactive
+- **Emoji:** ⚡
+
+## Default Setup
+
+- **GitHub account:** <your-github-username>
+- **Primary repo:** <owner/repo>
+- **AO project ID:** <project-id-from-agent-orchestrator.yaml>
+- **Owner:** <your-name>
+
+## How You Operate
+
+You are a MANAGER. You never write code yourself. You delegate ALL coding work to Agent Orchestrator.
+
+When asked about work → use `ao_issues` tool
+When asked about status → use `ao_sessions` or `ao_status` tool
+When asked to start work → use `ao_spawn` tool (always include project ID)
+When asked to start multiple → use `ao_batch_spawn` tool
+When talking to an agent → use `ao_send` tool
+When stopping an agent → use `ao_kill` tool (confirm first)
+
+If an AO tool fails, report the error. Do NOT fall back to coding directly.
+```
+
+### SOUL.md
+
+```markdown
+# SOUL.md
+
+You are AO — an AI engineering manager. You manage coding agents through Agent Orchestrator.
+
+You NEVER write code directly. You delegate ALL coding to AO agents via ao_spawn.
+Even if spawning fails, you report the failure — you don't code directly.
+
+Always include full PR URLs when reporting: https://github.com/<owner>/<repo>/pull/<number>
+```
+
+## 5. Restart and Verify
+
+```bash
+# Restart the gateway
+pm2 restart openclaw-gateway
+# Or however you run OpenClaw
+
+# Verify the plugin loaded
+openclaw plugins list | grep agent-orchestrator
+
+# Verify tools are visible
+openclaw agent --agent main -m "List your tools"
+# Should show ao_sessions, ao_issues, ao_spawn, etc.
+
+# Verify AO works
+/ao doctor
+```
+
+## Why These Settings Matter
+
+| Setting | Why |
+|---------|-----|
+| `tools.profile: "full"` | The `coding` profile only includes built-in tools. Plugin tools require `full`. |
+| `tools.allow: ["group:plugins"]` | OpenClaw treats ALL plugin tools as optional. Without this, they're invisible to the AI. |
+| `tools.deny: [exec, write, ...]` | Without this, the bot will write code directly instead of delegating to AO. |
+| `skills.entries.coding-agent.enabled: false` | This built-in skill tells the bot to use Codex/Claude Code. It overrides AO. |
+| `skills.entries.gh-issues.enabled: false` | This built-in skill spawns OpenClaw sub-agents. It bypasses AO. |
+| `aoCwd` | `ao spawn` must run from the directory containing `agent-orchestrator.yaml`. |
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Bot says "no ao_* tools available" | `tools.profile` is not `full` or `tools.allow` missing `group:plugins` | Run `/ao setup` |
+| Bot writes code directly | `coding-agent` skill is active or `exec`/`write` not denied | Run `/ao setup` |
+| `ao spawn` returns "No config found" | `aoCwd` not set or wrong path | Set `plugins.entries.agent-orchestrator.config.aoCwd` |
+| `ao: not found` | `ao` not in PATH | Create symlink or set `aoPath` in plugin config |
+| Only 2-3 issues shown (not all) | Bot answering from stale session memory | Clear sessions: `rm ~/.openclaw/agents/main/sessions/sessions.json` |
+| Bot only responds in DMs | `groupPolicy` is `allowlist` | Set `channels.discord.groupPolicy` to `open` |
+| Bot responds to every message | `mentionPatterns` too broad | Remove patterns, rely on native @mentions |
+| Sessions show "exited" immediately | Agent (Claude Code) won't run as root | Run AO as non-root user |
+
+## Architecture
+
+```
+Discord message → OpenClaw Gateway → AI Model (with AO tools)
+                                          ↓
+                                    ao_spawn tool
+                                          ↓
+                              AO CLI (agent-orchestrator)
+                                          ↓
+                              Git worktree + Claude Code agent
+                                          ↓
+                              Branch → Commit → PR
+```
+
+The bot (OpenClaw) is the **manager**. AO is the **workforce**. The bot never codes — it uses AO tools to spawn agents that do the actual work.

openclaw-plugin/index.test.ts

@@ -0,0 +1,124 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  extractConfiguredReposFromYaml,
+  fetchIssues,
+  mergeStringLists,
+  parseStringArraySetting,
+} from "./index.ts";
+
+function makeIssue(number: number, title: string, repo: string) {
+  return {
+    number,
+    title,
+    labels: [],
+    state: "open",
+    assignees: [],
+    createdAt: `2026-03-${String(number).padStart(2, "0")}T00:00:00Z`,
+    url: `https://github.com/${repo}/issues/${number}`,
+  };
+}
+
+test("extractConfiguredReposFromYaml reads every project repo", () => {
+  const rawYaml = `
+port: 3000
+projects:
+  app:
+    repo: acme/app
+    path: ~/code/app
+  docs:
+    repo: "acme/docs" # keep quoted repos working
+    path: ~/code/docs
+notifiers:
+  openclaw:
+    plugin: openclaw
+`;
+
+  assert.deepEqual(extractConfiguredReposFromYaml(rawYaml), ["acme/app", "acme/docs"]);
+});
+
+test("fetchIssues queries every configured repo when repo is omitted", () => {
+  const ghCalls: string[] = [];
+  const result = fetchIssues(
+    { aoCwd: "/tmp/work" },
+    {},
+    {
+      getConfiguredRepos: () => ["acme/app", "acme/docs"],
+      runGh: (_config, args) => {
+        const repoIndex = args.indexOf("-R");
+        const repo = repoIndex >= 0 ? args[repoIndex + 1] : "default";
+        ghCalls.push(repo);
+
+        if (repo === "acme/app") {
+          return { ok: true, output: JSON.stringify([makeIssue(1, "App bug", repo)]) };
+        }
+        if (repo === "acme/docs") {
+          return { ok: true, output: JSON.stringify([makeIssue(2, "Docs bug", repo)]) };
+        }
+
+        return { ok: false, error: `unexpected repo: ${repo}` };
+      },
+    },
+  );
+
+  assert.deepEqual(ghCalls, ["acme/app", "acme/docs"]);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+
+  assert.deepEqual(result.scannedRepos, ["acme/app", "acme/docs"]);
+  assert.equal(result.warnings.length, 0);
+  assert.deepEqual(
+    result.issues.map((issue) => issue.repository),
+    ["acme/docs", "acme/app"],
+  );
+});
+
+test("fetchIssues surfaces GitHub failures instead of reporting an empty board", () => {
+  const result = fetchIssues(
+    { aoCwd: "/tmp/work" },
+    {},
+    {
+      getConfiguredRepos: () => ["acme/app"],
+      runGh: () => ({ ok: false, error: "gh auth token missing" }),
+    },
+  );
+
+  assert.equal(result.ok, false);
+  if (result.ok) return;
+  assert.match(result.error, /gh auth token missing/);
+});
+
+test("fetchIssues keeps partial failures visible when at least one repo succeeds", () => {
+  const result = fetchIssues(
+    { aoCwd: "/tmp/work" },
+    {},
+    {
+      getConfiguredRepos: () => ["acme/app", "acme/docs"],
+      runGh: (_config, args) => {
+        const repoIndex = args.indexOf("-R");
+        const repo = repoIndex >= 0 ? args[repoIndex + 1] : "default";
+        if (repo === "acme/app") {
+          return { ok: true, output: JSON.stringify([makeIssue(3, "App bug", repo)]) };
+        }
+        return { ok: false, error: "gh not authenticated for docs repo" };
+      },
+    },
+  );
+
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.issues.length, 1);
+  assert.deepEqual(result.warnings, ["acme/docs: gh not authenticated for docs repo"]);
+});
+
+test("allowlist helpers preserve existing entries while adding AO requirements", () => {
+  assert.deepEqual(mergeStringLists(["custom:tools", "group:plugins"], ["group:plugins"]), [
+    "custom:tools",
+    "group:plugins",
+  ]);
+  assert.deepEqual(parseStringArraySetting('["group:plugins","custom:tools"]'), [
+    "group:plugins",
+    "custom:tools",
+  ]);
+  assert.deepEqual(parseStringArraySetting("null"), []);
+});

openclaw-plugin/openclaw.plugin.json

@@ -0,0 +1,60 @@
+{
+  "id": "agent-orchestrator",
+  "name": "Agent Orchestrator",
+  "description": "Control and monitor Agent Orchestrator (AO) from OpenClaw. Slash commands, AI tools, issue board scanning, proactive planning, and health monitoring.",
+  "version": "0.3.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["aoCwd"],
+    "properties": {
+      "aoPath": {
+        "type": "string",
+        "description": "Path to the ao CLI binary. Defaults to 'ao' (found via PATH)."
+      },
+      "aoCwd": {
+        "type": "string",
+        "description": "Working directory for ao commands. Must contain agent-orchestrator.yaml. Defaults to the current working directory."
+      },
+      "healthPollIntervalMs": {
+        "type": "number",
+        "description": "How often to poll AO health in milliseconds. Default: 30000 (30s). Set to 0 to disable."
+      },
+      "boardScanIntervalMs": {
+        "type": "number",
+        "description": "How often to scan the issue board for changes in milliseconds. Default: 1800000 (30min). Set to 0 to disable."
+      },
+      "ghPath": {
+        "type": "string",
+        "description": "Path to the gh CLI binary. Defaults to 'gh' (found via PATH)."
+      }
+    }
+  },
+  "uiHints": {
+    "aoCwd": {
+      "label": "AO working directory",
+      "placeholder": "/home/user/my-project",
+      "help": "Path to the directory containing agent-orchestrator.yaml. Required — most commands fail without this."
+    },
+    "aoPath": {
+      "label": "AO CLI path",
+      "placeholder": "ao",
+      "help": "Leave empty to use 'ao' from PATH"
+    },
+    "healthPollIntervalMs": {
+      "label": "Health poll interval (ms)",
+      "placeholder": "30000",
+      "help": "Set to 0 to disable health monitoring"
+    },
+    "boardScanIntervalMs": {
+      "label": "Board scan interval (ms)",
+      "placeholder": "1800000",
+      "help": "How often to scan for new issues. Default 30min. Set to 0 to disable."
+    },
+    "ghPath": {
+      "label": "GitHub CLI path",
+      "placeholder": "gh",
+      "help": "Leave empty to use 'gh' from PATH"
+    }
+  }
+}

openclaw-plugin/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "openclaw-agent-orchestrator",
+  "version": "0.3.1",
+  "description": "OpenClaw plugin for Agent Orchestrator — AI tools, slash commands, hooks, and health monitoring for managing parallel coding agents from OpenClaw",
+  "license": "MIT",
+  "author": "Dhruv Sharma (https://github.com/illegalcall)",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "main": "index.ts",
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ComposioHQ/agent-orchestrator.git",
+    "directory": "openclaw-plugin"
+  },
+  "homepage": "https://github.com/ComposioHQ/agent-orchestrator/tree/main/openclaw-plugin",
+  "bugs": "https://github.com/ComposioHQ/agent-orchestrator/issues",
+  "keywords": ["openclaw", "openclaw-plugin", "plugin", "agent-orchestrator", "composio", "ai-agents", "coding-agents"],
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/ao/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @composio/ao
 
+## 0.2.1
+
+### Patch Changes
+
+- ac625c3: Fix startup onboarding and install reliability:
+  - Repair npm global install startup path by improving package resolution and web package discovery hints.
+  - Make `ao start` prerequisite installs explicit and interactive for required tools (`tmux`, `git`) with clearer fallback guidance.
+  - Keep `ao spawn` preflight check-only for `tmux` (no implicit install).
+  - Remove redundant agent runtime re-detection during config generation.
+
+- Updated dependencies [ac625c3]
+  - @composio/ao-cli@0.2.1
+
 ## 0.2.0
 
 ### Minor Changes

packages/ao/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composio/ao",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Orchestrate parallel AI coding agents — global CLI wrapper",
   "license": "MIT",
   "type": "module",

packages/cli/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @composio/ao-cli
 
+## 0.2.1
+
+### Patch Changes
+
+- ac625c3: Fix startup onboarding and install reliability:
+  - Repair npm global install startup path by improving package resolution and web package discovery hints.
+  - Make `ao start` prerequisite installs explicit and interactive for required tools (`tmux`, `git`) with clearer fallback guidance.
+  - Keep `ao spawn` preflight check-only for `tmux` (no implicit install).
+  - Remove redundant agent runtime re-detection during config generation.
+
 ## 0.2.0
 
 ### Minor Changes

packages/cli/__tests__/commands/doctor.test.ts

@@ -1,12 +1,23 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { Command } from "commander";
 
-const { mockExecuteScriptCommand } = vi.hoisted(() => ({
-  mockExecuteScriptCommand: vi.fn(),
+const { mockRunRepoScript, mockFindConfigFile } = vi.hoisted(() => ({
+  mockRunRepoScript: vi.fn(),
+  mockFindConfigFile: vi.fn(),
 }));
 
 vi.mock("../../src/lib/script-runner.js", () => ({
-  executeScriptCommand: (...args: unknown[]) => mockExecuteScriptCommand(...args),
+  runRepoScript: (...args: unknown[]) => mockRunRepoScript(...args),
+}));
+
+vi.mock("@composio/ao-core", () => ({
+  findConfigFile: (...args: unknown[]) => mockFindConfigFile(...args),
+  loadConfig: vi.fn(),
+}));
+
+vi.mock("../../src/lib/openclaw-probe.js", () => ({
+  probeGateway: vi.fn(),
+  validateToken: vi.fn(),
 }));
 
 import { registerDoctor } from "../../src/commands/doctor.js";
@@ -18,8 +29,10 @@ describe("doctor command", () => {
     program = new Command();
     program.exitOverride();
     registerDoctor(program);
-    mockExecuteScriptCommand.mockReset();
-    mockExecuteScriptCommand.mockResolvedValue(undefined);
+    mockRunRepoScript.mockReset();
+    mockRunRepoScript.mockResolvedValue(0);
+    mockFindConfigFile.mockReset();
+    mockFindConfigFile.mockReturnValue(null);
   });
 
   afterEach(() => {
@@ -29,12 +42,12 @@ describe("doctor command", () => {
   it("runs the doctor script with no extra args by default", async () => {
     await program.parseAsync(["node", "test", "doctor"]);
 
-    expect(mockExecuteScriptCommand).toHaveBeenCalledWith("ao-doctor.sh", []);
+    expect(mockRunRepoScript).toHaveBeenCalledWith("ao-doctor.sh", []);
   });
 
   it("passes through --fix", async () => {
     await program.parseAsync(["node", "test", "doctor", "--fix"]);
 
-    expect(mockExecuteScriptCommand).toHaveBeenCalledWith("ao-doctor.sh", ["--fix"]);
+    expect(mockRunRepoScript).toHaveBeenCalledWith("ao-doctor.sh", ["--fix"]);
   });
 });

packages/cli/__tests__/commands/setup.test.ts

@@ -0,0 +1,470 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { Command } from "commander";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+// ---------------------------------------------------------------------------
+// Hoisted mocks — must be defined before any imports that use them
+// ---------------------------------------------------------------------------
+
+const { mockFindConfigFile } = vi.hoisted(() => ({
+  mockFindConfigFile: vi.fn(),
+}));
+
+const { mockReadFileSync, mockWriteFileSync, mockExistsSync, mockMkdirSync } = vi.hoisted(() => ({
+  mockReadFileSync: vi.fn(),
+  mockWriteFileSync: vi.fn(),
+  mockExistsSync: vi.fn(),
+  mockMkdirSync: vi.fn(),
+}));
+
+const { mockProbeGateway, mockValidateToken } = vi.hoisted(() => ({
+  mockProbeGateway: vi.fn(),
+  mockValidateToken: vi.fn(),
+}));
+
+vi.mock("@composio/ao-core", () => ({
+  findConfigFile: (...args: unknown[]) => mockFindConfigFile(...args),
+}));
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...actual,
+    readFileSync: (...args: unknown[]) => mockReadFileSync(...args),
+    writeFileSync: (...args: unknown[]) => mockWriteFileSync(...args),
+    existsSync: (...args: unknown[]) => mockExistsSync(...args),
+    mkdirSync: (...args: unknown[]) => mockMkdirSync(...args),
+  };
+});
+
+vi.mock("../../src/lib/openclaw-probe.js", () => ({
+  probeGateway: (...args: unknown[]) => mockProbeGateway(...args),
+  validateToken: (...args: unknown[]) => mockValidateToken(...args),
+  DEFAULT_OPENCLAW_URL: "http://127.0.0.1:18789",
+  HOOKS_PATH: "/hooks/agent",
+}));
+
+import { registerSetup } from "../../src/commands/setup.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const MINIMAL_CONFIG = `
+port: 3000
+defaults:
+  notifiers:
+    - desktop
+projects:
+  my-app:
+    name: my-app
+    repo: owner/repo
+    path: ~/code/my-app
+`;
+
+const CONFIG_WITH_OPENCLAW = `
+port: 3000
+defaults:
+  notifiers:
+    - desktop
+    - openclaw
+notifiers:
+  openclaw:
+    plugin: openclaw
+    url: http://127.0.0.1:18789/hooks/agent
+    token: "\${OPENCLAW_HOOKS_TOKEN}"
+projects:
+  my-app:
+    name: my-app
+`;
+
+function createProgram(): Command {
+  const program = new Command();
+  program.exitOverride(); // throw instead of process.exit
+  registerSetup(program);
+  return program;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("setup openclaw command", () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    mockFindConfigFile.mockReturnValue("/tmp/agent-orchestrator.yaml");
+    mockReadFileSync.mockReturnValue(MINIMAL_CONFIG);
+    mockWriteFileSync.mockImplementation(() => {});
+    mockExistsSync.mockReturnValue(false);
+    mockMkdirSync.mockImplementation(() => undefined);
+    mockValidateToken.mockResolvedValue({ valid: true });
+    mockProbeGateway.mockResolvedValue({ reachable: false });
+
+    // Force non-interactive (no TTY in test environment)
+    Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  describe("non-interactive mode", () => {
+    it("writes config when --url and --token provided", async () => {
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--token",
+        "test-token",
+        "--non-interactive",
+      ]);
+
+      // Code writes YAML config + shell profile export — at least one write
+      expect(mockWriteFileSync).toHaveBeenCalled();
+      const writtenYaml = mockWriteFileSync.mock.calls[0][1] as string;
+      expect(writtenYaml).toContain("openclaw");
+      expect(writtenYaml).toContain("plugin: openclaw");
+      expect(writtenYaml).toContain("http://127.0.0.1:18789/hooks/agent");
+    });
+
+    it("reads token from OPENCLAW_HOOKS_TOKEN env var and skips validation", async () => {
+      process.env["OPENCLAW_HOOKS_TOKEN"] = "env-token";
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--non-interactive",
+      ]);
+
+      // Non-interactive mode skips pre-write validation
+      expect(mockValidateToken).not.toHaveBeenCalled();
+      expect(mockWriteFileSync).toHaveBeenCalled();
+    });
+
+    it("reads URL from OPENCLAW_GATEWAY_URL env var and skips validation", async () => {
+      process.env["OPENCLAW_GATEWAY_URL"] = "http://remote:18789";
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--token",
+        "tok",
+        "--non-interactive",
+      ]);
+
+      // Non-interactive mode skips pre-write validation
+      expect(mockValidateToken).not.toHaveBeenCalled();
+      expect(mockWriteFileSync).toHaveBeenCalled();
+    });
+
+    it("normalizes OPENCLAW_GATEWAY_URL without double-appending hooks path", async () => {
+      process.env["OPENCLAW_GATEWAY_URL"] = "http://remote:18789/hooks/agent";
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--token",
+        "tok",
+        "--non-interactive",
+      ]);
+
+      const writtenYaml = mockWriteFileSync.mock.calls[0][1] as string;
+      expect(writtenYaml).toContain("url: http://remote:18789/hooks/agent");
+      expect(writtenYaml).not.toContain("/hooks/agent/hooks/agent");
+    });
+
+    it("skips token validation and writes config in non-interactive mode", async () => {
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--token",
+        "good-token",
+        "--non-interactive",
+      ]);
+
+      // Non-interactive setup skips pre-write validation (gateway may not have
+      // the token yet on a fresh install — user restarts gateway after setup)
+      expect(mockValidateToken).not.toHaveBeenCalled();
+      expect(mockWriteFileSync).toHaveBeenCalled();
+    });
+  });
+
+  describe("config writing", () => {
+    it("adds openclaw to defaults.notifiers", async () => {
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--token",
+        "tok",
+        "--non-interactive",
+      ]);
+
+      const writtenYaml = mockWriteFileSync.mock.calls[0][1] as string;
+      expect(writtenYaml).toContain("openclaw");
+      // Should have both desktop and openclaw in defaults.notifiers
+      expect(writtenYaml).toContain("desktop");
+    });
+
+    it("does not duplicate openclaw in defaults.notifiers", async () => {
+      mockReadFileSync.mockReturnValue(CONFIG_WITH_OPENCLAW);
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--token",
+        "tok",
+        "--non-interactive",
+      ]);
+
+      const writtenYaml = mockWriteFileSync.mock.calls[0][1] as string;
+      const parsed = parseYaml(writtenYaml) as { defaults?: { notifiers?: string[] } };
+      expect(parsed.defaults?.notifiers?.filter((name) => name === "openclaw")).toHaveLength(1);
+    });
+
+    it("writes correct notifier block structure", async () => {
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://custom:9999/hooks/agent",
+        "--token",
+        "tok",
+        "--non-interactive",
+      ]);
+
+      const writtenYaml = mockWriteFileSync.mock.calls[0][1] as string;
+      expect(writtenYaml).toContain("plugin: openclaw");
+      expect(writtenYaml).toContain("http://custom:9999/hooks/agent");
+      expect(writtenYaml).toContain("${OPENCLAW_HOOKS_TOKEN}");
+      expect(writtenYaml).toContain("retries: 3");
+      expect(writtenYaml).toContain("retryDelayMs: 1000");
+      expect(writtenYaml).toContain("wakeMode: now");
+    });
+
+    it("merges existing allowedSessionKeyPrefixes in openclaw.json", async () => {
+      const openclawConfigPath = join(homedir(), ".openclaw", "openclaw.json");
+
+      mockExistsSync.mockImplementation((path: string) => path === openclawConfigPath);
+      mockReadFileSync.mockImplementation((path: string) => {
+        if (path === "/tmp/agent-orchestrator.yaml") {
+          return MINIMAL_CONFIG;
+        }
+        if (path === openclawConfigPath) {
+          return JSON.stringify({
+            hooks: {
+              enabled: false,
+              token: "old-token",
+              allowRequestSessionKey: false,
+              allowedSessionKeyPrefixes: ["legacy:", "hook:"],
+            },
+            otherConfig: true,
+          });
+        }
+        return "";
+      });
+
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--token",
+        "new-token",
+        "--non-interactive",
+      ]);
+
+      const openclawWrite = mockWriteFileSync.mock.calls.find(
+        ([path]) => path === openclawConfigPath,
+      );
+      expect(openclawWrite).toBeDefined();
+
+      const writtenJson = JSON.parse(openclawWrite![1] as string) as {
+        hooks: {
+          token: string;
+          enabled: boolean;
+          allowRequestSessionKey: boolean;
+          allowedSessionKeyPrefixes: string[];
+        };
+        otherConfig: boolean;
+      };
+
+      expect(writtenJson.otherConfig).toBe(true);
+      expect(writtenJson.hooks.token).toBe("new-token");
+      expect(writtenJson.hooks.enabled).toBe(true);
+      expect(writtenJson.hooks.allowRequestSessionKey).toBe(true);
+      expect(writtenJson.hooks.allowedSessionKeyPrefixes).toEqual(["legacy:", "hook:"]);
+    });
+
+    it("preserves existing projects in config", async () => {
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--token",
+        "tok",
+        "--non-interactive",
+      ]);
+
+      const writtenYaml = mockWriteFileSync.mock.calls[0][1] as string;
+      expect(writtenYaml).toContain("my-app");
+      expect(writtenYaml).toContain("owner/repo");
+    });
+
+    it("writes to the correct config path", async () => {
+      mockFindConfigFile.mockReturnValue("/custom/path/agent-orchestrator.yaml");
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--token",
+        "tok",
+        "--non-interactive",
+      ]);
+
+      expect(mockWriteFileSync.mock.calls[0][0]).toBe("/custom/path/agent-orchestrator.yaml");
+    });
+  });
+
+  describe("error handling", () => {
+    it("exits when no config file found", async () => {
+      mockFindConfigFile.mockReturnValue(null);
+      const program = createProgram();
+
+      const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => {
+        throw new Error("process.exit");
+      });
+
+      await expect(
+        program.parseAsync([
+          "node",
+          "test",
+          "setup",
+          "openclaw",
+          "--url",
+          "http://127.0.0.1:18789/hooks/agent",
+          "--token",
+          "tok",
+          "--non-interactive",
+        ]),
+      ).rejects.toThrow("process.exit");
+
+      expect(exitSpy).toHaveBeenCalledWith(1);
+      expect(mockWriteFileSync).not.toHaveBeenCalled();
+    });
+
+    it("skips validation and writes config even with bad token in non-interactive mode", async () => {
+      mockValidateToken.mockResolvedValue({ valid: false, error: "Token rejected" });
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--token",
+        "bad-token",
+        "--non-interactive",
+      ]);
+
+      // nonInteractiveSetup skips pre-write validation, so config should still be written
+      expect(mockWriteFileSync).toHaveBeenCalled();
+    });
+
+    it("exits when --url missing in non-interactive mode", async () => {
+      const program = createProgram();
+
+      const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => {
+        throw new Error("process.exit");
+      });
+
+      await expect(
+        program.parseAsync([
+          "node",
+          "test",
+          "setup",
+          "openclaw",
+          "--token",
+          "tok",
+          "--non-interactive",
+        ]),
+      ).rejects.toThrow("process.exit");
+
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it("auto-generates token when --token missing in non-interactive mode", async () => {
+      delete process.env["OPENCLAW_HOOKS_TOKEN"];
+      const program = createProgram();
+
+      await program.parseAsync([
+        "node",
+        "test",
+        "setup",
+        "openclaw",
+        "--url",
+        "http://127.0.0.1:18789/hooks/agent",
+        "--non-interactive",
+      ]);
+
+      // nonInteractiveSetup auto-generates a token when none is provided
+      expect(mockWriteFileSync).toHaveBeenCalled();
+    });
+  });
+});

packages/cli/__tests__/lib/openclaw-probe.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { probeGateway, validateToken } from "../../src/lib/openclaw-probe.js";
+
+describe("openclaw-probe", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("probeGateway", () => {
+    it("returns reachable:true on 200", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ status: 200, ok: true });
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await probeGateway("http://127.0.0.1:18789");
+
+      expect(result.reachable).toBe(true);
+      expect(result.httpStatus).toBe(200);
+      expect(result.error).toBeUndefined();
+    });
+
+    it("returns reachable:true even on non-200 (gateway is up)", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ status: 404, ok: false });
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await probeGateway("http://127.0.0.1:18789");
+
+      expect(result.reachable).toBe(true);
+      expect(result.httpStatus).toBe(404);
+    });
+
+    it("returns reachable:false on ECONNREFUSED", async () => {
+      const fetchMock = vi.fn().mockRejectedValue(new Error("fetch failed: ECONNREFUSED"));
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await probeGateway("http://127.0.0.1:18789");
+
+      expect(result.reachable).toBe(false);
+      expect(result.error).toContain("not reachable");
+    });
+
+    it("returns reachable:false on timeout", async () => {
+      const fetchMock = vi.fn().mockRejectedValue(new Error("The operation was aborted"));
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await probeGateway("http://127.0.0.1:18789", 100);
+
+      expect(result.reachable).toBe(false);
+      expect(result.error).toContain("timed out");
+    });
+
+    it("strips trailing slashes from URL", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ status: 200, ok: true });
+      vi.stubGlobal("fetch", fetchMock);
+
+      await probeGateway("http://127.0.0.1:18789///");
+
+      expect(fetchMock.mock.calls[0][0]).toBe("http://127.0.0.1:18789");
+    });
+
+    it("uses default URL when none provided", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ status: 200, ok: true });
+      vi.stubGlobal("fetch", fetchMock);
+
+      await probeGateway();
+
+      expect(fetchMock.mock.calls[0][0]).toBe("http://127.0.0.1:18789");
+    });
+  });
+
+  describe("validateToken", () => {
+    it("returns valid:true on 200", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await validateToken("http://127.0.0.1:18789", "good-token");
+
+      expect(result.valid).toBe(true);
+      expect(result.error).toBeUndefined();
+    });
+
+    it("sends Bearer token in Authorization header", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+      vi.stubGlobal("fetch", fetchMock);
+
+      await validateToken("http://127.0.0.1:18789", "my-secret");
+
+      const headers = fetchMock.mock.calls[0][1].headers;
+      expect(headers["Authorization"]).toBe("Bearer my-secret");
+    });
+
+    it("appends /hooks/agent if not in URL", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+      vi.stubGlobal("fetch", fetchMock);
+
+      await validateToken("http://127.0.0.1:18789", "tok");
+
+      expect(fetchMock.mock.calls[0][0]).toBe("http://127.0.0.1:18789/hooks/agent");
+    });
+
+    it("does not double-append /hooks/agent", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+      vi.stubGlobal("fetch", fetchMock);
+
+      await validateToken("http://127.0.0.1:18789/hooks/agent", "tok");
+
+      expect(fetchMock.mock.calls[0][0]).toBe("http://127.0.0.1:18789/hooks/agent");
+    });
+
+    it("returns valid:false with message on 401", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ ok: false, status: 401 });
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await validateToken("http://127.0.0.1:18789", "bad-token");
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Token rejected");
+    });
+
+    it("returns valid:false with message on 403", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ ok: false, status: 403 });
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await validateToken("http://127.0.0.1:18789", "bad-token");
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Token rejected");
+    });
+
+    it("returns valid:false with body on unexpected status", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: false,
+        status: 500,
+        text: () => Promise.resolve("internal error"),
+      });
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await validateToken("http://127.0.0.1:18789", "tok");
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("500");
+      expect(result.error).toContain("internal error");
+    });
+
+    it("returns valid:false on ECONNREFUSED", async () => {
+      const fetchMock = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await validateToken("http://127.0.0.1:18789", "tok");
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Can't reach");
+    });
+
+    it("returns valid:false on timeout", async () => {
+      const fetchMock = vi.fn().mockRejectedValue(new Error("The operation was aborted"));
+      vi.stubGlobal("fetch", fetchMock);
+
+      const result = await validateToken("http://127.0.0.1:18789", "tok", 100);
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("timed out");
+    });
+
+    it("sends a test payload with correct structure", async () => {
+      const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+      vi.stubGlobal("fetch", fetchMock);
+
+      await validateToken("http://127.0.0.1:18789", "tok");
+
+      const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+      expect(body.message).toContain("Connection test");
+      expect(body.name).toBe("AO");
+      expect(body.sessionKey).toBe("hook:ao:setup-test");
+      expect(body.wakeMode).toBe("now");
+      expect(body.deliver).toBe(false);
+    });
+  });
+});

packages/cli/__tests__/scripts/doctor-script.test.ts

@@ -29,6 +29,7 @@ function createFakeBinary(binDir: string, name: string, body: string): void {
 function createHealthyRepo(tempRoot: string): string {
   const fakeRepo = join(tempRoot, "repo");
   mkdirSync(join(fakeRepo, "node_modules"), { recursive: true });
+  mkdirSync(join(fakeRepo, "packages", "ao"), { recursive: true });
   mkdirSync(join(fakeRepo, "packages", "core", "dist"), { recursive: true });
   mkdirSync(join(fakeRepo, "packages", "cli", "dist"), { recursive: true });
   mkdirSync(join(fakeRepo, "packages", "agent-orchestrator", "bin"), { recursive: true });
@@ -98,7 +99,7 @@ describe("scripts/ao-doctor.sh", () => {
     const result = spawnSync("bash", [scriptPath], {
       env: {
         ...process.env,
-        PATH: `${binDir}:${process.env.PATH || ""}`,
+        PATH: `${binDir}:/bin:/usr/bin`,
         AO_REPO_ROOT: fakeRepo,
         AO_CONFIG_PATH: configPath,
       },
@@ -149,7 +150,7 @@ describe("scripts/ao-doctor.sh", () => {
     const result = spawnSync("bash", [scriptPath, "--fix"], {
       env: {
         ...process.env,
-        PATH: `${binDir}:${process.env.PATH || ""}`,
+        PATH: `${binDir}:/bin:/usr/bin`,
         AO_REPO_ROOT: fakeRepo,
         AO_CONFIG_PATH: configPath,
         AO_DOCTOR_TMP_ROOT: tmpRoot,

packages/cli/__tests__/scripts/update-script.test.ts

@@ -22,6 +22,7 @@ describe("scripts/ao-update.sh", () => {
     const tempRoot = mkdtempSync(join(tmpdir(), "ao-update-script-"));
     const fakeRepo = join(tempRoot, "repo");
     mkdirSync(join(fakeRepo, "packages", "cli"), { recursive: true });
+    mkdirSync(join(fakeRepo, "packages", "ao"), { recursive: true });
 
     const binDir = join(tempRoot, "bin");
     mkdirSync(binDir, { recursive: true });
@@ -79,6 +80,7 @@ esac\nexit 0`,
     const tempRoot = mkdtempSync(join(tmpdir(), "ao-update-smoke-"));
     const fakeRepo = join(tempRoot, "repo");
     mkdirSync(join(fakeRepo, "packages", "agent-orchestrator", "bin"), { recursive: true });
+    mkdirSync(join(fakeRepo, "packages", "ao"), { recursive: true });
     writeFileSync(
       join(fakeRepo, "packages", "agent-orchestrator", "bin", "ao.js"),
       "#!/usr/bin/env node\n",
@@ -178,6 +180,7 @@ exit 0`,
     const tempRoot = mkdtempSync(join(tmpdir(), "ao-update-post-dirty-"));
     const fakeRepo = join(tempRoot, "repo");
     mkdirSync(join(fakeRepo, "packages", "cli"), { recursive: true });
+    mkdirSync(join(fakeRepo, "packages", "ao"), { recursive: true });
 
     const binDir = join(tempRoot, "bin");
     mkdirSync(binDir, { recursive: true });

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composio/ao-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "CLI for agent-orchestrator — the `ao` command",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,7 @@
     "@composio/ao-plugin-agent-opencode": "workspace:*",
     "@composio/ao-plugin-notifier-composio": "workspace:*",
     "@composio/ao-plugin-notifier-desktop": "workspace:*",
+    "@composio/ao-plugin-notifier-discord": "workspace:*",
     "@composio/ao-plugin-notifier-openclaw": "workspace:*",
     "@composio/ao-plugin-notifier-slack": "workspace:*",
     "@composio/ao-plugin-notifier-webhook": "workspace:*",
@@ -53,6 +54,7 @@
     "@composio/ao-plugin-workspace-clone": "workspace:*",
     "@composio/ao-plugin-workspace-worktree": "workspace:*",
     "@composio/ao-web": "workspace:*",
+    "@clack/prompts": "^0.9.1",
     "chalk": "^5.4.0",
     "commander": "^13.0.0",
     "ora": "^8.1.0",

packages/cli/src/commands/doctor.ts

@@ -1,17 +1,221 @@
 import type { Command } from "commander";
-import { executeScriptCommand } from "../lib/script-runner.js";
+import chalk from "chalk";
+import { findConfigFile, loadConfig, type Notifier, type OrchestratorConfig } from "@composio/ao-core";
+import { runRepoScript } from "../lib/script-runner.js";
+import { probeGateway, validateToken } from "../lib/openclaw-probe.js";
+
+// ---------------------------------------------------------------------------
+// Helpers — match the PASS / WARN / FAIL style of ao-doctor.sh
+// ---------------------------------------------------------------------------
+
+function pass(msg: string): void {
+  console.log(`${chalk.green("PASS")} ${msg}`);
+}
+
+function warn(msg: string): void {
+  console.log(`${chalk.yellow("WARN")} ${msg}`);
+}
+
+/** Returns a fail() recorder and a count() getter — local per invocation, no shared state. */
+function makeFailCounter(): { fail: (msg: string) => void; count: () => number } {
+  let n = 0;
+  return {
+    fail(msg: string): void {
+      n++;
+      console.log(`${chalk.red("FAIL")} ${msg}`);
+    },
+    count(): number {
+      return n;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Notifier connectivity checks (Gap 2)
+// ---------------------------------------------------------------------------
+
+async function checkOpenClawNotifier(
+  config: OrchestratorConfig,
+  fail: (msg: string) => void,
+): Promise<void> {
+  const openclawConfig = config.notifiers?.["openclaw"];
+  if (!openclawConfig || openclawConfig.plugin !== "openclaw") {
+    warn("OpenClaw notifier is not configured. Fix: run ao setup openclaw");
+    return;
+  }
+
+  const url =
+    (typeof openclawConfig["url"] === "string" ? openclawConfig["url"] : undefined) ??
+    "http://127.0.0.1:18789";
+  // Resolve ${ENV_VAR} placeholders written by `ao setup openclaw` — the config
+  // stores the literal string "${OPENCLAW_HOOKS_TOKEN}" which is truthy but wrong.
+  const rawToken = typeof openclawConfig["token"] === "string" ? openclawConfig["token"] : undefined;
+  const envVarMatch = rawToken?.match(/^\$\{([^}]+)\}$/);
+  const token = (envVarMatch ? process.env[envVarMatch[1]] : rawToken) ?? process.env["OPENCLAW_HOOKS_TOKEN"];
+
+  // Step 1: Probe gateway reachability
+  const probe = await probeGateway(url);
+  if (!probe.reachable) {
+    fail(
+      `OpenClaw gateway is not reachable at ${url}. ` +
+        `Fix: ensure OpenClaw is running (openclaw status) or fix the URL in your config`,
+    );
+    return;
+  }
+
+  pass(`OpenClaw gateway is reachable at ${url} (HTTP ${probe.httpStatus})`);
+
+  // Step 2: Validate auth token if present
+  if (!token) {
+    warn(
+      "OpenClaw token is not set. Fix: set OPENCLAW_HOOKS_TOKEN env var or add token to notifiers.openclaw in config",
+    );
+    return;
+  }
+
+  const tokenResult = await validateToken(url, token);
+  if (!tokenResult.valid) {
+    fail(`OpenClaw token validation failed: ${tokenResult.error}`);
+    return;
+  }
+
+  pass("OpenClaw token is valid");
+}
+
+async function checkNotifierConnectivity(
+  config: OrchestratorConfig,
+  fail: (msg: string) => void,
+): Promise<void> {
+  console.log(""); // blank line before notifier section
+  console.log("Notifier connectivity:");
+
+  const configuredNotifiers = Object.keys(config.notifiers ?? {});
+  if (configuredNotifiers.length === 0) {
+    warn("No notifiers are configured. Fix: add notifiers to your agent-orchestrator.yaml");
+    return;
+  }
+
+  // Check OpenClaw specifically (it's the only one we can probe without side effects)
+  if (config.notifiers?.["openclaw"]) {
+    await checkOpenClawNotifier(config, fail);
+  }
+
+  // Report other configured notifiers as present (we can't health-check Slack/desktop/webhook without sending)
+  for (const [name, notifierConfig] of Object.entries(config.notifiers ?? {})) {
+    if (name === "openclaw") continue; // already checked above
+    const plugin = notifierConfig.plugin;
+    pass(`${name} notifier is configured (plugin: ${plugin})`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test-notify (Gap 3)
+// ---------------------------------------------------------------------------
+
+async function sendTestNotifications(
+  config: OrchestratorConfig,
+  fail: (msg: string) => void,
+): Promise<void> {
+  const { createPluginRegistry } = await import("@composio/ao-core");
+  const registry = createPluginRegistry();
+  await registry.loadFromConfig(config);
+
+  const activeNotifierNames = config.defaults?.notifiers ?? [];
+  const configuredNotifiers = Object.keys(config.notifiers ?? {});
+
+  // Combine both lists (defaults + configured) and deduplicate
+  const allNames = [...new Set([...activeNotifierNames, ...configuredNotifiers])];
+
+  if (allNames.length === 0) {
+    warn("No notifiers to test. Fix: configure notifiers in your agent-orchestrator.yaml");
+    return;
+  }
+
+  console.log(`\nSending test notification to ${allNames.length} notifier(s)...\n`);
+
+  for (const name of allNames) {
+    const notifier = registry.get<Notifier>("notifier", name);
+    if (!notifier) {
+      warn(`${name}: plugin not loaded (may not be installed)`);
+      continue;
+    }
+
+    try {
+      const testEvent = {
+        id: `doctor-test-${Date.now()}`,
+        type: "summary.all_complete" as const,
+        priority: "info" as const,
+        sessionId: "doctor-test",
+        projectId: "doctor",
+        timestamp: new Date(),
+        message: "Test notification from ao doctor --test-notify",
+        data: { source: "ao-doctor" },
+      };
+
+      await notifier.notify(testEvent);
+      pass(`${name}: test notification sent`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      fail(`${name}: ${message}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
 
 export function registerDoctor(program: Command): void {
   program
     .command("doctor")
     .description("Run install, environment, and runtime health checks")
     .option("--fix", "Apply safe fixes for launcher and stale temp issues")
-    .action(async (opts: { fix?: boolean }) => {
-      const args: string[] = [];
+    .option("--test-notify", "Send a test notification through each configured notifier")
+    .action(async (opts: { fix?: boolean; testNotify?: boolean }) => {
+      const { fail, count: failCount } = makeFailCounter();
+
+      // 1. Run the existing shell-based checks
+      const scriptArgs: string[] = [];
       if (opts.fix) {
-        args.push("--fix");
+        scriptArgs.push("--fix");
       }
 
-      await executeScriptCommand("ao-doctor.sh", args);
+      let shellExitCode: number;
+      try {
+        shellExitCode = await runRepoScript("ao-doctor.sh", scriptArgs);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        shellExitCode = 1;
+      }
+
+      // 2. Run TypeScript-based notifier checks if a config file exists
+      const configPath = findConfigFile();
+      if (configPath) {
+        let config: ReturnType<typeof loadConfig> | undefined;
+        try {
+          config = loadConfig(configPath);
+          await checkNotifierConnectivity(config, fail);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          warn(`Notifier connectivity check failed: ${message}`);
+        }
+
+        // 3. Send test notifications if requested (separate catch for accurate errors)
+        if (opts.testNotify && config) {
+          try {
+            await sendTestNotifications(config, fail);
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            fail(`Sending test notifications failed: ${message}`);
+          }
+        }
+      } else if (opts.testNotify) {
+        fail("No config file found. Cannot test notifiers without agent-orchestrator.yaml");
+      }
+
+      // Exit non-zero if shell checks or notifier checks failed
+      if (shellExitCode !== 0 || failCount() > 0) {
+        process.exit(shellExitCode || 1);
+      }
     });
 }

packages/cli/src/commands/setup.ts

@@ -0,0 +1,531 @@
+/**
+ * `ao setup openclaw` — interactive wizard + non-interactive mode
+ * for wiring AO notifications to an OpenClaw gateway.
+ *
+ * Interactive:  ao setup openclaw          (human in terminal)
+ * Programmatic: ao setup openclaw --url X --token Y --non-interactive
+ *               (OpenClaw agent calling via exec tool)
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { parse as yamlParse, parseDocument } from "yaml";
+import { findConfigFile } from "@composio/ao-core";
+import {
+  probeGateway,
+  validateToken,
+  DEFAULT_OPENCLAW_URL,
+  HOOKS_PATH,
+} from "../lib/openclaw-probe.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export class SetupAbortedError extends Error {
+  constructor(
+    message: string,
+    public readonly exitCode: number = 1,
+  ) {
+    super(message);
+    this.name = "SetupAbortedError";
+  }
+}
+
+interface SetupOptions {
+  url?: string;
+  token?: string;
+  nonInteractive?: boolean;
+}
+
+interface ResolvedConfig {
+  url: string;
+  token: string;
+}
+
+function normalizeOpenClawHooksUrl(url: string): string {
+  const normalized = url.trim().replace(/\/+$/, "");
+  return normalized.endsWith(HOOKS_PATH) ? normalized : `${normalized}${HOOKS_PATH}`;
+}
+
+// ---------------------------------------------------------------------------
+// Interactive prompts (dynamic import to keep @clack/prompts optional)
+// ---------------------------------------------------------------------------
+
+async function interactiveSetup(existingUrl?: string): Promise<ResolvedConfig> {
+  const clack = await import("@clack/prompts");
+
+  clack.intro(chalk.bgCyan(chalk.black(" ao setup openclaw ")));
+
+  // --- Step 1: Gateway URL ---------------------------------------------------
+  const defaultUrl = `${DEFAULT_OPENCLAW_URL}${HOOKS_PATH}`;
+  let detectedUrl: string | undefined;
+
+  const spin = clack.spinner();
+  spin.start("Detecting OpenClaw gateway on localhost...");
+
+  const probe = await probeGateway(DEFAULT_OPENCLAW_URL);
+  if (probe.reachable) {
+    detectedUrl = defaultUrl;
+    spin.stop(`Found OpenClaw gateway at ${DEFAULT_OPENCLAW_URL}`);
+  } else {
+    spin.stop("No OpenClaw gateway detected on localhost");
+  }
+
+  const urlInput = await clack.text({
+    message: "OpenClaw webhook URL:",
+    placeholder: defaultUrl,
+    initialValue: existingUrl ?? detectedUrl ?? defaultUrl,
+    validate: (v) => {
+      if (!v) return "URL is required";
+      if (!v.startsWith("http://") && !v.startsWith("https://"))
+        return "Must start with http:// or https://";
+    },
+  });
+
+  if (clack.isCancel(urlInput)) {
+    clack.cancel("Setup cancelled.");
+    throw new SetupAbortedError("Setup cancelled.", 0);
+  }
+
+  // Normalize: ensure URL ends with /hooks/agent
+  const url = normalizeOpenClawHooksUrl(urlInput as string);
+
+  // --- Step 2: Token ---------------------------------------------------------
+  const envToken = process.env["OPENCLAW_HOOKS_TOKEN"];
+  let tokenValue: string;
+
+  if (envToken) {
+    const useEnv = await clack.confirm({
+      message: `Found OPENCLAW_HOOKS_TOKEN in environment. Use it?`,
+      initialValue: true,
+    });
+
+    if (clack.isCancel(useEnv)) {
+      clack.cancel("Setup cancelled.");
+      throw new SetupAbortedError("Setup cancelled.", 0);
+    }
+
+    if (useEnv) {
+      tokenValue = envToken;
+    } else {
+      const input = await clack.password({
+        message: "Enter your OpenClaw hooks token:",
+        validate: (v) => (!v ? "Token is required" : undefined),
+      });
+      if (clack.isCancel(input)) {
+        clack.cancel("Setup cancelled.");
+        throw new SetupAbortedError("Setup cancelled.", 0);
+      }
+      tokenValue = input as string;
+    }
+  } else {
+    const generatedToken = randomBytes(32).toString("base64url");
+    const tokenChoice = await clack.select({
+      message: "How would you like to set the hooks token?",
+      options: [
+        { value: "generate", label: "Auto-generate a secure token (recommended)" },
+        { value: "manual", label: "Enter an existing token manually" },
+      ],
+    });
+
+    if (clack.isCancel(tokenChoice)) {
+      clack.cancel("Setup cancelled.");
+      throw new SetupAbortedError("Setup cancelled.", 0);
+    }
+
+    if (tokenChoice === "manual") {
+      const input = await clack.password({
+        message: "Enter your OpenClaw hooks token:",
+        validate: (v) => (!v ? "Token is required" : undefined),
+      });
+      if (clack.isCancel(input)) {
+        clack.cancel("Setup cancelled.");
+        throw new SetupAbortedError("Setup cancelled.", 0);
+      }
+      tokenValue = input as string;
+    } else {
+      tokenValue = generatedToken;
+      clack.log.success(`Generated token: ${chalk.dim(tokenValue.slice(0, 8))}...`);
+    }
+  }
+
+  // --- Step 3: Validate ------------------------------------------------------
+  spin.start("Validating token against gateway...");
+
+  const validation = await validateToken(url, tokenValue);
+  if (validation.valid) {
+    spin.stop("Token validated — connection works!");
+  } else {
+    spin.stop(`Validation failed: ${validation.error}`);
+
+    const cont = await clack.confirm({
+      message: "Save config anyway? (you can fix the token later)",
+      initialValue: false,
+    });
+
+    if (clack.isCancel(cont) || !cont) {
+      clack.cancel("Setup cancelled. Fix the issue and retry.");
+      throw new SetupAbortedError("Setup cancelled. Fix the issue and retry.");
+    }
+  }
+
+  return { url, token: tokenValue };
+}
+
+// ---------------------------------------------------------------------------
+// Non-interactive path
+// ---------------------------------------------------------------------------
+
+async function nonInteractiveSetup(opts: SetupOptions): Promise<ResolvedConfig> {
+  const rawUrl = opts.url ?? process.env["OPENCLAW_GATEWAY_URL"];
+  const token = opts.token ?? process.env["OPENCLAW_HOOKS_TOKEN"];
+
+  if (!rawUrl) {
+    throw new SetupAbortedError(
+      "Error: --url is required in non-interactive mode.\n" +
+        "  Example: ao setup openclaw --url http://127.0.0.1:18789/hooks/agent --token YOUR_TOKEN --non-interactive",
+    );
+  }
+
+  let url = rawUrl;
+  if (!url.startsWith("http://") && !url.startsWith("https://")) {
+    throw new SetupAbortedError("Error: --url must start with http:// or https://");
+  }
+
+  // Normalize: ensure URL ends with /hooks/agent
+  url = normalizeOpenClawHooksUrl(url);
+
+  const resolvedToken = token ?? randomBytes(32).toString("base64url");
+  if (!token) {
+    console.log(chalk.dim("No token provided — auto-generated a secure token."));
+  }
+
+  // Skip pre-write validation — on fresh installs the gateway won't have the
+  // token yet. We write both configs first, then the user restarts the gateway.
+  console.log(chalk.dim("Skipping pre-validation (token will be written to both configs)."));
+
+  return { url, token: resolvedToken };
+}
+
+// ---------------------------------------------------------------------------
+// Config writer
+// ---------------------------------------------------------------------------
+
+function writeOpenClawConfig(
+  configPath: string,
+  resolved: ResolvedConfig,
+  nonInteractive: boolean,
+): void {
+  const rawYaml = readFileSync(configPath, "utf-8");
+
+  // Use parseDocument to preserve YAML comments during round-trip
+  const doc = parseDocument(rawYaml);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const rawConfig = (doc.toJS() as Record<string, any>) ?? {};
+
+  // Write the env-var placeholder so the raw token is never committed to
+  // version control. ao setup openclaw exports the real value to the shell
+  // profile; the notifier plugin resolves it at runtime (env var → openclaw.json
+  // fallback for daemon contexts where the shell profile isn't sourced).
+  if (!rawConfig.notifiers) rawConfig.notifiers = {};
+  rawConfig.notifiers.openclaw = {
+    plugin: "openclaw",
+    url: resolved.url,
+    token: "$" + "{OPENCLAW_HOOKS_TOKEN}", // env-var placeholder, not a JS template
+    retries: 3,
+    retryDelayMs: 1000,
+    wakeMode: "now",
+  };
+
+  // Add "openclaw" to defaults.notifiers if not already present
+  if (!rawConfig.defaults) rawConfig.defaults = {};
+  if (!rawConfig.defaults.notifiers) rawConfig.defaults.notifiers = ["desktop"];
+  if (!Array.isArray(rawConfig.defaults.notifiers)) {
+    rawConfig.defaults.notifiers = [rawConfig.defaults.notifiers];
+  }
+  if (!rawConfig.defaults.notifiers.includes("openclaw")) {
+    rawConfig.defaults.notifiers.push("openclaw");
+  }
+
+  // Add "openclaw" to notificationRouting so notifications actually fire
+  // (AO prefers per-priority routing over defaults.notifiers)
+  if (!rawConfig.notificationRouting) {
+    // Seed from existing defaults.notifiers so we don't silently drop notifiers
+    // (e.g. desktop) that the user already had for all priorities.
+    const base = [...new Set([...(rawConfig.defaults.notifiers as string[]), "openclaw"])];
+    rawConfig.notificationRouting = {
+      urgent: [...base],
+      action: [...base],
+      warning: [...base],
+      info: [...base],
+    };
+  } else if (typeof rawConfig.notificationRouting === "object") {
+    for (const priority of Object.keys(rawConfig.notificationRouting)) {
+      const list = rawConfig.notificationRouting[priority];
+      if (Array.isArray(list) && !list.includes("openclaw")) {
+        list.push("openclaw");
+      }
+    }
+  }
+
+  // Update the document tree from the modified plain object while preserving comments
+  doc.setIn(["notifiers"], rawConfig.notifiers);
+  doc.setIn(["defaults"], rawConfig.defaults);
+  doc.setIn(["notificationRouting"], rawConfig.notificationRouting);
+
+  writeFileSync(configPath, doc.toString({ indent: 2 }));
+
+  if (nonInteractive) {
+    console.log(chalk.green(`✓ Config written to ${configPath}`));
+  }
+}
+
+/**
+ * Write the hooks block into ~/.openclaw/openclaw.json.
+ * Returns true on success, false on failure (caller should fall back to
+ * printing manual instructions).
+ */
+function writeOpenClawJsonConfig(token: string): boolean {
+  try {
+    const openclawDir = join(homedir(), ".openclaw");
+    const openclawJsonPath = join(openclawDir, "openclaw.json");
+
+    let config: Record<string, unknown> = {};
+    if (existsSync(openclawJsonPath)) {
+      const raw = readFileSync(openclawJsonPath, "utf-8");
+      config = JSON.parse(raw) as Record<string, unknown>;
+    } else if (!existsSync(openclawDir)) {
+      mkdirSync(openclawDir, { recursive: true });
+    }
+
+    // Merge the hooks block (preserve other existing keys in hooks if any)
+    const existingHooks = (config.hooks as Record<string, unknown> | undefined) ?? {};
+    const existingPrefixes = Array.isArray(existingHooks.allowedSessionKeyPrefixes)
+      ? existingHooks.allowedSessionKeyPrefixes.filter(
+          (prefix): prefix is string => typeof prefix === "string",
+        )
+      : [];
+    const allowedSessionKeyPrefixes = existingPrefixes.includes("hook:")
+      ? existingPrefixes
+      : [...existingPrefixes, "hook:"];
+
+    config.hooks = {
+      ...existingHooks,
+      enabled: true,
+      token,
+      allowRequestSessionKey: true,
+      allowedSessionKeyPrefixes,
+    };
+
+    writeFileSync(openclawJsonPath, JSON.stringify(config, null, 2) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Append `export OPENCLAW_HOOKS_TOKEN=...` to the user's shell profile
+ * (~/.zshrc or ~/.bashrc). Skips if the export line already exists.
+ * Returns the profile path on success, undefined on failure.
+ */
+function writeShellExport(token: string): string | undefined {
+  try {
+    const shell = process.env["SHELL"] ?? "";
+    const profileName = shell.endsWith("/zsh") ? ".zshrc" : ".bashrc";
+    const profilePath = join(homedir(), profileName);
+
+    // Sanitize token: escape shell-special characters to prevent injection
+    // when the profile is sourced. Single-quote the value and escape any
+    // embedded single quotes (the only character that breaks '...' quoting).
+    const safeToken = token.replace(/'/g, "'\\''");
+    const exportLine = `export OPENCLAW_HOOKS_TOKEN='${safeToken}'`;
+
+    // Check if it already exists (use the same regex for detection and replacement
+    // to avoid silent no-ops when the line is commented, lacks the export prefix,
+    // or has leading whitespace)
+    // Negative lookahead excludes commented lines (e.g. # export OPENCLAW_HOOKS_TOKEN=...)
+    const existingExportRegex = /^(?!\s*#)\s*(?:export\s+)?OPENCLAW_HOOKS_TOKEN=.*$/m;
+    if (existsSync(profilePath)) {
+      const content = readFileSync(profilePath, "utf-8");
+      if (existingExportRegex.test(content)) {
+        // Replace the existing line
+        const updated = content.replace(existingExportRegex, exportLine);
+        writeFileSync(profilePath, updated);
+        return profilePath;
+      }
+    }
+
+    // Append
+    const prefix = existsSync(profilePath) ? "\n" : "";
+    writeFileSync(profilePath, `${prefix}# Added by ao setup openclaw\n${exportLine}\n`, {
+      flag: "a",
+    });
+    return profilePath;
+  } catch {
+    return undefined;
+  }
+}
+
+function printOpenClawInstructions(
+  nonInteractive: boolean,
+  openclawConfigWritten: boolean,
+  shellProfilePath: string | undefined,
+): void {
+  if (openclawConfigWritten) {
+    // Both configs written automatically
+    if (nonInteractive) {
+      console.log(
+        chalk.green("✓ Both configs written (agent-orchestrator.yaml + ~/.openclaw/openclaw.json)"),
+      );
+      if (shellProfilePath) {
+        console.log(chalk.green(`✓ OPENCLAW_HOOKS_TOKEN exported in ${shellProfilePath}`));
+      }
+      console.log("Restart OpenClaw gateway to apply.");
+    } else {
+      console.log(`\n${chalk.green.bold("Done — both configs written.")}`);
+      console.log(chalk.dim("  agent-orchestrator.yaml  — notifiers.openclaw block"));
+      console.log(chalk.dim("  ~/.openclaw/openclaw.json — hooks block"));
+      if (shellProfilePath) {
+        console.log(chalk.dim(`  ${shellProfilePath} — OPENCLAW_HOOKS_TOKEN export`));
+      }
+      console.log(`\n${chalk.yellow("Restart OpenClaw gateway to apply.")}`);
+    }
+  } else {
+    // Fallback: could not write OpenClaw config, print manual instructions
+    const instructions = `
+${chalk.bold("OpenClaw-side config required")}
+
+AO config was written successfully. Add this to your OpenClaw config (${chalk.dim("~/.openclaw/openclaw.json")}):
+
+  ${chalk.cyan(`{
+    "hooks": {
+      "enabled": true,
+      "token": "<same-token-you-entered-above>",
+      "allowRequestSessionKey": true,
+      "allowedSessionKeyPrefixes": ["hook:"]
+    }
+  }`)}
+`;
+
+    if (nonInteractive) {
+      console.log("\nOpenClaw-side config required:");
+      console.log("AO config was written successfully. Add to ~/.openclaw/openclaw.json:");
+      console.log("  hooks.enabled: true");
+      console.log('  hooks.token: "<your-token>"');
+      console.log("  hooks.allowRequestSessionKey: true");
+      console.log('  hooks.allowedSessionKeyPrefixes: ["hook:"]');
+    } else {
+      console.log(instructions);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerSetup(program: Command): void {
+  const setup = program.command("setup").description("Set up integrations with external services");
+
+  setup
+    .command("openclaw")
+    .description("Connect AO notifications to an OpenClaw gateway")
+    .option("--url <url>", "OpenClaw webhook URL (e.g. http://127.0.0.1:18789/hooks/agent)")
+    .option("--token <token>", "OpenClaw hooks auth token")
+    .option("--non-interactive", "Skip prompts — requires --url (token auto-generated if not provided)")
+    .action(async (opts: SetupOptions) => {
+      try {
+        await runSetupAction(opts);
+      } catch (err) {
+        if (err instanceof SetupAbortedError) {
+          console.error(err.message);
+          process.exit(err.exitCode);
+        }
+        throw err;
+      }
+    });
+}
+
+async function runSetupAction(opts: SetupOptions): Promise<void> {
+  const nonInteractive = opts.nonInteractive || !process.stdin.isTTY;
+
+  // --- Find existing config ------------------------------------------------
+  let configPath: string | undefined;
+  try {
+    const found = findConfigFile();
+    configPath = found ?? undefined;
+  } catch {
+    // no config found
+  }
+
+  if (!configPath) {
+    throw new SetupAbortedError(
+      "No agent-orchestrator.yaml found. Run 'ao start' first to create one.",
+    );
+  }
+
+  // --- Check for existing openclaw config ----------------------------------
+  const rawYaml = readFileSync(configPath, "utf-8");
+  const rawConfig = yamlParse(rawYaml) ?? {};
+  const existingOpenClaw = rawConfig?.notifiers?.openclaw;
+  const existingUrl = existingOpenClaw?.url as string | undefined;
+
+  if (existingOpenClaw && !nonInteractive) {
+    const clack = await import("@clack/prompts");
+    const reconfigure = await clack.confirm({
+      message: "OpenClaw is already configured. Reconfigure?",
+      initialValue: false,
+    });
+
+    if (clack.isCancel(reconfigure) || !reconfigure) {
+      console.log(chalk.dim("Keeping existing config."));
+      return;
+    }
+  }
+
+  // --- Run setup -----------------------------------------------------------
+  let resolved: ResolvedConfig;
+
+  if (nonInteractive) {
+    resolved = await nonInteractiveSetup(opts);
+  } else {
+    resolved = await interactiveSetup(existingUrl);
+  }
+
+  // --- Write AO config -----------------------------------------------------
+  writeOpenClawConfig(configPath, resolved, nonInteractive);
+
+  // --- Write OpenClaw config -----------------------------------------------
+  const openclawConfigWritten = writeOpenClawJsonConfig(resolved.token);
+  if (openclawConfigWritten && nonInteractive) {
+    console.log(chalk.green("✓ Wrote hooks config to ~/.openclaw/openclaw.json"));
+  }
+
+  // --- Write shell export --------------------------------------------------
+  const shellProfilePath = writeShellExport(resolved.token);
+  if (shellProfilePath && nonInteractive) {
+    console.log(chalk.green(`✓ Exported OPENCLAW_HOOKS_TOKEN in ${shellProfilePath}`));
+  }
+
+  // --- Print instructions --------------------------------------------------
+  printOpenClawInstructions(nonInteractive, openclawConfigWritten, shellProfilePath);
+
+  // --- Done ----------------------------------------------------------------
+  if (!nonInteractive) {
+    const clack = await import("@clack/prompts");
+    clack.outro(
+      `${chalk.green("Setup complete!")} AO will send notifications to OpenClaw.\n` +
+        chalk.dim("  Run 'ao doctor' to verify the full setup.\n") +
+        chalk.dim("  Restart AO with 'ao stop && ao start' to activate."),
+    );
+  } else {
+    console.log(chalk.green("\n✓ OpenClaw setup complete."));
+    console.log(chalk.dim("Restart AO to activate: ao stop && ao start"));
+  }
+}

packages/cli/src/index.ts

@@ -14,6 +14,7 @@ import { registerLifecycleWorker } from "./commands/lifecycle-worker.js";
 import { registerVerify } from "./commands/verify.js";
 import { registerDoctor } from "./commands/doctor.js";
 import { registerUpdate } from "./commands/update.js";
+import { registerSetup } from "./commands/setup.js";
 import { getConfigInstruction } from "./lib/config-instruction.js";
 
 const program = new Command();
@@ -38,6 +39,7 @@ registerLifecycleWorker(program);
 registerVerify(program);
 registerDoctor(program);
 registerUpdate(program);
+registerSetup(program);
 
 program
   .command("config-help")

packages/cli/src/lib/config-instruction.ts

@@ -22,7 +22,7 @@ defaults:
   agent: claude-code          # claude-code | aider | codex | opencode
   workspace: worktree         # worktree | clone
   notifiers:                  # List of active notifier plugins
-    - desktop                 # desktop | slack | webhook | composio | openclaw
+    - desktop                 # desktop | discord | slack | webhook | composio | openclaw
   orchestrator:
     agent: claude-code        # Agent for orchestrator sessions (optional override)
   worker:
@@ -102,6 +102,11 @@ notifiers:
   webhook:
     plugin: webhook
     # url: https://example.com/hook
+  openclaw:
+    plugin: openclaw
+    # url: http://127.0.0.1:18789/hooks/agent
+    # token: \${OPENCLAW_HOOKS_TOKEN}
+    # Run 'ao setup openclaw' for guided configuration
 
 # ── Notification routing (optional) ─────────────────────────────────
 # Route notifications by priority level.
@@ -122,7 +127,7 @@ notificationRouting:
 # Workspace: worktree, clone
 # SCM:       github, gitlab
 # Tracker:   github, linear, gitlab
-# Notifier:  desktop, slack, webhook, composio, openclaw
+# Notifier:  desktop, discord, slack, webhook, composio, openclaw
 # Terminal:  iterm2, web
 `.trim();
 }

packages/cli/src/lib/openclaw-probe.ts

@@ -0,0 +1,128 @@
+/**
+ * OpenClaw gateway probing utilities.
+ *
+ * Used by `ao setup openclaw` and future TypeScript-based doctor checks.
+ * Probes the OpenClaw gateway for reachability and validates auth tokens.
+ */
+
+export interface ProbeResult {
+  reachable: boolean;
+  httpStatus?: number;
+  error?: string;
+}
+
+export interface TokenValidation {
+  valid: boolean;
+  error?: string;
+}
+
+const DEFAULT_TIMEOUT_MS = 3_000;
+const DEFAULT_OPENCLAW_URL = "http://127.0.0.1:18789";
+const HOOKS_PATH = "/hooks/agent";
+
+/**
+ * Probe the OpenClaw gateway for reachability.
+ * Sends a GET to the base URL (not /hooks/agent) with a short timeout.
+ */
+export async function probeGateway(
+  baseUrl: string = DEFAULT_OPENCLAW_URL,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): Promise<ProbeResult> {
+  const url = baseUrl.replace(/\/+$/, "");
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      signal: controller.signal,
+    });
+
+    return { reachable: true, httpStatus: response.status };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    if (message.includes("ECONNREFUSED")) {
+      return { reachable: false, error: `Gateway not reachable at ${url}` };
+    }
+    if (message.includes("abort") || message.includes("timeout")) {
+      return { reachable: false, error: `Gateway timed out at ${url} (${timeoutMs}ms)` };
+    }
+
+    return { reachable: false, error: message };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Validate an auth token against the OpenClaw hooks endpoint.
+ * Sends a lightweight test payload and checks the response.
+ */
+export async function validateToken(
+  url: string,
+  token: string,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): Promise<TokenValidation> {
+  const hooksUrl = url.includes(HOOKS_PATH) ? url : `${url.replace(/\/+$/, "")}${HOOKS_PATH}`;
+
+  const payload = {
+    message: "[AO Setup] Connection test — you can ignore this message.",
+    name: "AO",
+    sessionKey: "hook:ao:setup-test",
+    wakeMode: "now",
+    deliver: false,
+  };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(hooksUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+
+    if (response.ok) {
+      return { valid: true };
+    }
+
+    if (response.status === 401 || response.status === 403) {
+      return {
+        valid: false,
+        error:
+          "Token rejected by OpenClaw. Check that hooks.token in your OpenClaw config matches this token.",
+      };
+    }
+
+    const body = await response.text().catch(() => "");
+    return {
+      valid: false,
+      error: `Unexpected response (HTTP ${response.status})${body ? `: ${body.trim()}` : ""}`,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    if (message.includes("ECONNREFUSED")) {
+      return {
+        valid: false,
+        error: `Can't reach OpenClaw gateway. Is OpenClaw running?`,
+      };
+    }
+    if (message.includes("abort") || message.includes("timeout")) {
+      return {
+        valid: false,
+        error: `Connection timed out. Check the gateway URL and network.`,
+      };
+    }
+
+    return { valid: false, error: message };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export { DEFAULT_OPENCLAW_URL, HOOKS_PATH };

packages/core/src/plugin-registry.ts

@@ -45,6 +45,7 @@ const BUILTIN_PLUGINS: Array<{ slot: PluginSlot; name: string; pkg: string }> =
   // Notifiers
   { slot: "notifier", name: "composio", pkg: "@composio/ao-plugin-notifier-composio" },
   { slot: "notifier", name: "desktop", pkg: "@composio/ao-plugin-notifier-desktop" },
+  { slot: "notifier", name: "discord", pkg: "@composio/ao-plugin-notifier-discord" },
   { slot: "notifier", name: "openclaw", pkg: "@composio/ao-plugin-notifier-openclaw" },
   { slot: "notifier", name: "slack", pkg: "@composio/ao-plugin-notifier-slack" },
   { slot: "notifier", name: "webhook", pkg: "@composio/ao-plugin-notifier-webhook" },

packages/integration-tests/src/agent-claude-code.integration.test.ts

@@ -139,6 +139,7 @@ describe.skipIf(!realProject)("path encoding & JSONL reading (real Claude data)"
         "user",
         "assistant",
         "system",
+        "last-prompt",
         "tool_use",
         "progress",
         "permission_request",

packages/mobile/src/screens/SessionDetailScreen.tsx

@@ -97,13 +97,25 @@ export default function SessionDetailScreen({ route, navigation }: Props) {
     );
   }, [killSession, sessionId, refresh]);
 
-  const handleRestore = useCallback(async () => {
-    try {
-      await restoreSession(sessionId);
-      refresh();
-    } catch (err) {
-      Alert.alert("Error", err instanceof Error ? err.message : "Failed to restore session");
-    }
+  const handleRestore = useCallback(() => {
+    Alert.alert(
+      "Restore Session",
+      "This will restore the session and make it active again. Are you sure?",
+      [
+        { text: "Cancel", style: "cancel" },
+        {
+          text: "Restore",
+          onPress: async () => {
+            try {
+              await restoreSession(sessionId);
+              refresh();
+            } catch (err) {
+              Alert.alert("Error", err instanceof Error ? err.message : "Failed to restore session");
+            }
+          },
+        },
+      ],
+    );
   }, [restoreSession, sessionId, refresh]);
 
   const handleOpenTerminal = useCallback(() => {

packages/plugins/notifier-discord/README.md

@@ -0,0 +1,39 @@
+# notifier-discord
+
+Discord webhook notifier plugin for AO. Sends rich embed notifications for session events, PR creation, CI status, and escalations.
+
+## Setup
+
+1. In your Discord server: **Server Settings > Integrations > Webhooks > New Webhook**
+2. Copy the webhook URL
+3. Add to `agent-orchestrator.yaml`:
+
+```yaml
+defaults:
+  notifiers:
+    - desktop
+    - discord
+
+notifiers:
+  discord:
+    plugin: discord
+    webhookUrl: https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
+```
+
+## Config options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `webhookUrl` | (required) | Discord webhook URL |
+| `username` | "Agent Orchestrator" | Bot display name |
+| `avatarUrl` | (none) | Bot avatar image URL |
+| `threadId` | (none) | Post to a specific thread |
+| `retries` | 2 | Retry attempts on 5xx |
+| `retryDelayMs` | 1000 | Base retry delay (exponential backoff) |
+
+## Features
+
+- Rich embeds with color-coded priority (red=urgent, blue=action, yellow=warning, green=info)
+- PR links, CI status, and action buttons in embed fields
+- Thread support for organizing notifications by project
+- Retry with exponential backoff on 5xx responses

packages/plugins/notifier-discord/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@composio/ao-plugin-notifier-discord",
+  "version": "0.1.0",
+  "description": "Notifier plugin: Discord webhook notifications",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ComposioHQ/agent-orchestrator.git",
+    "directory": "packages/plugins/notifier-discord"
+  },
+  "homepage": "https://github.com/ComposioHQ/agent-orchestrator",
+  "bugs": {
+    "url": "https://github.com/ComposioHQ/agent-orchestrator/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@composio/ao-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

packages/plugins/notifier-discord/src/index.test.ts

@@ -0,0 +1,244 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { NotifyAction, OrchestratorEvent } from "@composio/ao-core";
+import { create, manifest } from "./index.js";
+
+function makeEvent(overrides: Partial<OrchestratorEvent> = {}): OrchestratorEvent {
+  return {
+    id: "evt-1",
+    type: "reaction.escalated",
+    priority: "urgent",
+    sessionId: "ao-5",
+    projectId: "ao",
+    timestamp: new Date("2026-03-20T12:00:00Z"),
+    message: "CI failed after 5 retries",
+    data: { attempts: 5, reason: "ci_failed" },
+    ...overrides,
+  };
+}
+
+describe("notifier-discord", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("has correct manifest", () => {
+    expect(manifest.name).toBe("discord");
+    expect(manifest.slot).toBe("notifier");
+  });
+
+  it("posts to Discord webhook URL", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc" });
+    await notifier.notify(makeEvent());
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(fetchMock.mock.calls[0][0]).toBe("https://discord.com/api/webhooks/123/abc");
+  });
+
+  it("sends Discord embed with correct structure", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc" });
+    await notifier.notify(makeEvent());
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    expect(body.username).toBe("Agent Orchestrator");
+    expect(body.embeds).toHaveLength(1);
+
+    const embed = body.embeds[0];
+    expect(embed.title).toContain("ao-5");
+    expect(embed.title).toContain("reaction.escalated");
+    expect(embed.description).toBe("CI failed after 5 retries");
+    expect(embed.color).toBe(0xed4245); // red for urgent
+    expect(embed.timestamp).toBe("2026-03-20T12:00:00.000Z");
+    expect(embed.footer.text).toBe("Agent Orchestrator");
+  });
+
+  it("includes project and priority fields", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc" });
+    await notifier.notify(makeEvent());
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    const fields = body.embeds[0].fields;
+    expect(fields).toContainEqual(expect.objectContaining({ name: "Project", value: "ao" }));
+    expect(fields).toContainEqual(expect.objectContaining({ name: "Priority", value: "urgent" }));
+  });
+
+  it("includes PR link when available", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc" });
+    await notifier.notify(makeEvent({ data: { prUrl: "https://github.com/org/repo/pull/42" } }));
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    const prField = body.embeds[0].fields.find((f: { name: string }) => f.name === "Pull Request");
+    expect(prField.value).toContain("https://github.com/org/repo/pull/42");
+  });
+
+  it("includes CI status when available", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc" });
+    await notifier.notify(makeEvent({ data: { ciStatus: "passing" } }));
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    const ciField = body.embeds[0].fields.find((f: { name: string }) => f.name === "CI");
+    expect(ciField.value).toContain("passing");
+  });
+
+  it("notifyWithActions includes action links", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc" });
+    const actions: NotifyAction[] = [
+      { label: "View PR", url: "https://github.com/org/repo/pull/42" },
+      { label: "retry" },
+    ];
+    await notifier.notifyWithActions!(makeEvent(), actions);
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    const actionsField = body.embeds[0].fields.find((f: { name: string }) => f.name === "Actions");
+    expect(actionsField.value).toContain("View PR");
+    expect(actionsField.value).toContain("retry");
+  });
+
+  it("post sends plain content message", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc" });
+    await notifier.post!("Session ao-5 completed successfully");
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    expect(body.content).toBe("Session ao-5 completed successfully");
+    expect(body.embeds).toBeUndefined();
+  });
+
+  it("uses custom username when configured", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc", username: "AO Bot" });
+    await notifier.notify(makeEvent());
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    expect(body.username).toBe("AO Bot");
+  });
+
+  it("includes avatar_url when configured", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({
+      webhookUrl: "https://discord.com/api/webhooks/123/abc",
+      avatarUrl: "https://example.com/avatar.png",
+    });
+    await notifier.notify(makeEvent());
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    expect(body.avatar_url).toBe("https://example.com/avatar.png");
+  });
+
+  it("includes thread_id when configured", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({
+      webhookUrl: "https://discord.com/api/webhooks/123/abc",
+      threadId: "1234567890",
+    });
+    await notifier.notify(makeEvent());
+
+    // Discord requires thread_id as a URL query param, not in the JSON body
+    const calledUrl = fetchMock.mock.calls[0][0];
+    expect(calledUrl).toBe("https://discord.com/api/webhooks/123/abc?thread_id=1234567890");
+  });
+
+  it("is a no-op when webhookUrl not configured", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create();
+    await notifier.notify(makeEvent());
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("No webhookUrl configured"));
+  });
+
+  it("uses correct color for each priority", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc" });
+
+    await notifier.notify(makeEvent({ priority: "info" }));
+    let body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    expect(body.embeds[0].color).toBe(0x57f287); // green
+
+    await notifier.notify(makeEvent({ priority: "warning" }));
+    body = JSON.parse(fetchMock.mock.calls[1][1].body);
+    expect(body.embeds[0].color).toBe(0xfee75c); // yellow
+  });
+
+  it("handles 204 No Content as success", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 204 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ webhookUrl: "https://discord.com/api/webhooks/123/abc" });
+    await expect(notifier.notify(makeEvent())).resolves.toBeUndefined();
+  });
+
+  it("retries on 5xx response", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({ ok: false, status: 503, text: () => Promise.resolve("down") })
+      .mockResolvedValueOnce({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({
+      webhookUrl: "https://discord.com/api/webhooks/123/abc",
+      retries: 1,
+      retryDelayMs: 50,
+    });
+    const promise = notifier.notify(makeEvent());
+
+    await vi.advanceTimersByTimeAsync(0);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(50);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    await promise;
+    vi.useRealTimers();
+  });
+
+  it("does not retry on 4xx response", async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue({ ok: false, status: 401, text: () => Promise.resolve("unauthorized") });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({
+      webhookUrl: "https://discord.com/api/webhooks/123/abc",
+      retries: 2,
+      retryDelayMs: 1,
+    });
+    await expect(notifier.notify(makeEvent())).rejects.toThrow("Discord webhook failed (401)");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});

packages/plugins/notifier-discord/src/index.ts

@@ -0,0 +1,219 @@
+import {
+  validateUrl,
+  type PluginModule,
+  type Notifier,
+  type OrchestratorEvent,
+  type NotifyAction,
+  type NotifyContext,
+  type EventPriority,
+  CI_STATUS,
+} from "@composio/ao-core";
+import { isRetryableHttpStatus, normalizeRetryConfig } from "@composio/ao-core/utils";
+
+export const manifest = {
+  name: "discord",
+  slot: "notifier" as const,
+  description: "Notifier plugin: Discord webhook notifications with rich embeds",
+  version: "0.1.0",
+};
+
+// Discord embed color codes (decimal)
+const PRIORITY_COLOR: Record<EventPriority, number> = {
+  urgent: 0xed4245, // red
+  action: 0x5865f2, // blurple
+  warning: 0xfee75c, // yellow
+  info: 0x57f287, // green
+};
+
+const PRIORITY_EMOJI: Record<EventPriority, string> = {
+  urgent: "\u{1F6A8}", // rotating light
+  action: "\u{1F449}", // point right
+  warning: "\u{26A0}\u{FE0F}", // warning
+  info: "\u{2139}\u{FE0F}", // info
+};
+
+const DISCORD_WEBHOOK_URL_RE =
+  /^https:\/\/(?:discord\.com|discordapp\.com)\/api\/webhooks\//;
+
+const EMBED_DESCRIPTION_MAX = 4096;
+
+interface DiscordEmbed {
+  title: string;
+  description: string;
+  color: number;
+  fields?: { name: string; value: string; inline?: boolean }[];
+  timestamp?: string;
+  footer?: { text: string };
+}
+
+function buildEmbed(event: OrchestratorEvent, actions?: NotifyAction[]): DiscordEmbed {
+  const emoji = PRIORITY_EMOJI[event.priority];
+  const description =
+    event.message.length > EMBED_DESCRIPTION_MAX
+      ? event.message.slice(0, EMBED_DESCRIPTION_MAX - 1) + "\u2026"
+      : event.message;
+  const embed: DiscordEmbed = {
+    title: `${emoji} ${event.type} — ${event.sessionId}`,
+    description,
+    color: PRIORITY_COLOR[event.priority],
+    fields: [
+      { name: "Project", value: event.projectId, inline: true },
+      { name: "Priority", value: event.priority, inline: true },
+    ],
+    timestamp: event.timestamp.toISOString(),
+    footer: { text: "Agent Orchestrator" },
+  };
+
+  // Add PR link if available
+  const prUrl = typeof event.data.prUrl === "string" ? event.data.prUrl : undefined;
+  if (prUrl) {
+    embed.fields!.push({ name: "Pull Request", value: `[View PR](${prUrl})`, inline: false });
+  }
+
+  // Add CI status if available
+  const ciStatus = typeof event.data.ciStatus === "string" ? event.data.ciStatus : undefined;
+  if (ciStatus) {
+    const ciEmoji = ciStatus === CI_STATUS.PASSING ? "\u{2705}" : "\u{274C}";
+    embed.fields!.push({ name: "CI", value: `${ciEmoji} ${ciStatus}`, inline: true });
+  }
+
+  // Add actions as a field
+  if (actions && actions.length > 0) {
+    const actionLinks = actions.map((a) => {
+      if (a.url) return `[${a.label}](${a.url})`;
+      return `\`${a.label}\``;
+    });
+    embed.fields!.push({ name: "Actions", value: actionLinks.join(" | "), inline: false });
+  }
+
+  return embed;
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+async function postWithRetry(
+  webhookUrl: string,
+  payload: Record<string, unknown>,
+  retries: number,
+  retryDelayMs: number,
+): Promise<void> {
+  let lastError: Error | undefined;
+  // Separate counter for 429 Retry-After waits so they don't consume the error
+  // retry budget — a server-mandated wait shouldn't cost a retry slot.
+  let rateLimitRetries = 0;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    try {
+      const response = await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+
+      if (response.ok || response.status === 204) return;
+
+      // Handle rate limiting: wait then retry without burning an error retry slot.
+      // Use Retry-After if present, otherwise fall back to retryDelayMs.
+      if (response.status === 429) {
+        if (rateLimitRetries < retries) {
+          const retryAfter = response.headers.get("Retry-After");
+          const waitMs = retryAfter ? (parseFloat(retryAfter) || 1) * 1000 : retryDelayMs;
+          await new Promise((resolve) => setTimeout(resolve, waitMs));
+          rateLimitRetries++;
+          attempt--; // undo the for-loop increment so error budget is preserved
+          continue;
+        }
+        // Rate-limit budget exhausted — fail immediately rather than falling through
+        // to the error retry path (which would compound the two counters).
+        const body = await response.text().catch(() => "");
+        lastError = new Error(`Discord webhook rate-limited (HTTP 429)${body ? `: ${body.trim()}` : ""}`);
+        throw lastError;
+      }
+
+      const body = await response.text();
+      lastError = new Error(`Discord webhook failed (${response.status}): ${body}`);
+
+      if (!isRetryableHttpStatus(response.status)) {
+        throw lastError;
+      }
+    } catch (err) {
+      if (err === lastError) throw err;
+      lastError = err instanceof Error ? err : new Error(String(err));
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (attempt < retries) {
+      const delay = retryDelayMs * 2 ** attempt;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError;
+}
+
+export function create(config?: Record<string, unknown>): Notifier {
+  const webhookUrl = config?.webhookUrl as string | undefined;
+  const username = (config?.username as string) ?? "Agent Orchestrator";
+  const avatarUrl = config?.avatarUrl as string | undefined;
+  const threadId = config?.threadId as string | undefined;
+
+  const { retries, retryDelayMs } = normalizeRetryConfig(config);
+
+  if (!webhookUrl) {
+    console.warn(
+      "[notifier-discord] No webhookUrl configured.\n" +
+      "  Set it in agent-orchestrator.yaml under notifiers.discord.webhookUrl\n" +
+      "  Create a webhook: Discord Server Settings > Integrations > Webhooks > New Webhook",
+    );
+  } else {
+    validateUrl(webhookUrl, "notifier-discord");
+    if (!DISCORD_WEBHOOK_URL_RE.test(webhookUrl)) {
+      console.warn(
+        "[notifier-discord] webhookUrl does not match expected Discord webhook format.\n" +
+        "  Expected: https://discord.com/api/webhooks/... or https://discordapp.com/api/webhooks/...",
+      );
+    }
+  }
+
+  // Discord requires thread_id as a URL query param, not in the JSON body
+  const effectiveUrl = webhookUrl && threadId
+    ? `${webhookUrl}${webhookUrl.includes("?") ? "&" : "?"}thread_id=${encodeURIComponent(threadId)}`
+    : webhookUrl;
+
+  function buildPayload(embeds: DiscordEmbed[]): Record<string, unknown> {
+    const payload: Record<string, unknown> = { username, embeds };
+    if (avatarUrl) payload.avatar_url = avatarUrl;
+    return payload;
+  }
+
+  return {
+    name: "discord",
+
+    async notify(event: OrchestratorEvent): Promise<void> {
+      if (!effectiveUrl) return;
+      const payload = buildPayload([buildEmbed(event)]);
+      await postWithRetry(effectiveUrl, payload, retries, retryDelayMs);
+    },
+
+    async notifyWithActions(event: OrchestratorEvent, actions: NotifyAction[]): Promise<void> {
+      if (!effectiveUrl) return;
+      const payload = buildPayload([buildEmbed(event, actions)]);
+      await postWithRetry(effectiveUrl, payload, retries, retryDelayMs);
+    },
+
+    async post(message: string, _context?: NotifyContext): Promise<string | null> {
+      if (!effectiveUrl) return null;
+      const payload: Record<string, unknown> = { username, content: message };
+      if (avatarUrl) payload.avatar_url = avatarUrl;
+      // thread_id is already passed as a URL query param via effectiveUrl
+      await postWithRetry(effectiveUrl, payload, retries, retryDelayMs);
+      return null;
+    },
+  };
+}
+
+export default { manifest, create } satisfies PluginModule<Notifier>;

packages/plugins/notifier-discord/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

packages/plugins/notifier-openclaw/README.md

@@ -2,6 +2,18 @@
 
 OpenClaw notifier plugin for AO escalation events.
 
+## Quick setup
+
+```bash
+ao setup openclaw
+```
+
+This interactive wizard auto-detects your OpenClaw gateway, validates the connection, and writes the config. For non-interactive use (e.g., in CI/CD pipelines or automation scripts):
+
+```bash
+ao setup openclaw --url http://127.0.0.1:18789/hooks/agent --token YOUR_TOKEN --non-interactive
+```
+
 ## Required OpenClaw config (`openclaw.json`)
 
 ```json

packages/plugins/notifier-openclaw/src/index.test.ts

@@ -169,7 +169,17 @@ describe("notifier-openclaw", () => {
     vi.stubGlobal("fetch", fetchMock);
 
     const notifier = create({ token: "tok", retries: 2, retryDelayMs: 1 });
-    await expect(notifier.notify(makeEvent())).rejects.toThrow("OpenClaw webhook failed (401)");
+    await expect(notifier.notify(makeEvent())).rejects.toThrow("OpenClaw rejected the auth token");
     expect(fetchMock).toHaveBeenCalledTimes(1);
   });
+
+  it("throws actionable error on ECONNREFUSED", async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new Error("fetch failed: ECONNREFUSED"));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const notifier = create({ token: "tok", retries: 0 });
+    await expect(notifier.notify(makeEvent())).rejects.toThrow(
+      "Can't reach OpenClaw gateway",
+    );
+  });
 });

packages/plugins/notifier-openclaw/src/index.ts

@@ -1,3 +1,6 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import {
   type EventPriority,
   type Notifier,
@@ -8,6 +11,25 @@ import {
 } from "@composio/ao-core";
 import { isRetryableHttpStatus, normalizeRetryConfig, validateUrl } from "@composio/ao-core/utils";
 
+/**
+ * Read the hooks token from ~/.openclaw/openclaw.json as a fallback for
+ * daemon contexts where the shell profile (and OPENCLAW_HOOKS_TOKEN) isn't
+ * sourced. This file is written by `ao setup openclaw` and lives outside
+ * the project directory so it's never committed to version control.
+ */
+function readTokenFromOpenClawConfig(): string | undefined {
+  try {
+    const configPath = join(homedir(), ".openclaw", "openclaw.json");
+    if (!existsSync(configPath)) return undefined;
+    const raw = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(raw) as Record<string, unknown>;
+    const token = (config.hooks as Record<string, unknown> | undefined)?.token;
+    return typeof token === "string" && token ? token : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export const manifest = {
   name: "openclaw",
   slot: "notifier" as const,
@@ -15,6 +37,8 @@ export const manifest = {
   version: "0.1.0",
 };
 
+const DEFAULT_TIMEOUT_MS = 10_000;
+
 type WakeMode = "now" | "next-heartbeat";
 
 interface OpenClawWebhookPayload {
@@ -36,16 +60,29 @@ async function postWithRetry(
   let lastError: Error | undefined;
 
   for (let attempt = 0; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
     try {
       const response = await fetch(url, {
         method: "POST",
         headers,
         body: JSON.stringify(payload),
+        signal: controller.signal,
       });
 
       if (response.ok) return;
 
       const body = await response.text();
+
+      if (response.status === 401 || response.status === 403) {
+        lastError = new Error(
+          `OpenClaw rejected the auth token (HTTP ${response.status}).\n` +
+            `  Check that hooks.token in your OpenClaw config matches the token configured for AO.\n` +
+            `  Reconfigure: ao setup openclaw`,
+        );
+        throw lastError;
+      }
+
       lastError = new Error(`OpenClaw webhook failed (${response.status}): ${body}`);
 
       if (!isRetryableHttpStatus(response.status)) {
@@ -61,11 +98,22 @@ async function postWithRetry(
       if (err === lastError) throw err;
       lastError = err instanceof Error ? err : new Error(String(err));
 
+      if (lastError.message.includes("ECONNREFUSED")) {
+        throw new Error(
+          `Can't reach OpenClaw gateway at ${url}.\n` +
+            `  Is OpenClaw running? Check: openclaw status\n` +
+            `  Wrong URL? Run: ao setup openclaw`,
+          { cause: err },
+        );
+      }
+
       if (attempt < retries) {
         console.warn(
           `[notifier-openclaw] Retry ${attempt + 1}/${retries} for session=${context.sessionId} after network error: ${lastError.message}`,
         );
       }
+    } finally {
+      clearTimeout(timer);
     }
 
     if (attempt < retries) {
@@ -108,13 +156,26 @@ function formatActionsLine(actions: NotifyAction[]): string {
   return `Actions available: ${labels}`;
 }
 
+/**
+ * Resolve a token value that may be a `${ENV_VAR}` placeholder (as written
+ * into agent-orchestrator.yaml by `ao setup openclaw`) or a literal string.
+ * Returns undefined for empty/unresolvable values so callers can chain `??`.
+ */
+function resolveEnvVarToken(raw: unknown): string | undefined {
+  if (typeof raw !== "string" || !raw) return undefined;
+  const match = raw.match(/^\$\{([^}]+)\}$/);
+  if (match) return process.env[match[1]] || undefined;
+  return raw;
+}
+
 export function create(config?: Record<string, unknown>): Notifier {
   const url =
     (typeof config?.url === "string" ? config.url : undefined) ??
     "http://127.0.0.1:18789/hooks/agent";
   const token =
-    (typeof config?.token === "string" ? config.token : undefined) ??
-    process.env.OPENCLAW_HOOKS_TOKEN;
+    resolveEnvVarToken(config?.token) ??
+    process.env.OPENCLAW_HOOKS_TOKEN ??
+    readTokenFromOpenClawConfig();
   const senderName = typeof config?.name === "string" ? config.name : "AO";
   const sessionKeyPrefix =
     typeof config?.sessionKeyPrefix === "string" ? config.sessionKeyPrefix : "hook:ao:";
@@ -127,7 +188,9 @@ export function create(config?: Record<string, unknown>): Notifier {
 
   if (!token) {
     console.warn(
-      "[notifier-openclaw] No token configured (token or OPENCLAW_HOOKS_TOKEN). Sending without Authorization header.",
+      "[notifier-openclaw] No token configured.\n" +
+        "  Set OPENCLAW_HOOKS_TOKEN env var, or add token to your notifier config.\n" +
+        "  Run: ao setup openclaw",
     );
   }
 

packages/web/.gitignore

@@ -1 +1,2 @@
 build/
+dist-server/

packages/web/next.config.js

@@ -10,6 +10,17 @@ const nextConfig = {
     "@composio/ao-plugin-tracker-linear",
     "@composio/ao-plugin-workspace-worktree",
   ],
+  async headers() {
+    return [
+      {
+        source: "/sw.js",
+        headers: [
+          { key: "Cache-Control", value: "no-cache, no-store, must-revalidate" },
+          { key: "Service-Worker-Allowed", value: "/" },
+        ],
+      },
+    ];
+  },
 };
 
 export default nextConfig;

packages/web/public/offline.html

@@ -0,0 +1,86 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+  <title>Offline | ao</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      background: #0a0d12;
+      color: #e6edf3;
+      min-height: 100dvh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 24px;
+      padding-top: env(safe-area-inset-top, 24px);
+      padding-bottom: env(safe-area-inset-bottom, 24px);
+    }
+    .container {
+      text-align: center;
+      max-width: 400px;
+    }
+    .icon {
+      width: 64px;
+      height: 64px;
+      margin: 0 auto 24px;
+      border-radius: 12px;
+      background: hsl(220, 15%, 20%);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .icon svg {
+      width: 32px;
+      height: 32px;
+      stroke: #8b949e;
+      fill: none;
+      stroke-width: 1.5;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+    }
+    h1 {
+      font-size: 20px;
+      font-weight: 600;
+      margin-bottom: 8px;
+      color: #e6edf3;
+    }
+    p {
+      font-size: 14px;
+      color: #8b949e;
+      line-height: 1.5;
+      margin-bottom: 24px;
+    }
+    button {
+      background: hsl(220, 15%, 18%);
+      color: #e6edf3;
+      border: 1px solid hsl(220, 15%, 25%);
+      padding: 12px 24px;
+      border-radius: 8px;
+      font-size: 14px;
+      font-weight: 500;
+      cursor: pointer;
+      min-height: 44px;
+      min-width: 44px;
+      transition: background 0.15s ease;
+    }
+    button:active {
+      background: hsl(220, 15%, 22%);
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="icon">
+      <svg viewBox="0 0 24 24">
+        <path d="M1 1l22 22M16.72 11.06A10.94 10.94 0 0119 12.55M5 12.55a10.94 10.94 0 015.17-2.39M10.71 5.05A16 16 0 0122.56 9M1.42 9a15.91 15.91 0 014.7-2.88M8.53 16.11a6 6 0 016.95 0M12 20h.01" />
+      </svg>
+    </div>
+    <h1>You are offline</h1>
+    <p>The ao dashboard requires a network connection. Please check your connection and try again.</p>
+    <button onclick="location.reload()">Retry</button>
+  </div>
+</body>
+</html>

packages/web/public/sw.js

@@ -0,0 +1,38 @@
+/* globals self, caches, fetch, Response, URL, console */
+const CACHE_NAME = "ao-pwa-v2";
+const OFFLINE_URL = "/offline.html";
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.add(OFFLINE_URL))
+  );
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) =>
+        Promise.all(
+          keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k))
+        )
+      )
+      .then(() => self.clients.claim())
+  );
+});
+
+self.addEventListener("fetch", (event) => {
+  if (event.request.mode !== "navigate") return;
+
+  const url = new URL(event.request.url);
+  if (url.origin !== self.location.origin) return;
+
+  event.respondWith(
+    fetch(event.request).catch((err) => {
+      console.warn("[SW] Navigation fetch failed:", err.message);
+      return caches.match(OFFLINE_URL).then((r) =>
+        r || new Response("Offline", { status: 503, headers: { "Content-Type": "text/plain" } })
+      );
+    })
+  );
+});

packages/web/src/__tests__/components.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { render, screen, fireEvent } from "@testing-library/react";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
 import { CIBadge, CICheckList } from "@/components/CIBadge";
 import { PRStatus } from "@/components/PRStatus";
 import { SessionCard } from "@/components/SessionCard";
@@ -426,6 +426,138 @@ describe("SessionCard", () => {
     render(<SessionCard session={session} />);
     expect(screen.getByRole("button", { name: /terminate session/i })).toBeInTheDocument();
   });
+
+  it("prevents duplicate quick-reply preset sends while a send is in flight", async () => {
+    let resolveSend: (() => void) | null = null;
+    const onSend = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveSend = resolve;
+        }),
+    );
+    const session = makeSession({
+      id: "respond-1",
+      status: "needs_input",
+      activity: "waiting_input",
+      summary: "Need approval to proceed",
+    });
+
+    render(<SessionCard session={session} onSend={onSend} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Continue" }));
+
+    expect(onSend).toHaveBeenCalledTimes(1);
+    expect(onSend).toHaveBeenCalledWith("respond-1", "continue");
+    expect(screen.getByRole("button", { name: "Sending..." })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "Abort" })).toBeDisabled();
+    expect(screen.getByRole("textbox", { name: /type a reply to the agent/i })).toBeDisabled();
+
+    fireEvent.click(screen.getByRole("button", { name: "Abort" }));
+    expect(onSend).toHaveBeenCalledTimes(1);
+
+    resolveSend?.();
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: "Sent" })).toBeInTheDocument();
+    });
+  });
+
+  it("prevents duplicate enter submits and only clears the textarea after send settles", async () => {
+    let resolveSend: (() => void) | null = null;
+    const onSend = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveSend = resolve;
+        }),
+    );
+    const session = makeSession({
+      id: "respond-2",
+      status: "needs_input",
+      activity: "waiting_input",
+      summary: "Need approval to proceed",
+    });
+
+    render(<SessionCard session={session} onSend={onSend} />);
+
+    const input = screen.getByRole("textbox", { name: /type a reply to the agent/i });
+    fireEvent.change(input, { target: { value: "please continue" } });
+    fireEvent.keyDown(input, { key: "Enter", code: "Enter" });
+
+    expect(onSend).toHaveBeenCalledTimes(1);
+    expect(onSend).toHaveBeenCalledWith("respond-2", "please continue");
+    expect(screen.getByRole("textbox", { name: /type a reply to the agent/i })).toBeDisabled();
+    expect(screen.getByDisplayValue("please continue")).toBeInTheDocument();
+
+    fireEvent.keyDown(screen.getByRole("textbox", { name: /type a reply to the agent/i }), {
+      key: "Enter",
+      code: "Enter",
+    });
+    expect(onSend).toHaveBeenCalledTimes(1);
+
+    resolveSend?.();
+
+    await waitFor(() => {
+      expect(screen.getByRole("textbox", { name: /type a reply to the agent/i })).toHaveValue("");
+    });
+  });
+
+  it("does not show sent state or clear reply text when quick reply send fails", async () => {
+    const onSend = vi.fn(() => Promise.reject(new Error("network failed")));
+    const session = makeSession({
+      id: "respond-3",
+      status: "needs_input",
+      activity: "waiting_input",
+      summary: "Need approval to proceed",
+    });
+
+    render(<SessionCard session={session} onSend={onSend} />);
+
+    const input = screen.getByRole("textbox", { name: /type a reply to the agent/i });
+    fireEvent.change(input, { target: { value: "please continue" } });
+    fireEvent.keyDown(input, { key: "Enter", code: "Enter" });
+
+    await waitFor(() => {
+      expect(onSend).toHaveBeenCalledTimes(1);
+    });
+
+    expect(screen.queryByRole("button", { name: "Sent" })).not.toBeInTheDocument();
+    expect(screen.getByRole("textbox", { name: /type a reply to the agent/i })).toHaveValue(
+      "please continue",
+    );
+    expect(screen.getByRole("textbox", { name: /type a reply to the agent/i })).not.toBeDisabled();
+  });
+
+  it("shows a temporary failed state when an alert action send is rejected", async () => {
+    const onSend = vi.fn(() => Promise.reject(new Error("network failed")));
+    const pr = makePR({
+      state: "open",
+      ciStatus: "failing",
+      ciChecks: [{ name: "test", status: "failed" }],
+      reviewDecision: "approved",
+      mergeability: {
+        mergeable: false,
+        ciPassing: false,
+        approved: true,
+        noConflicts: true,
+        blockers: [],
+      },
+    });
+    const session = makeSession({ activity: "idle", pr });
+
+    render(<SessionCard session={session} onSend={onSend} />);
+
+    const actionButton = screen.getByRole("button", { name: "ask to fix" });
+    fireEvent.click(actionButton);
+
+    await waitFor(() => {
+      expect(onSend).toHaveBeenCalledTimes(1);
+    });
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: "failed" })).toBeInTheDocument();
+    });
+    expect(screen.queryByRole("button", { name: "sent!" })).not.toBeInTheDocument();
+  });
 });
 
 // ── AttentionZone ────────────────────────────────────────────────────

packages/web/src/__tests__/setup.ts

@@ -1 +1,19 @@
 import "@testing-library/jest-dom/vitest";
+
+// jsdom does not implement window.matchMedia. Provide a minimal stub so
+// components that call useMediaQuery (e.g. Dashboard) work in unit tests.
+// The stub always returns `false` (non-matching), which keeps tests in the
+// desktop/non-mobile rendering path and avoids spurious re-renders.
+Object.defineProperty(window, "matchMedia", {
+  writable: true,
+  value: (query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  }),
+});

packages/web/src/app/api/sessions/route.ts

@@ -38,6 +38,7 @@ export async function GET(request: Request) {
     const { searchParams } = new URL(request.url);
     const projectFilter = searchParams.get("project");
     const activeOnly = searchParams.get("active") === "true";
+    const orchestratorOnly = searchParams.get("orchestratorOnly") === "true";
 
     const { config, registry, sessionManager } = await getServices();
     const requestedProjectId =
@@ -45,11 +46,35 @@ export async function GET(request: Request) {
         ? projectFilter
         : undefined;
     const coreSessions = await sessionManager.list(requestedProjectId);
-    const allSessions = requestedProjectId ? await sessionManager.list() : coreSessions;
     const visibleSessions = filterProjectSessions(coreSessions, projectFilter, config.projects);
     const orchestrators = listDashboardOrchestrators(visibleSessions, config.projects);
     const orchestratorId = orchestrators.length === 1 ? (orchestrators[0]?.id ?? null) : null;
 
+    if (orchestratorOnly) {
+      recordApiObservation({
+        config,
+        method: "GET",
+        path: "/api/sessions",
+        correlationId,
+        startedAt,
+        outcome: "success",
+        statusCode: 200,
+        data: { orchestratorOnly: true, orchestratorCount: orchestrators.length },
+      });
+
+      return jsonWithCorrelation(
+        {
+          orchestratorId,
+          orchestrators,
+          sessions: [],
+        },
+        { status: 200 },
+        correlationId,
+      );
+    }
+
+    const allSessions = requestedProjectId ? await sessionManager.list() : coreSessions;
+
     let workerSessions = visibleSessions.filter((session) => !isOrchestratorSession(session));
 
     // Convert to dashboard format

packages/web/src/app/apple-icon.tsx

@@ -0,0 +1,11 @@
+import { ImageResponse } from "next/og";
+import { getProjectName } from "@/lib/project-name";
+import { renderIconElement, sanitizeIconName } from "@/lib/icon-renderer";
+
+export const size = { width: 180, height: 180 };
+export const contentType = "image/png";
+
+export default function AppleIcon() {
+  const name = sanitizeIconName(getProjectName());
+  return new ImageResponse(renderIconElement(180, name), { ...size });
+}

packages/web/src/app/icon-192/route.tsx

@@ -0,0 +1,15 @@
+import { ImageResponse } from "next/og";
+import { getProjectName } from "@/lib/project-name";
+import { renderIconElement, sanitizeIconName } from "@/lib/icon-renderer";
+
+export async function GET() {
+  const rawName = getProjectName();
+  const name = sanitizeIconName(rawName);
+  const response = new ImageResponse(renderIconElement(192, name), {
+    width: 192,
+    height: 192,
+  });
+  response.headers.set("Cache-Control", "public, max-age=86400, stale-while-revalidate=3600");
+  response.headers.set("Content-Security-Policy", "default-src 'none'; img-src 'self'");
+  return response;
+}

packages/web/src/app/icon-512/route.tsx

@@ -0,0 +1,15 @@
+import { ImageResponse } from "next/og";
+import { getProjectName } from "@/lib/project-name";
+import { renderIconElement, sanitizeIconName } from "@/lib/icon-renderer";
+
+export async function GET() {
+  const rawName = getProjectName();
+  const name = sanitizeIconName(rawName);
+  const response = new ImageResponse(renderIconElement(512, name), {
+    width: 512,
+    height: 512,
+  });
+  response.headers.set("Cache-Control", "public, max-age=86400, stale-while-revalidate=3600");
+  response.headers.set("Content-Security-Policy", "default-src 'none'; img-src 'self'");
+  return response;
+}

packages/web/src/app/icon.tsx

@@ -1,43 +1,11 @@
 import { ImageResponse } from "next/og";
 import { getProjectName } from "@/lib/project-name";
+import { renderIconElement, sanitizeIconName } from "@/lib/icon-renderer";
 
 export const size = { width: 32, height: 32 };
 export const contentType = "image/png";
 
-/** Derive a consistent hue from a string (0-360). */
-function stringToHue(s: string): number {
-  let hash = 0;
-  for (let i = 0; i < s.length; i++) {
-    hash = s.charCodeAt(i) + ((hash << 5) - hash);
-  }
-  return ((hash % 360) + 360) % 360;
-}
-
 export default function Icon() {
-  const name = getProjectName();
-  const initial = (name.charAt(0) || "A").toUpperCase();
-  const hue = stringToHue(name);
-
-  return new ImageResponse(
-    (
-      <div
-        style={{
-          width: "32px",
-          height: "32px",
-          borderRadius: "6px",
-          background: `hsl(${hue}, 60%, 45%)`,
-          display: "flex",
-          alignItems: "center",
-          justifyContent: "center",
-          color: "white",
-          fontSize: "20px",
-          fontWeight: 700,
-          fontFamily: "sans-serif",
-        }}
-      >
-        {initial}
-      </div>
-    ),
-    { ...size },
-  );
+  const name = sanitizeIconName(getProjectName());
+  return new ImageResponse(renderIconElement(32, name), { ...size });
 }

packages/web/src/app/layout.tsx

@@ -1,7 +1,8 @@
-import type { Metadata } from "next";
+import type { Metadata, Viewport } from "next";
 import { IBM_Plex_Sans, IBM_Plex_Mono, JetBrains_Mono } from "next/font/google";
 import { ThemeProvider } from "next-themes";
 import { getProjectName } from "@/lib/project-name";
+import { ServiceWorkerRegistrar } from "@/components/ServiceWorkerRegistrar";
 import "./globals.css";
 
 const ibmPlexSans = IBM_Plex_Sans({
@@ -25,6 +26,16 @@ const jetbrainsMono = JetBrains_Mono({
   weight: ["400", "500"],
 });
 
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+  viewportFit: "cover",
+  themeColor: [
+    { media: "(prefers-color-scheme: light)", color: "#ffffff" },
+    { media: "(prefers-color-scheme: dark)", color: "#0a0d12" },
+  ],
+};
+
 export async function generateMetadata(): Promise<Metadata> {
   const projectName = getProjectName();
   return {
@@ -33,6 +44,11 @@ export async function generateMetadata(): Promise<Metadata> {
       default: `ao | ${projectName}`,
     },
     description: "Dashboard for managing parallel AI coding agents",
+    appleWebApp: {
+      capable: true,
+      statusBarStyle: "black-translucent",
+      title: `ao | ${projectName}`,
+    },
   };
 }
 
@@ -43,6 +59,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
         <ThemeProvider attribute="class" defaultTheme="dark" enableSystem={false}>
           {children}
         </ThemeProvider>
+        <ServiceWorkerRegistrar />
       </body>
     </html>
   );

packages/web/src/app/manifest.ts

@@ -0,0 +1,20 @@
+import type { MetadataRoute } from "next";
+import { getProjectName } from "@/lib/project-name";
+
+export default function manifest(): MetadataRoute.Manifest {
+  const projectName = getProjectName();
+  return {
+    name: `ao | ${projectName}`,
+    short_name: "ao",
+    description: "Dashboard for managing parallel AI coding agents",
+    start_url: "/",
+    display: "standalone",
+    background_color: "#0a0d12",
+    theme_color: "#0a0d12",
+    icons: [
+      { src: "/apple-icon", sizes: "180x180", type: "image/png" },
+      { src: "/icon-192", sizes: "192x192", type: "image/png", purpose: "any" },
+      { src: "/icon-512", sizes: "512x512", type: "image/png", purpose: "any" },
+    ],
+  };
+}

packages/web/src/app/page.tsx

@@ -2,136 +2,32 @@ import type { Metadata } from "next";
 
 export const dynamic = "force-dynamic";
 import { Dashboard } from "@/components/Dashboard";
-import type { DashboardSession } from "@/lib/types";
-import { getServices, getSCM } from "@/lib/services";
 import {
-  sessionToDashboard,
-  resolveProject,
-  enrichSessionPR,
-  enrichSessionsMetadata,
-  listDashboardOrchestrators,
-} from "@/lib/serialize";
-import { prCache, prCacheKey } from "@/lib/cache";
-import { getPrimaryProjectId, getProjectName, getAllProjects } from "@/lib/project-name";
-import { filterProjectSessions, filterWorkerSessions } from "@/lib/project-utils";
-import { resolveGlobalPause, type GlobalPauseState } from "@/lib/global-pause";
-
-function getSelectedProjectName(projectFilter: string | undefined): string {
-  if (projectFilter === "all") return "All Projects";
-  const projects = getAllProjects();
-  if (projectFilter) {
-    const selectedProject = projects.find((project) => project.id === projectFilter);
-    if (selectedProject) return selectedProject.name;
-  }
-  return getProjectName();
-}
+  getDashboardPageData,
+  getDashboardProjectName,
+  resolveDashboardProjectFilter,
+} from "@/lib/dashboard-page-data";
 
 export async function generateMetadata(props: {
   searchParams: Promise<{ project?: string }>;
 }): Promise<Metadata> {
   const searchParams = await props.searchParams;
-  const projectFilter = searchParams.project ?? getPrimaryProjectId();
-  const projectName = getSelectedProjectName(projectFilter);
+  const projectFilter = resolveDashboardProjectFilter(searchParams.project);
+  const projectName = getDashboardProjectName(projectFilter);
   return { title: { absolute: `ao | ${projectName}` } };
 }
 
 export default async function Home(props: { searchParams: Promise<{ project?: string }> }) {
   const searchParams = await props.searchParams;
-  const projectFilter = searchParams.project ?? getPrimaryProjectId();
-  const pageData: {
-    sessions: DashboardSession[];
-    globalPause: GlobalPauseState | null;
-    orchestrators: Array<{ id: string; projectId: string; projectName: string }>;
-  } = {
-    sessions: [],
-    globalPause: null,
-    orchestrators: [],
-  };
-
-  try {
-    const { config, registry, sessionManager } = await getServices();
-    const allSessions = await sessionManager.list();
-
-    pageData.globalPause = resolveGlobalPause(allSessions);
-
-    const visibleSessions = filterProjectSessions(allSessions, projectFilter, config.projects);
-
-    pageData.orchestrators = listDashboardOrchestrators(visibleSessions, config.projects);
-
-    const coreSessions = filterWorkerSessions(allSessions, projectFilter, config.projects);
-    pageData.sessions = coreSessions.map(sessionToDashboard);
-
-    const metaTimeout = new Promise<void>((resolve) => setTimeout(resolve, 3_000));
-    await Promise.race([
-      enrichSessionsMetadata(coreSessions, pageData.sessions, config, registry),
-      metaTimeout,
-    ]);
-
-    const terminalStatuses = new Set(["merged", "killed", "cleanup", "done", "terminated"]);
-    const enrichPromises = coreSessions.map((core, i) => {
-      if (!core.pr) return Promise.resolve();
-
-      const cacheKey = prCacheKey(core.pr.owner, core.pr.repo, core.pr.number);
-      const cached = prCache.get(cacheKey);
-
-      if (cached) {
-        if (pageData.sessions[i].pr) {
-          pageData.sessions[i].pr.state = cached.state;
-          pageData.sessions[i].pr.title = cached.title;
-          pageData.sessions[i].pr.additions = cached.additions;
-          pageData.sessions[i].pr.deletions = cached.deletions;
-          pageData.sessions[i].pr.ciStatus = cached.ciStatus as
-            | "none"
-            | "pending"
-            | "passing"
-            | "failing";
-          pageData.sessions[i].pr.reviewDecision = cached.reviewDecision as
-            | "none"
-            | "pending"
-            | "approved"
-            | "changes_requested";
-          pageData.sessions[i].pr.ciChecks = cached.ciChecks.map((c) => ({
-            name: c.name,
-            status: c.status as "pending" | "running" | "passed" | "failed" | "skipped",
-            url: c.url,
-          }));
-          pageData.sessions[i].pr.mergeability = cached.mergeability;
-          pageData.sessions[i].pr.unresolvedThreads = cached.unresolvedThreads;
-          pageData.sessions[i].pr.unresolvedComments = cached.unresolvedComments;
-        }
-
-        if (
-          terminalStatuses.has(core.status) ||
-          cached.state === "merged" ||
-          cached.state === "closed"
-        ) {
-          return Promise.resolve();
-        }
-      }
-
-      const project = resolveProject(core, config.projects);
-      const scm = getSCM(registry, project);
-      if (!scm) return Promise.resolve();
-      return enrichSessionPR(pageData.sessions[i], scm, core.pr);
-    });
-    const enrichTimeout = new Promise<void>((resolve) => setTimeout(resolve, 4_000));
-    await Promise.race([Promise.allSettled(enrichPromises), enrichTimeout]);
-  } catch {
-    pageData.sessions = [];
-    pageData.globalPause = null;
-    pageData.orchestrators = [];
-  }
-
-  const projectName = getSelectedProjectName(projectFilter);
-  const projects = getAllProjects();
-  const selectedProjectId = projectFilter === "all" ? undefined : projectFilter;
+  const projectFilter = resolveDashboardProjectFilter(searchParams.project);
+  const pageData = await getDashboardPageData(projectFilter);
 
   return (
     <Dashboard
       initialSessions={pageData.sessions}
-      projectId={selectedProjectId}
-      projectName={projectName}
-      projects={projects}
+      projectId={pageData.selectedProjectId}
+      projectName={pageData.projectName}
+      projects={pageData.projects}
       initialGlobalPause={pageData.globalPause}
       orchestrators={pageData.orchestrators}
     />

packages/web/src/app/prs/page.tsx

@@ -0,0 +1,36 @@
+import type { Metadata } from "next";
+import { PullRequestsPage } from "@/components/PullRequestsPage";
+import {
+  getDashboardPageData,
+  getDashboardProjectName,
+  resolveDashboardProjectFilter,
+} from "@/lib/dashboard-page-data";
+
+export const dynamic = "force-dynamic";
+
+export async function generateMetadata(props: {
+  searchParams: Promise<{ project?: string }>;
+}): Promise<Metadata> {
+  const searchParams = await props.searchParams;
+  const projectFilter = resolveDashboardProjectFilter(searchParams.project);
+  const projectName = getDashboardProjectName(projectFilter);
+  return { title: { absolute: `ao | ${projectName} PRs` } };
+}
+
+export default async function PullRequestsRoute(props: {
+  searchParams: Promise<{ project?: string }>;
+}) {
+  const searchParams = await props.searchParams;
+  const projectFilter = resolveDashboardProjectFilter(searchParams.project);
+  const pageData = await getDashboardPageData(projectFilter);
+
+  return (
+    <PullRequestsPage
+      initialSessions={pageData.sessions}
+      projectId={pageData.selectedProjectId}
+      projectName={pageData.projectName}
+      projects={pageData.projects}
+      orchestrators={pageData.orchestrators}
+    />
+  );
+}

packages/web/src/app/sessions/[id]/page.test.tsx

@@ -0,0 +1,118 @@
+import { act, render } from "@testing-library/react";
+import { beforeEach, afterEach, describe, expect, it, vi } from "vitest";
+import type { DashboardSession } from "@/lib/types";
+
+const sessionDetailSpy = vi.fn();
+
+vi.mock("next/navigation", () => ({
+  useParams: () => ({ id: "worker-1" }),
+}));
+
+vi.mock("@/components/SessionDetail", () => ({
+  SessionDetail: (props: unknown) => {
+    sessionDetailSpy(props);
+    return <div data-testid="session-detail" />;
+  },
+}));
+
+function makeWorkerSession(): DashboardSession {
+  return {
+    id: "worker-1",
+    projectId: "my-app",
+    status: "working",
+    activity: "active",
+    branch: "feat/test",
+    issueId: "https://linear.app/test/issue/INT-100",
+    issueUrl: "https://linear.app/test/issue/INT-100",
+    issueLabel: "INT-100",
+    summary: "Test worker session",
+    summaryIsFallback: false,
+    createdAt: new Date().toISOString(),
+    lastActivityAt: new Date().toISOString(),
+    pr: null,
+    metadata: {},
+  };
+}
+
+async function flushAsyncWork(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe("SessionPage project polling", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    sessionDetailSpy.mockClear();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("resolves orchestrator nav once for non-orchestrator pages and skips repeated project polling", async () => {
+    const workerSession = makeWorkerSession();
+
+    global.fetch = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url === "/api/sessions/worker-1") {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => workerSession,
+        } as Response;
+      }
+
+      if (url === "/api/sessions?project=my-app&orchestratorOnly=true") {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            orchestratorId: "my-app-orchestrator",
+            orchestrators: [
+              {
+                id: "my-app-orchestrator",
+                projectId: "my-app",
+                projectName: "My App",
+              },
+            ],
+          }),
+        } as Response;
+      }
+
+      throw new Error(`Unexpected fetch: ${url}`);
+    }) as typeof fetch;
+
+    const { default: SessionPage } = await import("./page");
+
+    render(<SessionPage />);
+    await flushAsyncWork();
+
+    expect(fetch).toHaveBeenCalledWith("/api/sessions/worker-1");
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2_000);
+    });
+    await flushAsyncWork();
+
+    expect(fetch).toHaveBeenCalledWith("/api/sessions?project=my-app&orchestratorOnly=true");
+
+    expect(
+      vi.mocked(fetch).mock.calls.filter(
+        ([url]) => url === "/api/sessions?project=my-app&orchestratorOnly=true",
+      ),
+    ).toHaveLength(1);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5_000);
+    });
+    await flushAsyncWork();
+
+    expect(
+      vi.mocked(fetch).mock.calls.filter(
+        ([url]) => url === "/api/sessions?project=my-app&orchestratorOnly=true",
+      ),
+    ).toHaveLength(1);
+  });
+});

packages/web/src/app/sessions/[id]/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useState, useCallback } from "react";
+import { useEffect, useState, useCallback, useRef } from "react";
 import { useParams } from "next/navigation";
 import { isOrchestratorSession } from "@composio/ao-core/types";
 import { SessionDetail } from "@/components/SessionDetail";
@@ -41,16 +41,26 @@ interface ZoneCounts {
   done: number;
 }
 
+interface ProjectSessionsBody {
+  sessions?: DashboardSession[];
+  orchestratorId?: string | null;
+  orchestrators?: Array<{ id: string; projectId: string; projectName: string }>;
+}
+
 export default function SessionPage() {
   const params = useParams();
   const id = params.id as string;
 
   const [session, setSession] = useState<DashboardSession | null>(null);
   const [zoneCounts, setZoneCounts] = useState<ZoneCounts | null>(null);
+  const [projectOrchestratorId, setProjectOrchestratorId] = useState<string | null | undefined>(undefined);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const sessionProjectId = session?.projectId ?? null;
   const sessionIsOrchestrator = session ? isOrchestratorSession(session) : false;
+  const sessionProjectIdRef = useRef<string | null>(null);
+  const sessionIsOrchestratorRef = useRef(false);
+  const resolvedProjectSessionsKeyRef = useRef<string | null>(null);
 
   // Update document title based on session data
   useEffect(() => {
@@ -61,6 +71,14 @@ export default function SessionPage() {
     }
   }, [session, id]);
 
+  useEffect(() => {
+    sessionProjectIdRef.current = sessionProjectId;
+  }, [sessionProjectId]);
+
+  useEffect(() => {
+    sessionIsOrchestratorRef.current = sessionIsOrchestrator;
+  }, [sessionIsOrchestrator]);
+
   // Fetch session data (memoized to avoid recreating on every render)
   const fetchSession = useCallback(async () => {
     try {
@@ -82,13 +100,31 @@ export default function SessionPage() {
     }
   }, [id]);
 
-  const fetchZoneCounts = useCallback(async () => {
-    if (!sessionIsOrchestrator || !sessionProjectId) return;
+  const fetchProjectSessions = useCallback(async () => {
+    const projectId = sessionProjectIdRef.current;
+    if (!projectId) return;
+    const isOrchestrator = sessionIsOrchestratorRef.current;
+    const projectSessionsKey = `${projectId}:${isOrchestrator ? "orchestrator" : "worker"}`;
+    if (!isOrchestrator && resolvedProjectSessionsKeyRef.current === projectSessionsKey) return;
     try {
-      const res = await fetch(`/api/sessions?project=${encodeURIComponent(sessionProjectId)}`);
+      const query = isOrchestrator
+        ? `/api/sessions?project=${encodeURIComponent(projectId)}`
+        : `/api/sessions?project=${encodeURIComponent(projectId)}&orchestratorOnly=true`;
+      const res = await fetch(query);
       if (!res.ok) return;
-      const body = (await res.json()) as { sessions: DashboardSession[] };
+      const body = (await res.json()) as ProjectSessionsBody;
       const sessions = body.sessions ?? [];
+      const orchestratorId =
+        body.orchestratorId ??
+        body.orchestrators?.find((orchestrator) => orchestrator.projectId === projectId)?.id ??
+        null;
+      setProjectOrchestratorId((current) => (current === orchestratorId ? current : orchestratorId));
+
+      if (!isOrchestrator) {
+        resolvedProjectSessionsKeyRef.current = projectSessionsKey;
+        return;
+      }
+
       const counts: ZoneCounts = {
         merge: 0,
         respond: 0,
@@ -106,24 +142,30 @@ export default function SessionPage() {
     } catch {
       // non-critical - status strip just won't show
     }
-  }, [sessionIsOrchestrator, sessionProjectId]);
+  }, []);
+
+  useEffect(() => {
+    if (!sessionIsOrchestrator) {
+      setZoneCounts(null);
+    }
+  }, [sessionIsOrchestrator]);
 
   // Initial fetch — session first, zone counts after (avoids blocking on slow /api/sessions)
   useEffect(() => {
     fetchSession();
     // Delay zone counts so the heavy /api/sessions call doesn't contend with session load
-    const t = setTimeout(fetchZoneCounts, 2000);
+    const t = setTimeout(fetchProjectSessions, 2000);
     return () => clearTimeout(t);
-  }, [fetchSession, fetchZoneCounts]);
+  }, [fetchSession, fetchProjectSessions]);
 
   // Poll every 5s
   useEffect(() => {
     const interval = setInterval(() => {
       fetchSession();
-      fetchZoneCounts();
+      fetchProjectSessions();
     }, 5000);
     return () => clearInterval(interval);
-  }, [fetchSession, fetchZoneCounts]);
+  }, [fetchSession, fetchProjectSessions]);
 
   if (loading) {
     return (
@@ -151,6 +193,7 @@ export default function SessionPage() {
       session={session}
       isOrchestrator={sessionIsOrchestrator}
       orchestratorZones={zoneCounts ?? undefined}
+      projectOrchestratorId={projectOrchestratorId}
     />
   );
 }

packages/web/src/components/AttentionZone.tsx

@@ -1,16 +1,31 @@
 "use client";
 
-import { memo } from "react";
-import type { DashboardSession, AttentionLevel } from "@/lib/types";
+import { memo, useEffect, useState } from "react";
+import {
+  type DashboardSession,
+  type AttentionLevel,
+  isPRMergeReady,
+} from "@/lib/types";
 import { SessionCard } from "./SessionCard";
+import { getSessionTitle } from "@/lib/format";
 
 interface AttentionZoneProps {
   level: AttentionLevel;
   sessions: DashboardSession[];
-  onSend?: (sessionId: string, message: string) => void;
+  onSend?: (sessionId: string, message: string) => Promise<void> | void;
   onKill?: (sessionId: string) => void;
   onMerge?: (prNumber: number) => void;
   onRestore?: (sessionId: string) => void;
+  /** Accordion mode: whether this section is collapsed (mobile only) */
+  collapsed?: boolean;
+  /** Accordion mode: called when the header is tapped to toggle */
+  onToggle?: (level: AttentionLevel) => void;
+  /** Dense mobile rows rendered instead of full cards */
+  compactMobile?: boolean;
+  /** Open the lightweight mobile preview sheet */
+  onPreview?: (session: DashboardSession) => void;
+  /** Reset internal "show all" state when this value changes */
+  resetKey?: string | number | null;
 }
 
 const zoneConfig: Record<
@@ -56,6 +71,11 @@ const zoneConfig: Record<
 /**
  * Kanban column — always renders (even when empty) to preserve
  * the board shape. Cards scroll independently within each column.
+ *
+ * When `collapsed` and `onToggle` are provided the component renders
+ * in accordion mode (mobile): a 44 px tappable header only, with the
+ * card list hidden. Empty sections in accordion mode omit the dashed
+ * placeholder entirely — just the single-line header is shown.
  */
 function AttentionZoneView({
   level,
@@ -64,8 +84,88 @@ function AttentionZoneView({
   onKill,
   onMerge,
   onRestore,
+  collapsed,
+  onToggle,
+  compactMobile,
+  onPreview,
+  resetKey,
 }: AttentionZoneProps) {
   const config = zoneConfig[level];
+  const isAccordion = onToggle !== undefined;
+  const [showAll, setShowAll] = useState(false);
+  const visibleSessions =
+    isAccordion && compactMobile && !showAll ? sessions.slice(0, 5) : sessions;
+  const hiddenCount = sessions.length - visibleSessions.length;
+
+  useEffect(() => {
+    if (collapsed) {
+      setShowAll(false);
+    }
+  }, [collapsed]);
+
+  useEffect(() => {
+    setShowAll(false);
+  }, [resetKey]);
+
+  if (isAccordion) {
+    return (
+      <div
+        className={`accordion-section${collapsed ? " accordion-section--collapsed" : " accordion-section--expanded"}`}
+        data-level={level}
+      >
+        <button
+          type="button"
+          className="accordion-header"
+          onClick={() => onToggle(level)}
+          aria-expanded={!collapsed}
+        >
+          <span className="accordion-header__dot" style={{ background: config.color }} />
+          <span className="accordion-header__label">{config.label}</span>
+          <span className="accordion-header__count">{sessions.length}</span>
+          <span className="accordion-header__chevron" aria-hidden="true">▶</span>
+        </button>
+
+        <div className="accordion-body">
+          {sessions.length > 0 ? (
+            <div className={compactMobile ? "mobile-session-list" : "flex flex-col gap-2 p-3"}>
+              {visibleSessions.map((session) =>
+                compactMobile ? (
+                  <MobileSessionRow
+                    key={session.id}
+                    session={session}
+                    level={level}
+                    onPreview={onPreview}
+                  />
+                ) : (
+                  <SessionCard
+                    key={session.id}
+                    session={session}
+                    onSend={onSend}
+                    onKill={onKill}
+                    onMerge={onMerge}
+                    onRestore={onRestore}
+                  />
+                ),
+              )}
+              {compactMobile && hiddenCount > 0 ? (
+                <button
+                  type="button"
+                  className="mobile-session-list__view-all"
+                  onClick={() => setShowAll(true)}
+                >
+                  View all {sessions.length}
+                </button>
+              ) : null}
+            </div>
+          ) : compactMobile ? (
+            <div className="mobile-session-list">
+              <div className="mobile-session-list__empty">No sessions</div>
+            </div>
+          ) : null}
+        </div>
+      </div>
+    );
+  }
 
   return (
     <div className="kanban-column" data-level={level}>
@@ -105,13 +205,101 @@ function AttentionZoneView({
 function areAttentionZonePropsEqual(prev: AttentionZoneProps, next: AttentionZoneProps): boolean {
   return (
     prev.level === next.level &&
+    prev.collapsed === next.collapsed &&
+    prev.onToggle === next.onToggle &&
     prev.onSend === next.onSend &&
     prev.onKill === next.onKill &&
     prev.onMerge === next.onMerge &&
     prev.onRestore === next.onRestore &&
+    prev.compactMobile === next.compactMobile &&
+    prev.onPreview === next.onPreview &&
+    prev.resetKey === next.resetKey &&
     prev.sessions.length === next.sessions.length &&
     prev.sessions.every((session, index) => session === next.sessions[index])
   );
 }
 
 export const AttentionZone = memo(AttentionZoneView, areAttentionZonePropsEqual);
+
+function MobileSessionRow({
+  session,
+  level,
+  onPreview,
+}: {
+  session: DashboardSession;
+  level: AttentionLevel;
+  onPreview?: (session: DashboardSession) => void;
+}) {
+  const meta = [
+    session.branch,
+    session.pr ? `PR #${session.pr.number}` : null,
+    session.issueLabel,
+  ].filter(Boolean);
+
+  return (
+    <div className="mobile-session-row">
+      <button
+        type="button"
+        className="mobile-session-row__preview"
+        onClick={() => onPreview?.(session)}
+        aria-label={`Open ${getSessionTitle(session)}`}
+      >
+        <div className="mobile-session-row__line">
+          <span
+            className="mobile-session-row__dot"
+            style={{ background: zoneConfig[level].color }}
+            aria-hidden="true"
+          />
+          <span className="mobile-session-row__title">{getSessionTitle(session)}</span>
+        </div>
+        <div className="mobile-session-row__meta">
+          {meta.length > 0 ? meta.join(" · ") : "No branch or PR metadata"}
+        </div>
+      </button>
+      <div className="mobile-session-row__side">
+        <SessionStateChip session={session} level={level} />
+        <a
+          href={`/sessions/${encodeURIComponent(session.id)}`}
+          className="mobile-session-row__open"
+          aria-label={`Go to ${getSessionTitle(session)}`}
+        >
+          <svg
+            className="mobile-session-row__open-icon"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            viewBox="0 0 24 24"
+            aria-hidden="true"
+          >
+            <path d="M4 17V7a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2Z" />
+            <path d="m8 10 2 2-2 2M12 14h4" />
+          </svg>
+        </a>
+      </div>
+    </div>
+  );
+}
+
+function SessionStateChip({
+  session,
+  level,
+}: {
+  session: DashboardSession;
+  level: AttentionLevel;
+}) {
+  let label = zoneConfig[level].label.toLowerCase();
+
+  if (level === "merge" && session.pr && isPRMergeReady(session.pr)) {
+    label = "ready";
+  } else if (level === "respond") {
+    label = session.activity === "waiting_input" ? "waiting" : "needs input";
+  } else if (level === "review") {
+    label = session.pr?.reviewDecision === "changes_requested" ? "changes" : "review";
+  } else if (level === "pending") {
+    label = session.pr?.unresolvedThreads ? "threads" : "pending";
+  } else if (level === "working") {
+    label = session.activity === "idle" ? "idle" : "active";
+  }
+
+  return <span className="mobile-session-row__chip">{label}</span>;
+}

packages/web/src/components/BottomSheet.tsx

@@ -0,0 +1,253 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { getAttentionLevel, type DashboardSession } from "@/lib/types";
+import { getSessionTitle } from "@/lib/format";
+
+function getRelativeTime(dateStr: string): string {
+  const now = Date.now();
+  const then = new Date(dateStr).getTime();
+  const diffMs = now - then;
+  const diffSec = Math.floor(diffMs / 1000);
+  if (diffSec < 60) return `${diffSec}s ago`;
+  const diffMin = Math.floor(diffSec / 60);
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.floor(diffMin / 60);
+  if (diffHr < 24) return `${diffHr}h ago`;
+  const diffDay = Math.floor(diffHr / 24);
+  return `${diffDay}d ago`;
+}
+
+function formatTagLabel(value: string): string {
+  return value.replaceAll("_", " ");
+}
+
+function isTag(
+  value:
+    | {
+        label: string;
+        tone: "accent" | "neutral" | "mono";
+      }
+    | null,
+): value is { label: string; tone: "accent" | "neutral" | "mono" } {
+  return value !== null;
+}
+
+interface BottomSheetProps {
+  session: DashboardSession | null;
+  mode: "preview" | "confirm-kill";
+  onConfirm: () => void;
+  onCancel: () => void;
+  onRequestKill?: () => void;
+  onMerge?: (prNumber: number) => void;
+  isMergeReady?: boolean;
+}
+
+export function BottomSheet({
+  session,
+  mode,
+  onCancel,
+  onConfirm,
+  onRequestKill,
+  onMerge,
+  isMergeReady = false,
+}: BottomSheetProps) {
+  const touchStartYRef = useRef<number | null>(null);
+  const sheetRef = useRef<HTMLDivElement>(null);
+  const sessionIdRef = useRef<string | null>(null);
+  const mergePrNumber = session?.pr?.number ?? null;
+
+  useEffect(() => {
+    if (!session) {
+      sessionIdRef.current = null;
+      return;
+    }
+
+    function handleKeyDown(e: KeyboardEvent) {
+      if (e.key === "Escape") onCancel();
+    }
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [session, onCancel]);
+
+  useEffect(() => {
+    if (!session) return;
+    if (!sheetRef.current) return;
+
+    const focusable = sheetRef.current.querySelectorAll<HTMLElement>(
+      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+    );
+    if (focusable.length === 0) return;
+
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+
+    // Only steal focus when the sheet first opens (new session id), not on SSE updates.
+    const isNewSession = sessionIdRef.current !== session.id;
+    sessionIdRef.current = session.id;
+    if (isNewSession) first.focus();
+
+    function handleTabTrap(e: KeyboardEvent) {
+      if (e.key === "Tab") {
+        if (e.shiftKey && document.activeElement === first) {
+          e.preventDefault();
+          last.focus();
+        } else if (!e.shiftKey && document.activeElement === last) {
+          e.preventDefault();
+          first.focus();
+        }
+      }
+    }
+
+    const sheet = sheetRef.current;
+    sheet.addEventListener("keydown", handleTabTrap);
+    return () => sheet.removeEventListener("keydown", handleTabTrap);
+  }, [session, mode]);
+
+  function handleTouchStart(e: React.TouchEvent) {
+    touchStartYRef.current = e.touches[0]?.clientY ?? null;
+  }
+
+  function handleTouchEnd(e: React.TouchEvent) {
+    if (touchStartYRef.current === null) return;
+    const deltaY = (e.changedTouches[0]?.clientY ?? 0) - touchStartYRef.current;
+    touchStartYRef.current = null;
+    if (deltaY > 80) {
+      onCancel();
+    }
+  }
+
+  if (!session) return null;
+
+  const title = getSessionTitle(session);
+  const attention = getAttentionLevel(session);
+  const summary =
+    session.summary && !session.summaryIsFallback ? session.summary : null;
+  const hasLiveTerminateAction =
+    attention !== "done" && attention !== "merge" && session.status !== "terminated";
+  const tags = [
+    { label: formatTagLabel(attention), tone: "accent" as const },
+    { label: formatTagLabel(session.status), tone: "neutral" as const },
+    session.activity ? { label: formatTagLabel(session.activity), tone: "neutral" as const } : null,
+    session.branch ? { label: session.branch, tone: "mono" as const } : null,
+    session.pr ? { label: `PR #${session.pr.number}`, tone: "neutral" as const } : null,
+    session.issueLabel ? { label: session.issueLabel, tone: "neutral" as const } : null,
+  ].filter(isTag);
+
+  return (
+    <>
+      {/* Backdrop */}
+      <div
+        className="bottom-sheet-backdrop"
+        onClick={onCancel}
+        aria-hidden="true"
+      />
+
+      {/* Sheet */}
+      <div
+        ref={sheetRef}
+        className="bottom-sheet"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="bottom-sheet-title"
+        onTouchStart={handleTouchStart}
+        onTouchEnd={handleTouchEnd}
+      >
+        {/* Drag handle */}
+        <div className="bottom-sheet__handle" aria-hidden="true" />
+
+        <div className="bottom-sheet__header">
+          <h2 id="bottom-sheet-title" className="bottom-sheet__title">
+            {mode === "confirm-kill" ? "Terminate session?" : title}
+          </h2>
+          <p className="bottom-sheet__subtitle">
+            {mode === "confirm-kill"
+              ? "This action cannot be undone."
+              : `${attention} · started ${getRelativeTime(session.createdAt)}`}
+          </p>
+        </div>
+
+        <div className="bottom-sheet__session-info">
+          {mode === "confirm-kill" ? (
+            <div className="bottom-sheet__session-name">{title}</div>
+          ) : null}
+          <div className="bottom-sheet__session-meta">
+            {tags.map((tag) => (
+              <span
+                key={`${tag.tone}-${tag.label}`}
+                className={`bottom-sheet__tag bottom-sheet__tag--${tag.tone}`}
+              >
+                {tag.label}
+              </span>
+            ))}
+          </div>
+          {summary ? <p className="bottom-sheet__summary">{summary}</p> : null}
+        </div>
+
+        <div className="bottom-sheet__actions">
+          {mode === "confirm-kill" ? (
+            <>
+              <button
+                type="button"
+                className="bottom-sheet__btn bottom-sheet__btn--cancel"
+                onClick={onCancel}
+              >
+                Cancel
+              </button>
+              <button
+                type="button"
+                className="bottom-sheet__btn bottom-sheet__btn--danger"
+                onClick={onConfirm}
+              >
+                Terminate
+              </button>
+            </>
+          ) : (
+            <>
+              <a
+                href={`/sessions/${encodeURIComponent(session.id)}`}
+                className="bottom-sheet__btn bottom-sheet__btn--primary"
+              >
+                Open session
+              </a>
+              {isMergeReady && session.pr && onMerge ? (
+                <button
+                  type="button"
+                  className="bottom-sheet__btn bottom-sheet__btn--secondary"
+                  onClick={() => {
+                    if (mergePrNumber !== null) {
+                      onMerge(mergePrNumber);
+                    }
+                  }}
+                >
+                  Merge
+                </button>
+              ) : hasLiveTerminateAction && onRequestKill ? (
+                <button
+                  type="button"
+                  className="bottom-sheet__btn bottom-sheet__btn--danger"
+                  onClick={onRequestKill}
+                >
+                  <svg
+                    className="bottom-sheet__btn-icon"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    viewBox="0 0 24 24"
+                    aria-hidden="true"
+                  >
+                    <path d="M3 6h18" />
+                    <path d="M8 6V4h8v2" />
+                    <path d="M19 6l-1 14H6L5 6" />
+                    <path d="M10 11v6M14 11v6" />
+                  </svg>
+                  Terminate
+                </button>
+              ) : null}
+            </>
+          )}
+        </div>
+      </div>
+    </>
+  );
+}

packages/web/src/components/ConnectionBar.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+interface ConnectionBarProps {
+  status: "connected" | "reconnecting" | "disconnected";
+}
+
+export function ConnectionBar({ status }: ConnectionBarProps) {
+  if (status === "connected") return null;
+
+  if (status === "disconnected") {
+    return (
+      <button
+        type="button"
+        className="connection-bar connection-bar--disconnected"
+        aria-live="assertive"
+        aria-atomic="true"
+        onClick={() => window.location.reload()}
+      >
+        Offline · tap to retry
+      </button>
+    );
+  }
+
+  return (
+    <div
+      className="connection-bar connection-bar--reconnecting"
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      Reconnecting…
+    </div>
+  );
+}

packages/web/src/components/Dashboard.tsx

@@ -1,26 +1,30 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useSearchParams } from "next/navigation";
+import { useMediaQuery, MOBILE_BREAKPOINT } from "@/hooks/useMediaQuery";
 import {
   type DashboardSession,
   type DashboardStats,
-  type DashboardPR,
   type AttentionLevel,
   type GlobalPauseState,
   type DashboardOrchestratorLink,
   getAttentionLevel,
   isPRRateLimited,
-  CI_STATUS,
+  isPRMergeReady,
 } from "@/lib/types";
 import { AttentionZone } from "./AttentionZone";
-import { PRTableRow } from "./PRStatus";
 import { DynamicFavicon } from "./DynamicFavicon";
 import { useSessionEvents } from "@/hooks/useSessionEvents";
 import { ProjectSidebar } from "./ProjectSidebar";
 import { ThemeToggle } from "./ThemeToggle";
 import type { ProjectInfo } from "@/lib/project-name";
 import { EmptyState } from "./Skeleton";
+import { ToastProvider, useToast } from "./Toast";
+import { BottomSheet } from "./BottomSheet";
+import { ConnectionBar } from "./ConnectionBar";
+import { MobileBottomNav } from "./MobileBottomNav";
+import { getProjectScopedHref } from "@/lib/project-utils";
 
 interface DashboardProps {
   initialSessions: DashboardSession[];
@@ -32,6 +36,18 @@ interface DashboardProps {
 }
 
 const KANBAN_LEVELS = ["working", "pending", "review", "respond", "merge"] as const;
+/** Urgency-first order for the mobile accordion (reversed from desktop) */
+const MOBILE_KANBAN_ORDER = ["respond", "merge", "review", "pending", "working"] as const;
+const MOBILE_FILTERS = [
+  { value: "all", label: "All" },
+  { value: "respond", label: "Respond" },
+  { value: "merge", label: "Ready" },
+  { value: "review", label: "Review" },
+  { value: "pending", label: "Pending" },
+  { value: "working", label: "Working" },
+] as const;
+type MobileAttentionLevel = (typeof MOBILE_KANBAN_ORDER)[number];
+type MobileFilterValue = (typeof MOBILE_FILTERS)[number]["value"];
 const EMPTY_ORCHESTRATORS: DashboardOrchestratorLink[] = [];
 
 function mergeOrchestrators(
@@ -47,7 +63,7 @@ function mergeOrchestrators(
   return [...merged.values()];
 }
 
-export function Dashboard({
+function DashboardInner({
   initialSessions,
   projectId,
   projectName,
@@ -56,7 +72,7 @@ export function Dashboard({
   orchestrators,
 }: DashboardProps) {
   const orchestratorLinks = orchestrators ?? EMPTY_ORCHESTRATORS;
-  const { sessions, globalPause } = useSessionEvents(
+  const { sessions, globalPause, connectionStatus } = useSessionEvents(
     initialSessions,
     initialGlobalPause,
     projectId,
@@ -70,18 +86,103 @@ export function Dashboard({
   const [spawningProjectIds, setSpawningProjectIds] = useState<string[]>([]);
   const [spawnErrors, setSpawnErrors] = useState<Record<string, string>>({});
   const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+  const isMobile = useMediaQuery(MOBILE_BREAKPOINT);
+  const [hasMounted, setHasMounted] = useState(false);
+  const [expandedLevel, setExpandedLevel] = useState<MobileAttentionLevel | null>(null);
+  const [mobileFilter, setMobileFilter] = useState<MobileFilterValue>("all");
   const showSidebar = projects.length > 1;
+  const { showToast } = useToast();
+  const [sheetState, setSheetState] = useState<{
+    sessionId: string;
+    mode: "preview" | "confirm-kill";
+  } | null>(null);
+  const [sheetSessionOverride, setSheetSessionOverride] = useState<DashboardSession | null>(null);
+  const sessionsRef = useRef(sessions);
+  const hasSeededMobileExpansionRef = useRef(false);
+  sessionsRef.current = sessions;
   const allProjectsView = showSidebar && projectId === undefined;
+  const currentProjectOrchestrator = useMemo(
+    () =>
+      projectId
+        ? activeOrchestrators.find((orchestrator) => orchestrator.projectId === projectId) ?? null
+        : null,
+    [activeOrchestrators, projectId],
+  );
+  const dashboardHref = getProjectScopedHref("/", projectId);
+  const prsHref = getProjectScopedHref("/prs", projectId);
+  const orchestratorHref = currentProjectOrchestrator
+    ? `/sessions/${encodeURIComponent(currentProjectOrchestrator.id)}`
+    : null;
 
   const displaySessions = useMemo(() => {
     if (allProjectsView || !activeSessionId) return sessions;
     return sessions.filter((s) => s.id === activeSessionId);
   }, [sessions, allProjectsView, activeSessionId]);
+  const sheetSession = useMemo(
+    () => (sheetState ? sessions.find((session) => session.id === sheetState.sessionId) ?? null : null),
+    [sessions, sheetState],
+  );
+  const hydratedSheetSession = useMemo(() => {
+    if (!sheetSession) return null;
+    if (!sheetSessionOverride) return sheetSession;
+    return {
+      ...sheetSession,
+      ...sheetSessionOverride,
+      status: sheetSession.status,
+      activity: sheetSession.activity,
+      lastActivityAt: sheetSession.lastActivityAt,
+    };
+  }, [sheetSession, sheetSessionOverride]);
 
   useEffect(() => {
     setActiveOrchestrators((current) => mergeOrchestrators(current, orchestratorLinks));
   }, [orchestratorLinks]);
 
+  useEffect(() => {
+    setMobileMenuOpen(false);
+  }, [searchParams]);
+
+  useEffect(() => {
+    if (sheetState && sheetSession === null) {
+      setSheetState(null);
+    }
+  }, [sheetSession, sheetState]);
+
+  useEffect(() => {
+    if (!sheetState || sheetState.mode !== "confirm-kill" || !hydratedSheetSession) return;
+    if (getAttentionLevel(hydratedSheetSession) !== "done") return;
+    setSheetState(null);
+  }, [hydratedSheetSession, sheetState]);
+
+  useEffect(() => {
+    if (!sheetState) {
+      setSheetSessionOverride(null);
+      return;
+    }
+
+    let cancelled = false;
+    const sessionId = sheetState.sessionId;
+    const refreshSession = async () => {
+      try {
+        const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}`);
+        if (!res.ok) return;
+        const data = (await res.json()) as Partial<DashboardSession> | null;
+        if (!data || data.id !== sessionId) return;
+        if (!cancelled) setSheetSessionOverride(data as DashboardSession);
+      } catch {
+        // Ignore transient failures; SSE still keeps status/activity fresh.
+      }
+    };
+
+    void refreshSession();
+    const interval = setInterval(refreshSession, 15000);
+    return () => {
+      cancelled = true;
+      clearInterval(interval);
+    };
+  }, [sheetState]);
+
   const grouped = useMemo(() => {
     const zones: Record<AttentionLevel, DashboardSession[]> = {
       merge: [],
@@ -97,6 +198,40 @@ export function Dashboard({
     return zones;
   }, [displaySessions]);
 
+  // Auto-expand the most urgent non-empty section when switching to mobile.
+  // Intentionally seeded once per mobile mode change, not on every session update.
+  useEffect(() => {
+    setHasMounted(true);
+  }, []);
+
+  useEffect(() => {
+    if (!isMobile) {
+      hasSeededMobileExpansionRef.current = false;
+      return;
+    }
+    if (hasSeededMobileExpansionRef.current) return;
+
+    hasSeededMobileExpansionRef.current = true;
+    setExpandedLevel(
+      MOBILE_KANBAN_ORDER.find((level) => grouped[level].length > 0) ?? null,
+    );
+  }, [grouped, isMobile]);
+
+  useEffect(() => {
+    if (!isMobile) return;
+    if (mobileFilter !== "all") {
+      setExpandedLevel(mobileFilter);
+      return;
+    }
+    // Preserve an explicit all-collapsed state. Only auto-expand when a specific expanded
+    // section becomes empty, so SSE regrouping does not override a deliberate user collapse.
+    setExpandedLevel((current) => {
+      if (current === null) return current;
+      if (current !== null && grouped[current].length > 0) return current;
+      return MOBILE_KANBAN_ORDER.find((level) => grouped[level].length > 0) ?? null;
+    });
+  }, [grouped, isMobile, mobileFilter]);
+
   const sessionsByProject = useMemo(() => {
     const groupedSessions = new Map<string, DashboardSession[]>();
     for (const session of sessions) {
@@ -110,16 +245,6 @@ export function Dashboard({
     return groupedSessions;
   }, [sessions]);
 
-  const openPRs = useMemo(() => {
-    return displaySessions
-      .filter(
-        (session): session is DashboardSession & { pr: DashboardPR } =>
-          session.pr?.state === "open",
-      )
-      .map((session) => session.pr)
-      .sort((a, b) => mergeScore(a) - mergeScore(b));
-  }, [displaySessions]);
-
   const projectOverviews = useMemo(() => {
     if (!allProjectsView) return [];
 
@@ -149,43 +274,137 @@ export function Dashboard({
     });
   }, [activeOrchestrators, allProjectsView, projects, sessionsByProject]);
 
-  const handleSend = useCallback(async (sessionId: string, message: string) => {
-    const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/send`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ message }),
-    });
-    if (!res.ok) {
-      console.error(`Failed to send message to ${sessionId}:`, await res.text());
-    }
+  const handleAccordionToggle = useCallback((level: AttentionLevel) => {
+    if (level === "done") return;
+    setExpandedLevel((current) => (current === level ? null : level));
   }, []);
 
-  const handleKill = useCallback(async (sessionId: string) => {
-    if (!confirm(`Kill session ${sessionId}?`)) return;
-    const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/kill`, {
-      method: "POST",
-    });
-    if (!res.ok) {
-      console.error(`Failed to kill ${sessionId}:`, await res.text());
-    }
+  const handlePillTap = useCallback((level: AttentionLevel) => {
+    if (level === "done") return;
+    setMobileFilter(level);
+    setExpandedLevel(level);
+    const behavior = window.matchMedia("(prefers-reduced-motion: reduce)").matches
+      ? ("instant" as ScrollBehavior)
+      : "smooth";
+    document.getElementById("mobile-board")?.scrollIntoView({ behavior, block: "start" });
   }, []);
 
+  const visibleMobileLevels =
+    mobileFilter === "all" ? MOBILE_KANBAN_ORDER : MOBILE_KANBAN_ORDER.filter((level) => level === mobileFilter);
+  const showDesktopPrsLink = hasMounted && !isMobile;
+
+  const handleSend = useCallback(async (sessionId: string, message: string) => {
+    try {
+      const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/send`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message }),
+      });
+      if (!res.ok) {
+        const text = await res.text();
+        const messageText = text || "Unknown error";
+        console.error(`Failed to send message to ${sessionId}:`, messageText);
+        showToast(`Send failed: ${messageText}`, "error");
+        const errorWithToast = new Error(messageText);
+        (errorWithToast as Error & { toastShown?: boolean }).toastShown = true;
+        throw errorWithToast;
+      }
+    } catch (error) {
+      const toastShown =
+        error instanceof Error &&
+        "toastShown" in error &&
+        (error as Error & { toastShown?: boolean }).toastShown;
+      if (!toastShown) {
+        console.error(`Network error sending message to ${sessionId}:`, error);
+        showToast("Network error while sending message", "error");
+      }
+      throw error;
+    }
+  }, [showToast]);
+
+  const killSession = useCallback(async (sessionId: string) => {
+    try {
+      const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/kill`, {
+        method: "POST",
+      });
+      if (!res.ok) {
+        const text = await res.text();
+        console.error(`Failed to kill ${sessionId}:`, text);
+        showToast(`Terminate failed: ${text}`, "error");
+      } else {
+        showToast("Session terminated", "success");
+      }
+    } catch (error) {
+      console.error(`Network error killing ${sessionId}:`, error);
+      showToast("Network error while terminating session", "error");
+    }
+  }, [showToast]);
+
+  const handleKill = useCallback((sessionId: string) => {
+    const session = sessionsRef.current.find((s) => s.id === sessionId) ?? null;
+    if (!session) return;
+    if (!isMobile) {
+      const confirmed = window.confirm("Terminate this session?");
+      if (confirmed) {
+        void killSession(session.id);
+      }
+      return;
+    }
+    setSheetState({ sessionId: session.id, mode: "confirm-kill" });
+  }, [isMobile, killSession]);
+
+  const handlePreview = useCallback((session: DashboardSession) => {
+    setSheetState({ sessionId: session.id, mode: "preview" });
+  }, []);
+
+  const handleRequestKillFromPreview = useCallback(() => {
+    setSheetState((current) =>
+      current ? { sessionId: current.sessionId, mode: "confirm-kill" } : current,
+    );
+  }, []);
+
+  const handleKillConfirm = useCallback(async () => {
+    const session = hydratedSheetSession;
+    setSheetState(null);
+    if (!session) return;
+    await killSession(session.id);
+  }, [hydratedSheetSession, killSession]);
+
   const handleMerge = useCallback(async (prNumber: number) => {
-    const res = await fetch(`/api/prs/${prNumber}/merge`, { method: "POST" });
-    if (!res.ok) {
-      console.error(`Failed to merge PR #${prNumber}:`, await res.text());
+    try {
+      const res = await fetch(`/api/prs/${prNumber}/merge`, { method: "POST" });
+      if (!res.ok) {
+        const text = await res.text();
+        console.error(`Failed to merge PR #${prNumber}:`, text);
+        showToast(`Merge failed: ${text}`, "error");
+        return;
+      } else {
+        showToast(`PR #${prNumber} merged`, "success");
+        setSheetState(null);
+      }
+    } catch (error) {
+      console.error(`Network error merging PR #${prNumber}:`, error);
+      showToast("Network error while merging PR", "error");
     }
-  }, []);
+  }, [showToast]);
 
   const handleRestore = useCallback(async (sessionId: string) => {
-    if (!confirm(`Restore session ${sessionId}?`)) return;
-    const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/restore`, {
-      method: "POST",
-    });
-    if (!res.ok) {
-      console.error(`Failed to restore ${sessionId}:`, await res.text());
+    try {
+      const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/restore`, {
+        method: "POST",
+      });
+      if (!res.ok) {
+        const text = await res.text();
+        console.error(`Failed to restore ${sessionId}:`, text);
+        showToast(`Restore failed: ${text}`, "error");
+      } else {
+        showToast("Session restored", "success");
+      }
+    } catch (error) {
+      console.error(`Network error restoring ${sessionId}:`, error);
+      showToast("Network error while restoring session", "error");
     }
-  }, []);
+  }, [showToast]);
 
   const handleSpawnOrchestrator = async (project: ProjectInfo) => {
     setSpawningProjectIds((current) =>
@@ -258,6 +477,8 @@ export function Dashboard({
   }, [globalPause?.pausedUntil, globalPause?.reason, globalPause?.sourceSessionId]);
 
   return (
+    <>
+    <ConnectionBar status={connectionStatus} />
     <div className="dashboard-shell flex h-screen">
       {showSidebar && (
         <ProjectSidebar
@@ -267,34 +488,103 @@ export function Dashboard({
           activeSessionId={activeSessionId}
           collapsed={sidebarCollapsed}
           onToggleCollapsed={() => setSidebarCollapsed((current) => !current)}
+          mobileOpen={mobileMenuOpen}
+          onMobileClose={() => setMobileMenuOpen(false)}
         />
       )}
       <div className="dashboard-main flex-1 overflow-y-auto px-4 py-4 md:px-7 md:py-6">
+        <div id="mobile-dashboard-anchor" aria-hidden="true" />
         <DynamicFavicon sessions={sessions} projectName={projectName} />
         <section className="dashboard-hero mb-5">
           <div className="dashboard-hero__backdrop" />
           <div className="dashboard-hero__content">
+            {showSidebar && (
+              <button
+                type="button"
+                className="mobile-menu-toggle"
+                onClick={() => setMobileMenuOpen(true)}
+                aria-label="Open menu"
+              >
+                <svg
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  viewBox="0 0 24 24"
+                  className="h-5 w-5"
+                >
+                  <path d="M4 6h16M4 12h16M4 18h16" />
+                </svg>
+              </button>
+            )}
             <div className="dashboard-hero__primary">
               <div className="dashboard-hero__heading">
-                <div>
-                  <h1 className="dashboard-title">{projectName ?? "Orchestrator"}</h1>
+                <div className="dashboard-hero__copy">
+                  <h1 className="dashboard-title">
+                    {projectName ?? "Orchestrator"}
+                  </h1>
                   <p className="dashboard-subtitle">
                     Live sessions, review pressure, and merge readiness.
                   </p>
                 </div>
               </div>
-              <StatusCards stats={liveStats} />
+              {!isMobile ? <StatusCards stats={liveStats} /> : null}
             </div>
 
             <div className="dashboard-hero__meta">
               <div className="flex items-center gap-3">
-                {!allProjectsView && <OrchestratorControl orchestrators={activeOrchestrators} />}
+                {showDesktopPrsLink ? (
+                  <a
+                    href={prsHref}
+                    className="dashboard-prs-link orchestrator-btn flex items-center gap-2 px-4 py-2 text-[12px] font-semibold hover:no-underline"
+                  >
+                    <svg
+                      className="h-3.5 w-3.5 opacity-75"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      viewBox="0 0 24 24"
+                      aria-hidden="true"
+                    >
+                      <path d="M4 6h16M4 12h16M4 18h10" />
+                    </svg>
+                    PRs
+                  </a>
+                ) : null}
+                {!allProjectsView && !isMobile ? (
+                  <OrchestratorControl orchestrators={activeOrchestrators} />
+                ) : null}
                 <ThemeToggle />
               </div>
             </div>
           </div>
         </section>
 
+        {isMobile ? (
+          <section className="mobile-priority-row" aria-label="Needs attention">
+            <div className="mobile-priority-row__label">Needs attention</div>
+            <MobileActionStrip
+              grouped={grouped}
+              onPillTap={handlePillTap}
+            />
+          </section>
+        ) : null}
+
+        {isMobile ? (
+          <section className="mobile-filter-row" aria-label="Dashboard filters">
+            {MOBILE_FILTERS.map((filter) => (
+              <button
+                key={filter.value}
+                type="button"
+                className="mobile-filter-chip"
+                data-active={mobileFilter === filter.value ? "true" : "false"}
+                onClick={() => setMobileFilter(filter.value)}
+              >
+                {filter.label}
+              </button>
+            ))}
+          </section>
+        ) : null}
+
         {globalPause && !globalPauseDismissed && (
           <div className="dashboard-alert mb-6 flex items-center gap-2.5 border border-[color-mix(in_srgb,var(--color-status-error)_25%,transparent)] bg-[var(--color-tint-red)] px-3.5 py-2.5 text-[11px] text-[var(--color-status-error)]">
             <svg
@@ -392,64 +682,80 @@ export function Dashboard({
                 <BoardLegendItem label="Ready to land" tone="var(--color-status-ready)" />
               </div>
             </div>
-            <div className="kanban-board">
-              {KANBAN_LEVELS.map((level) => (
-                <AttentionZone
-                  key={level}
-                  level={level}
-                  sessions={grouped[level]}
-                  onSend={handleSend}
-                  onKill={handleKill}
-                  onMerge={handleMerge}
-                  onRestore={handleRestore}
-                />
-              ))}
-            </div>
+
+            {isMobile ? (
+              <div id="mobile-board" className="accordion-board">
+                {visibleMobileLevels.map((level) => (
+                  <AttentionZone
+                    key={level}
+                    level={level}
+                    sessions={grouped[level]}
+                    onSend={handleSend}
+                    onKill={handleKill}
+                    onMerge={handleMerge}
+                    onRestore={handleRestore}
+                    collapsed={expandedLevel !== level}
+                    onToggle={handleAccordionToggle}
+                    compactMobile
+                    onPreview={handlePreview}
+                    resetKey={mobileFilter}
+                  />
+                ))}
+              </div>
+            ) : (
+              <div className="kanban-board">
+                {KANBAN_LEVELS.map((level) => (
+                  <AttentionZone
+                    key={level}
+                    level={level}
+                    sessions={grouped[level]}
+                    onSend={handleSend}
+                    onKill={handleKill}
+                    onMerge={handleMerge}
+                    onRestore={handleRestore}
+                  />
+                ))}
+              </div>
+            )}
           </div>
         )}
 
         {!allProjectsView && !hasAnySessions && <EmptyState />}
 
-        {openPRs.length > 0 && (
-          <div className="mx-auto max-w-[900px]">
-            <h2 className="mb-3 px-1 text-[10px] font-bold uppercase tracking-[0.10em] text-[var(--color-text-tertiary)]">
-              Pull Requests
-            </h2>
-            <div className="overflow-hidden border border-[var(--color-border-default)]">
-              <table className="w-full border-collapse">
-                <thead>
-                  <tr className="border-b border-[var(--color-border-muted)]">
-                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
-                      PR
-                    </th>
-                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
-                      Title
-                    </th>
-                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
-                      Size
-                    </th>
-                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
-                      CI
-                    </th>
-                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
-                      Review
-                    </th>
-                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
-                      Unresolved
-                    </th>
-                  </tr>
-                </thead>
-                <tbody>
-                  {openPRs.map((pr) => (
-                    <PRTableRow key={pr.number} pr={pr} />
-                  ))}
-                </tbody>
-              </table>
-            </div>
-          </div>
-        )}
       </div>
     </div>
+    {isMobile ? (
+      <MobileBottomNav
+        ariaLabel="Dashboard navigation"
+        activeTab="dashboard"
+        dashboardHref={dashboardHref}
+        prsHref={prsHref}
+        showOrchestrator={!allProjectsView}
+        orchestratorHref={orchestratorHref}
+      />
+    ) : null}
+    {isMobile ? (
+    <BottomSheet
+      session={hydratedSheetSession}
+      mode={sheetState?.mode ?? "preview"}
+      onConfirm={handleKillConfirm}
+      onCancel={() => setSheetState(null)}
+      onRequestKill={handleRequestKillFromPreview}
+      onMerge={handleMerge}
+      isMergeReady={
+        hydratedSheetSession?.pr ? isPRMergeReady(hydratedSheetSession.pr) : false
+      }
+    />
+    ) : null}
+    </>
+  );
+}
+
+export function Dashboard(props: DashboardProps) {
+  return (
+    <ToastProvider>
+      <DashboardInner {...props} />
+    </ToastProvider>
   );
 }
 
@@ -633,6 +939,68 @@ function ProjectMetric({ label, value, tone }: { label: string; value: number; t
   );
 }
 
+const MOBILE_ACTION_STRIP_LEVELS = [
+  {
+    level: "respond" as const,
+    label: "respond",
+    color: "var(--color-status-error)",
+  },
+  {
+    level: "merge" as const,
+    label: "merge",
+    color: "var(--color-status-ready)",
+  },
+  {
+    level: "review" as const,
+    label: "review",
+    color: "var(--color-accent-orange)",
+  },
+] satisfies Array<{ level: AttentionLevel; label: string; color: string }>;
+
+function MobileActionStrip({
+  grouped,
+  onPillTap,
+}: {
+  grouped: Record<AttentionLevel, DashboardSession[]>;
+  onPillTap: (level: AttentionLevel) => void;
+}) {
+  const activePills = MOBILE_ACTION_STRIP_LEVELS.filter(
+    ({ level }) => grouped[level].length > 0,
+  );
+
+  if (activePills.length === 0) {
+    return (
+      <div role="status" className="mobile-action-strip mobile-action-strip--all-good">
+        <span className="mobile-action-strip__all-good">All clear — agents are working</span>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mobile-action-strip" role="group" aria-label="Session priorities">
+      {activePills.map(({ level, label, color }) => (
+        <button
+          key={level}
+          type="button"
+          className="mobile-action-pill"
+          onClick={() => onPillTap(level)}
+          aria-label={`${grouped[level].length} ${label} — scroll to section`}
+        >
+          <span
+            className="mobile-action-pill__dot"
+            style={{ background: color }}
+            aria-hidden="true"
+          />
+          <span className="mobile-action-pill__count" style={{ color }}>
+            {grouped[level].length}
+          </span>
+          <span className="mobile-action-pill__label">{label}</span>
+        </button>
+      ))}
+    </div>
+  );
+}
+
 function StatusCards({ stats }: { stats: DashboardStats }) {
   if (stats.totalSessions === 0) {
     return (
@@ -689,16 +1057,3 @@ function BoardLegendItem({ label, tone }: { label: string; tone: string }) {
     </span>
   );
 }
-
-function mergeScore(
-  pr: Pick<DashboardPR, "ciStatus" | "reviewDecision" | "mergeability" | "unresolvedThreads">,
-): number {
-  let score = 0;
-  if (!pr.mergeability.noConflicts) score += 40;
-  if (pr.ciStatus === CI_STATUS.FAILING) score += 30;
-  else if (pr.ciStatus === CI_STATUS.PENDING) score += 5;
-  if (pr.reviewDecision === "changes_requested") score += 20;
-  else if (pr.reviewDecision !== "approved") score += 10;
-  score += pr.unresolvedThreads * 5;
-  return score;
-}

packages/web/src/components/DirectTerminal.tsx

@@ -142,7 +142,7 @@ export function DirectTerminal({
   sessionId,
   startFullscreen = false,
   variant = "agent",
-  height = "max(440px, calc(100vh - 440px))",
+  height = "max(440px, calc(100dvh - 440px))",
   isOpenCodeSession = false,
   reloadCommand,
 }: DirectTerminalProps) {
@@ -748,7 +748,7 @@ export function DirectTerminal({
           overflow: "hidden",
           display: "flex",
           flexDirection: "column",
-          height: fullscreen ? "calc(100vh - 37px)" : height,
+          height: fullscreen ? "calc(100dvh - 37px)" : height,
         }}
       />
     </div>

packages/web/src/components/MobileBottomNav.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import Link from "next/link";
+
+export type MobileBottomNavTab = "dashboard" | "prs" | "orchestrator";
+
+interface MobileBottomNavProps {
+  ariaLabel: string;
+  activeTab?: MobileBottomNavTab;
+  dashboardHref: string;
+  prsHref: string;
+  showOrchestrator?: boolean;
+  orchestratorHref?: string | null;
+}
+
+export function MobileBottomNav({
+  ariaLabel,
+  activeTab,
+  dashboardHref,
+  prsHref,
+  showOrchestrator = true,
+  orchestratorHref = null,
+}: MobileBottomNavProps) {
+  return (
+    <nav className="mobile-bottom-nav" aria-label={ariaLabel}>
+      <Link
+        href={dashboardHref}
+        className="mobile-bottom-nav__item"
+        data-active={activeTab === "dashboard" ? "true" : "false"}
+        aria-current={activeTab === "dashboard" ? "page" : undefined}
+      >
+        <svg fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24" aria-hidden="true">
+          <path d="M3 13h8V3H3zm10 8h8V11h-8zM3 21h8v-6H3zm10-10h8V3h-8z" />
+        </svg>
+        <span>Dashboard</span>
+      </Link>
+      <Link
+        href={prsHref}
+        className="mobile-bottom-nav__item"
+        data-active={activeTab === "prs" ? "true" : "false"}
+        aria-current={activeTab === "prs" ? "page" : undefined}
+      >
+        <svg fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24" aria-hidden="true">
+          <path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01" />
+        </svg>
+        <span>PRs</span>
+      </Link>
+      {showOrchestrator ? (
+        orchestratorHref ? (
+          <Link
+            href={orchestratorHref}
+            className="mobile-bottom-nav__item"
+            data-active={activeTab === "orchestrator" ? "true" : "false"}
+            aria-current={activeTab === "orchestrator" ? "page" : undefined}
+          >
+            <svg fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24" aria-hidden="true">
+              <path d="M9 3H5a2 2 0 0 0-2 2v4m16 0V5a2 2 0 0 0-2-2h-4m0 18h4a2 2 0 0 0 2-2v-4M3 15v4a2 2 0 0 0 2 2h4" />
+              <path d="M9 9h6v6H9z" />
+            </svg>
+            <span>Orchestrator</span>
+          </Link>
+        ) : (
+          <button type="button" className="mobile-bottom-nav__item" disabled>
+            <svg fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24" aria-hidden="true">
+              <path d="M9 3H5a2 2 0 0 0-2 2v4m16 0V5a2 2 0 0 0-2-2h-4m0 18h4a2 2 0 0 0 2-2v-4M3 15v4a2 2 0 0 0 2 2h4" />
+              <path d="M9 9h6v6H9z" />
+            </svg>
+            <span>Orchestrator</span>
+          </button>
+        )
+      ) : null}
+    </nav>
+  );
+}

packages/web/src/components/PRStatus.tsx

@@ -128,3 +128,46 @@ export function PRTableRow({ pr }: PRTableRowProps) {
     </tr>
   );
 }
+
+export function PRCard({ pr }: PRTableRowProps) {
+  const sizeLabel = getSizeLabel(pr.additions, pr.deletions);
+  const rateLimited = isPRRateLimited(pr);
+
+  const reviewLabel = rateLimited
+    ? "stale"
+    : pr.isDraft
+      ? "draft"
+      : pr.reviewDecision === "approved"
+        ? "approved"
+        : pr.reviewDecision === "changes_requested"
+          ? "changes"
+          : "review";
+
+  const ciLabel = rateLimited
+    ? "CI stale"
+    : pr.ciStatus === "passing"
+      ? "CI passing"
+      : pr.ciStatus === "failing"
+        ? "CI failing"
+        : "CI pending";
+
+  return (
+    <a
+      href={pr.url}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="mobile-pr-card"
+    >
+      <div className="mobile-pr-card__line">
+        <span className="mobile-pr-card__number">#{pr.number}</span>
+        <span className="mobile-pr-card__title">{pr.title}</span>
+        {!rateLimited ? <span className="mobile-pr-card__size">{sizeLabel}</span> : null}
+      </div>
+      <div className="mobile-pr-card__meta">
+        <span>{ciLabel}</span>
+        <span>{reviewLabel}</span>
+        <span>{pr.unresolvedThreads} threads</span>
+      </div>
+    </a>
+  );
+}

packages/web/src/components/ProjectSidebar.tsx

@@ -15,6 +15,8 @@ interface ProjectSidebarProps {
   activeSessionId: string | undefined;
   collapsed?: boolean;
   onToggleCollapsed?: () => void;
+  mobileOpen?: boolean;
+  onMobileClose?: () => void;
 }
 
 type ProjectHealth = "red" | "yellow" | "green" | "gray";
@@ -96,6 +98,8 @@ function ProjectSidebarInner({
   activeSessionId,
   collapsed = false,
   onToggleCollapsed,
+  mobileOpen = false,
+  onMobileClose,
 }: ProjectSidebarProps) {
   const router = useRouter();
   const pathname = usePathname();
@@ -156,61 +160,70 @@ function ProjectSidebarInner({
 
   if (collapsed) {
     return (
-      <aside className="project-sidebar project-sidebar--collapsed flex h-full w-[56px] flex-col items-center py-3">
-        <div className="flex flex-1 flex-col items-center gap-2">
-          {projects.map((project) => {
-            const entry = sessionsByProject.map.get(project.id);
-            const health = entry ? computeProjectHealth(entry.all) : ("gray" as ProjectHealth);
-            const isActive = activeProjectId === project.id;
-            const initial = project.name.charAt(0).toUpperCase();
-            return (
-              <button
-                key={project.id}
-                type="button"
-                onClick={() => router.push(pathname + `?project=${encodeURIComponent(project.id)}`)}
-                className={cn(
-                  "project-sidebar__collapsed-project",
-                  isActive && "project-sidebar__collapsed-project--active",
-                )}
-                title={project.name}
-              >
-                <span className="project-sidebar__avatar">{initial}</span>
-                {health !== "gray" && (
-                  <span
-                    className={cn(
-                      "project-sidebar__health-indicator",
-                      health === "red" && "animate-[activity-pulse_2s_ease-in-out_infinite]",
-                    )}
-                    style={{ background: healthDotColor[health] }}
-                  />
-                )}
-              </button>
-            );
-          })}
-        </div>
-        <button
-          type="button"
-          onClick={onToggleCollapsed}
-          className="project-sidebar__collapsed-toggle mt-auto"
-          aria-label="Show project sidebar"
-        >
-          <svg
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="1.8"
-            viewBox="0 0 24 24"
-            className="h-4 w-4"
+      <>
+        {mobileOpen && (
+          <div className="sidebar-mobile-backdrop" onClick={onMobileClose} />
+        )}
+        <aside className={cn("project-sidebar project-sidebar--collapsed flex h-full w-[56px] flex-col items-center py-3", mobileOpen && "project-sidebar--mobile-open")}>
+          <div className="flex flex-1 flex-col items-center gap-2">
+            {projects.map((project) => {
+              const entry = sessionsByProject.map.get(project.id);
+              const health = entry ? computeProjectHealth(entry.all) : ("gray" as ProjectHealth);
+              const isActive = activeProjectId === project.id;
+              const initial = project.name.charAt(0).toUpperCase();
+              return (
+                <button
+                  key={project.id}
+                  type="button"
+                  onClick={() => router.push(pathname + `?project=${encodeURIComponent(project.id)}`)}
+                  className={cn(
+                    "project-sidebar__collapsed-project",
+                    isActive && "project-sidebar__collapsed-project--active",
+                  )}
+                  title={project.name}
+                >
+                  <span className="project-sidebar__avatar">{initial}</span>
+                  {health !== "gray" && (
+                    <span
+                      className={cn(
+                        "project-sidebar__health-indicator",
+                        health === "red" && "animate-[activity-pulse_2s_ease-in-out_infinite]",
+                      )}
+                      style={{ background: healthDotColor[health] }}
+                    />
+                  )}
+                </button>
+              );
+            })}
+          </div>
+          <button
+            type="button"
+            onClick={() => { onToggleCollapsed?.(); onMobileClose?.(); }}
+            className="project-sidebar__collapsed-toggle mt-auto"
+            aria-label="Show project sidebar"
           >
-            <rect x="3.5" y="4.5" width="17" height="15" rx="2" />
-            <path d="M9 4.5v15M12 10l3 2-3 2" />
-          </svg>
-        </button>
-      </aside>
+            <svg
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.8"
+              viewBox="0 0 24 24"
+              className="h-4 w-4"
+            >
+              <rect x="3.5" y="4.5" width="17" height="15" rx="2" />
+              <path d="M9 4.5v15M12 10l3 2-3 2" />
+            </svg>
+          </button>
+        </aside>
+      </>
     );
   }
 
   return (
-    <aside className="project-sidebar flex h-full w-[244px] flex-col">
+    <>
+      {mobileOpen && (
+        <div className="sidebar-mobile-backdrop" onClick={onMobileClose} />
+      )}
+      <aside className={cn("project-sidebar flex h-full w-[244px] flex-col", mobileOpen && "project-sidebar--mobile-open")}>
       <div className="project-sidebar__header px-4 pb-3 pt-4">
         <div className="project-sidebar__eyebrow">Portfolio</div>
         <div className="project-sidebar__title-row">
@@ -364,7 +377,7 @@ function ProjectSidebarInner({
         })}
       </nav>
       <div className="border-t border-[var(--color-border-subtle)] p-2">
-        <button type="button" onClick={onToggleCollapsed} className="project-sidebar__collapse-btn">
+        <button type="button" onClick={() => { onToggleCollapsed?.(); onMobileClose?.(); }} className="project-sidebar__collapse-btn">
           <svg
             fill="none"
             stroke="currentColor"
@@ -379,5 +392,6 @@ function ProjectSidebarInner({
         </button>
       </div>
     </aside>
+    </>
   );
 }

packages/web/src/components/PullRequestsPage.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { useMediaQuery, MOBILE_BREAKPOINT } from "@/hooks/useMediaQuery";
+import {
+  type DashboardSession,
+  type DashboardPR,
+  type DashboardOrchestratorLink,
+} from "@/lib/types";
+import { useSessionEvents } from "@/hooks/useSessionEvents";
+import { ProjectSidebar } from "./ProjectSidebar";
+import { ThemeToggle } from "./ThemeToggle";
+import { DynamicFavicon } from "./DynamicFavicon";
+import { PRCard, PRTableRow } from "./PRStatus";
+import { MobileBottomNav } from "./MobileBottomNav";
+import type { ProjectInfo } from "@/lib/project-name";
+import { getProjectScopedHref } from "@/lib/project-utils";
+
+interface PullRequestsPageProps {
+  initialSessions: DashboardSession[];
+  projectId?: string;
+  projectName?: string;
+  projects?: ProjectInfo[];
+  orchestrators?: DashboardOrchestratorLink[];
+}
+
+const EMPTY_ORCHESTRATORS: DashboardOrchestratorLink[] = [];
+
+export function PullRequestsPage({
+  initialSessions,
+  projectId,
+  projectName,
+  projects = [],
+  orchestrators,
+}: PullRequestsPageProps) {
+  const orchestratorLinks = orchestrators ?? EMPTY_ORCHESTRATORS;
+  const { sessions } = useSessionEvents(initialSessions, null, projectId);
+  const searchParams = useSearchParams();
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+  const isMobile = useMediaQuery(MOBILE_BREAKPOINT);
+  const showSidebar = projects.length > 1;
+  const allProjectsView = showSidebar && projectId === undefined;
+  const currentProjectOrchestrator = useMemo(
+    () =>
+      projectId
+        ? orchestratorLinks.find((orchestrator) => orchestrator.projectId === projectId) ?? null
+        : null,
+    [orchestratorLinks, projectId],
+  );
+  const openPRs = useMemo(() => {
+    return sessions
+      .filter(
+        (session): session is DashboardSession & { pr: DashboardPR } => session.pr?.state === "open",
+      )
+      .map((session) => session.pr)
+      .sort((a, b) => a.number - b.number);
+  }, [sessions]);
+  const dashboardHref = getProjectScopedHref("/", projectId);
+  const prsHref = getProjectScopedHref("/prs", projectId);
+  const orchestratorHref = currentProjectOrchestrator
+    ? `/sessions/${encodeURIComponent(currentProjectOrchestrator.id)}`
+    : null;
+
+  useEffect(() => {
+    setMobileMenuOpen(false);
+  }, [searchParams]);
+
+  return (
+    <div className="dashboard-shell flex h-screen">
+      {showSidebar ? (
+        <ProjectSidebar
+          projects={projects}
+          sessions={sessions}
+          activeProjectId={projectId}
+          activeSessionId={undefined}
+          collapsed={sidebarCollapsed}
+          onToggleCollapsed={() => setSidebarCollapsed((current) => !current)}
+          mobileOpen={mobileMenuOpen}
+          onMobileClose={() => setMobileMenuOpen(false)}
+        />
+      ) : null}
+      <div className="dashboard-main flex-1 overflow-y-auto px-4 py-4 md:px-7 md:py-6">
+        <DynamicFavicon sessions={sessions} projectName={projectName ? `${projectName} PRs` : "Pull Requests"} />
+        <section className="dashboard-hero mb-5">
+          <div className="dashboard-hero__backdrop" />
+          <div className="dashboard-hero__content">
+            {showSidebar ? (
+              <button
+                type="button"
+                className="mobile-menu-toggle"
+                onClick={() => setMobileMenuOpen(true)}
+                aria-label="Open menu"
+              >
+                <svg
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  viewBox="0 0 24 24"
+                  className="h-5 w-5"
+                >
+                  <path d="M4 6h16M4 12h16M4 18h16" />
+                </svg>
+              </button>
+            ) : null}
+            <div className="dashboard-hero__primary">
+              <div className="dashboard-hero__heading">
+                <div>
+                  <h1 className="dashboard-title">{projectName ? `${projectName} PRs` : "Pull Requests"}</h1>
+                  <p className="dashboard-subtitle">
+                    Review active pull requests without the dashboard board chrome.
+                  </p>
+                </div>
+              </div>
+              <div className="dashboard-stat-cards dashboard-stat-cards--persist-mobile">
+                <div className="dashboard-stat-card">
+                  <span className="dashboard-stat-card__value">{openPRs.length}</span>
+                  <span className="dashboard-stat-card__label">Open PRs</span>
+                  <span className="dashboard-stat-card__meta">
+                    {allProjectsView ? "Across all projects" : "In this project"}
+                  </span>
+                </div>
+              </div>
+            </div>
+
+            <div className="dashboard-hero__meta">
+              <div className="flex items-center gap-3">
+                <ThemeToggle />
+              </div>
+            </div>
+          </div>
+        </section>
+
+        <section className="mx-auto max-w-[900px]">
+          <h2 className="mb-3 px-1 text-[10px] font-bold uppercase tracking-[0.10em] text-[var(--color-text-tertiary)]">
+            Pull Requests
+          </h2>
+          {openPRs.length === 0 ? (
+            <div className="border border-[var(--color-border-default)] bg-[var(--color-bg-surface)] px-4 py-6 text-[12px] text-[var(--color-text-secondary)]">
+              No open pull requests right now.
+            </div>
+          ) : isMobile ? (
+            <div className="mobile-pr-list">
+              {openPRs.map((pr) => (
+                <PRCard key={`${pr.owner}/${pr.repo}-${pr.number}`} pr={pr} />
+              ))}
+            </div>
+          ) : (
+            <div className="overflow-hidden border border-[var(--color-border-default)]">
+              <table className="w-full border-collapse">
+                <thead>
+                  <tr className="border-b border-[var(--color-border-muted)]">
+                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
+                      PR
+                    </th>
+                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
+                      Title
+                    </th>
+                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
+                      Size
+                    </th>
+                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
+                      CI
+                    </th>
+                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
+                      Review
+                    </th>
+                    <th className="px-3 py-2 text-left text-[11px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
+                      Unresolved
+                    </th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {openPRs.map((pr) => (
+                    <PRTableRow key={`${pr.owner}/${pr.repo}-${pr.number}`} pr={pr} />
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </section>
+      </div>
+      {isMobile ? (
+        <MobileBottomNav
+          ariaLabel="PR navigation"
+          activeTab="prs"
+          dashboardHref={dashboardHref}
+          prsHref={prsHref}
+          showOrchestrator={!allProjectsView}
+          orchestratorHref={orchestratorHref}
+        />
+      ) : null}
+    </div>
+  );
+}

packages/web/src/components/ServiceWorkerRegistrar.tsx

@@ -0,0 +1,14 @@
+"use client";
+
+import { useEffect } from "react";
+
+export function ServiceWorkerRegistrar() {
+  useEffect(() => {
+    if ("serviceWorker" in navigator) {
+      navigator.serviceWorker.register("/sw.js").catch((err) => {
+        console.error("Service worker registration failed:", err);
+      });
+    }
+  }, []);
+  return null;
+}

packages/web/src/components/SessionCard.tsx

@@ -17,7 +17,7 @@ import { getSizeLabel } from "./PRStatus";
 
 interface SessionCardProps {
   session: DashboardSession;
-  onSend?: (sessionId: string, message: string) => void;
+  onSend?: (sessionId: string, message: string) => Promise<void> | void;
   onKill?: (sessionId: string) => void;
   onMerge?: (prNumber: number) => void;
   onRestore?: (sessionId: string) => void;
@@ -94,21 +94,65 @@ function getDoneStatusInfo(session: DashboardSession): {
 function SessionCardView({ session, onSend, onKill, onMerge, onRestore }: SessionCardProps) {
   const [expanded, setExpanded] = useState(false);
   const [sendingAction, setSendingAction] = useState<string | null>(null);
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [failedAction, setFailedAction] = useState<string | null>(null);
+  const [sendingQuickReply, setSendingQuickReply] = useState<string | null>(null);
+  const [sentQuickReply, setSentQuickReply] = useState<string | null>(null);
+  const [replyText, setReplyText] = useState("");
+  const actionTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const quickReplyTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const level = getAttentionLevel(session);
   const pr = session.pr;
 
+  const handleQuickReply = async (message: string): Promise<boolean> => {
+    const trimmedMessage = message.trim();
+    if (!trimmedMessage || sendingQuickReply !== null) return false;
+
+    setSendingQuickReply(trimmedMessage);
+    setSentQuickReply(null);
+
+    try {
+      await Promise.resolve(onSend?.(session.id, trimmedMessage));
+      setSentQuickReply(trimmedMessage);
+      if (quickReplyTimerRef.current) clearTimeout(quickReplyTimerRef.current);
+      quickReplyTimerRef.current = setTimeout(() => setSentQuickReply(null), 2000);
+      return true;
+    } catch {
+      return false;
+    } finally {
+      setSendingQuickReply(null);
+    }
+  };
+
+  const handleReplyKeyDown = async (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      const sent = await handleQuickReply(replyText);
+      if (sent) setReplyText("");
+    }
+  };
+
   useEffect(() => {
     return () => {
-      if (timerRef.current) clearTimeout(timerRef.current);
+      if (actionTimerRef.current) clearTimeout(actionTimerRef.current);
+      if (quickReplyTimerRef.current) clearTimeout(quickReplyTimerRef.current);
     };
   }, []);
 
   const handleAction = async (action: string, message: string) => {
+    if (sendingAction !== null) return;
+
     setSendingAction(action);
-    onSend?.(session.id, message);
-    if (timerRef.current) clearTimeout(timerRef.current);
-    timerRef.current = setTimeout(() => setSendingAction(null), 2000);
+    setFailedAction(null);
+    try {
+      await Promise.resolve(onSend?.(session.id, message));
+      if (actionTimerRef.current) clearTimeout(actionTimerRef.current);
+      actionTimerRef.current = setTimeout(() => setSendingAction(null), 2000);
+    } catch {
+      setSendingAction(null);
+      setFailedAction(action);
+      if (actionTimerRef.current) clearTimeout(actionTimerRef.current);
+      actionTimerRef.current = setTimeout(() => setFailedAction(null), 2000);
+    }
   };
 
   const rateLimited = pr ? isPRRateLimited(pr) : false;
@@ -498,11 +542,13 @@ function SessionCardView({ session, onSend, onKill, onMerge, onRestore }: Sessio
                     <button
                       onClick={(e) => {
                         e.stopPropagation();
-                        handleAction(alert.key, alert.actionMessage ?? "");
+                        void handleAction(alert.key, alert.actionMessage ?? "");
                       }}
                       disabled={sendingAction === alert.key}
                       className={cn(
                         "border-l px-2 py-0.5 font-[var(--font-mono)] text-[11px] font-medium transition-colors disabled:opacity-50",
+                        failedAction === alert.key &&
+                          "bg-[var(--color-tint-red)] text-[var(--color-status-error)]",
                         alert.actionClassName,
                       )}
                       style={{
@@ -510,7 +556,11 @@ function SessionCardView({ session, onSend, onKill, onMerge, onRestore }: Sessio
                           alert.borderColor ?? alert.color ?? "var(--color-border-default)",
                       }}
                     >
-                      {sendingAction === alert.key ? "sent!" : alert.actionLabel}
+                      {sendingAction === alert.key
+                        ? "sent!"
+                        : failedAction === alert.key
+                          ? "failed"
+                          : alert.actionLabel}
                     </button>
                   )}
                 </span>
@@ -583,6 +633,61 @@ function SessionCardView({ session, onSend, onKill, onMerge, onRestore }: Sessio
           )}
         </div>
       </div>
+
+      {level === "respond" && (
+        <div className="quick-reply" onClick={(e) => e.stopPropagation()}>
+          {session.summary && !session.summaryIsFallback && (
+            <p className="quick-reply__summary">{session.summary}</p>
+          )}
+          <div className="quick-reply__presets">
+            <button
+              className="quick-reply__preset-btn"
+              onClick={() => void handleQuickReply("continue")}
+              disabled={sendingQuickReply !== null}
+            >
+              {sendingQuickReply === "continue"
+                ? "Sending..."
+                : sentQuickReply === "continue"
+                  ? "Sent"
+                  : "Continue"}
+            </button>
+            <button
+              className="quick-reply__preset-btn"
+              onClick={() => void handleQuickReply("abort")}
+              disabled={sendingQuickReply !== null}
+            >
+              {sendingQuickReply === "abort"
+                ? "Sending..."
+                : sentQuickReply === "abort"
+                  ? "Sent"
+                  : "Abort"}
+            </button>
+            <button
+              className="quick-reply__preset-btn"
+              onClick={() => void handleQuickReply("skip")}
+              disabled={sendingQuickReply !== null}
+            >
+              {sendingQuickReply === "skip"
+                ? "Sending..."
+                : sentQuickReply === "skip"
+                  ? "Sent"
+                  : "Skip"}
+            </button>
+          </div>
+          <textarea
+            className="quick-reply__input"
+            placeholder={sendingQuickReply !== null ? "Sending..." : "Type a reply..."}
+            aria-label="Type a reply to the agent"
+            value={replyText}
+            onChange={(e) => setReplyText(e.target.value)}
+            onKeyDown={(e) => {
+              void handleReplyKeyDown(e);
+            }}
+            rows={1}
+            disabled={sendingQuickReply !== null}
+          />
+        </div>
+      )}
     </div>
   );
 }

packages/web/src/components/SessionDetail.tsx

@@ -1,12 +1,14 @@
 "use client";
 
-import { useState, useEffect, useRef, type ReactNode } from "react";
+import { useState, useEffect, useRef, useMemo, type ReactNode } from "react";
 import { useSearchParams } from "next/navigation";
+import { useMediaQuery, MOBILE_BREAKPOINT } from "@/hooks/useMediaQuery";
 import { type DashboardSession, type DashboardPR, isPRMergeReady } from "@/lib/types";
 import { CI_STATUS } from "@composio/ao-core/types";
 import { cn } from "@/lib/cn";
 import { CICheckList } from "./CIBadge";
 import { DirectTerminal } from "./DirectTerminal";
+import { MobileBottomNav } from "./MobileBottomNav";
 
 interface OrchestratorZones {
   merge: number;
@@ -21,6 +23,7 @@ interface SessionDetailProps {
   session: DashboardSession;
   isOrchestrator?: boolean;
   orchestratorZones?: OrchestratorZones;
+  projectOrchestratorId?: string | null;
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────
@@ -56,6 +59,18 @@ function buildGitHubBranchUrl(pr: DashboardPR): string {
   return `https://github.com/${pr.owner}/${pr.repo}/tree/${pr.branch}`;
 }
 
+function activityStateClass(activityLabel: string): string {
+  const normalized = activityLabel.toLowerCase();
+  if (normalized === "active") return "session-detail-status-pill--active";
+  if (normalized === "ready") return "session-detail-status-pill--ready";
+  if (normalized === "idle") return "session-detail-status-pill--idle";
+  if (normalized === "waiting for input") return "session-detail-status-pill--waiting";
+  if (normalized === "blocked" || normalized === "exited") {
+    return "session-detail-status-pill--error";
+  }
+  return "session-detail-status-pill--neutral";
+}
+
 function SessionTopStrip({
   headline,
   activityLabel,
@@ -63,6 +78,9 @@ function SessionTopStrip({
   branch,
   pr,
   isOrchestrator = false,
+  crumbHref,
+  crumbLabel,
+  mobileSimple = false,
   rightSlot,
 }: {
   headline: string;
@@ -71,13 +89,16 @@ function SessionTopStrip({
   branch: string | null;
   pr: DashboardPR | null;
   isOrchestrator?: boolean;
+  crumbHref: string;
+  crumbLabel: string;
+  mobileSimple?: boolean;
   rightSlot?: ReactNode;
 }) {
   return (
-    <section className="session-page-header">
+    <section className={`session-page-header${mobileSimple ? " session-page-header--mobile" : ""}`}>
       <div className="session-page-header__crumbs">
         <a
-          href="/"
+          href={crumbHref}
           className="flex items-center gap-1 text-[11px] font-medium text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-text-primary)] hover:no-underline"
         >
           <svg
@@ -89,13 +110,17 @@ function SessionTopStrip({
           >
             <path d="M15 18l-6-6 6-6" />
           </svg>
-          Orchestrator
+          {crumbLabel}
         </a>
         <span className="text-[var(--color-border-strong)]">/</span>
-        <span className="font-[var(--font-mono)] text-[11px] text-[var(--color-text-tertiary)]">
-          {headline}
-        </span>
-        {isOrchestrator ? <span className="session-page-header__mode">orchestrator</span> : null}
+        {!mobileSimple ? (
+          <span className="font-[var(--font-mono)] text-[11px] text-[var(--color-text-tertiary)]">
+            {headline}
+          </span>
+        ) : null}
+        {isOrchestrator && !mobileSimple ? (
+          <span className="session-page-header__mode">orchestrator</span>
+        ) : null}
       </div>
       <div className="session-page-header__main">
         <div className="session-page-header__identity">
@@ -104,13 +129,19 @@ function SessionTopStrip({
           </h1>
           <div className="session-page-header__meta">
             <div
-              className="flex items-center gap-1.5 border px-2.5 py-1"
+              className={cn(
+                "session-detail-status-pill flex items-center gap-1.5 border px-2.5 py-1",
+                activityStateClass(activityLabel),
+              )}
               style={{
                 background: `color-mix(in srgb, ${activityColor} 12%, transparent)`,
                 border: `1px solid color-mix(in srgb, ${activityColor} 20%, transparent)`,
               }}
             >
-              <span className="h-1.5 w-1.5 shrink-0" style={{ background: activityColor }} />
+              <span
+                className="session-detail-status-pill__dot h-1.5 w-1.5 shrink-0"
+                style={{ background: activityColor }}
+              />
               <span className="text-[11px] font-semibold" style={{ color: activityColor }}>
                 {activityLabel}
               </span>
@@ -121,7 +152,7 @@ function SessionTopStrip({
                   href={buildGitHubBranchUrl(pr)}
                   target="_blank"
                   rel="noopener noreferrer"
-                  className="session-detail-link-pill font-[var(--font-mono)] text-[10px] hover:no-underline"
+                  className="session-detail-link-pill session-detail-link-pill--link font-[var(--font-mono)] text-[10px] hover:no-underline"
                 >
                   {branch}
                 </a>
@@ -136,7 +167,7 @@ function SessionTopStrip({
                 href={pr.url}
                 target="_blank"
                 rel="noopener noreferrer"
-                className="session-detail-link-pill session-detail-link-pill--accent hover:no-underline"
+                className="session-detail-link-pill session-detail-link-pill--link session-detail-link-pill--accent hover:no-underline"
               >
                 PR #{pr.number}
               </a>
@@ -181,6 +212,8 @@ function OrchestratorStatusStrip({
   activityColor,
   branch,
   pr,
+  crumbHref,
+  crumbLabel,
 }: {
   zones: OrchestratorZones;
   createdAt: string;
@@ -189,6 +222,8 @@ function OrchestratorStatusStrip({
   activityColor: string;
   branch: string | null;
   pr: DashboardPR | null;
+  crumbHref: string;
+  crumbLabel: string;
 }) {
   const [uptime, setUptime] = useState<string>("");
 
@@ -225,6 +260,8 @@ function OrchestratorStatusStrip({
         branch={branch}
         pr={pr}
         isOrchestrator
+        crumbHref={crumbHref}
+        crumbLabel={crumbLabel}
         rightSlot={
           <div className="flex flex-wrap items-center gap-3 lg:justify-end">
             <div className="flex items-baseline gap-1.5 mr-2">
@@ -282,8 +319,10 @@ export function SessionDetail({
   session,
   isOrchestrator = false,
   orchestratorZones,
+  projectOrchestratorId = null,
 }: SessionDetailProps) {
   const searchParams = useSearchParams();
+  const isMobile = useMediaQuery(MOBILE_BREAKPOINT);
   const startFullscreen = searchParams.get("fullscreen") === "true";
   const pr = session.pr;
   const activity = (session.activity && activityMeta[session.activity]) ?? {
@@ -305,10 +344,19 @@ export function SessionDetail({
   const reloadCommand = opencodeSessionId
     ? `/exit\nopencode --session ${opencodeSessionId}\n`
     : undefined;
+  const dashboardHref = session.projectId ? `/?project=${encodeURIComponent(session.projectId)}` : "/";
+  const prsHref = session.projectId ? `/prs?project=${encodeURIComponent(session.projectId)}` : "/prs";
+  const crumbHref = dashboardHref;
+  const crumbLabel = isOrchestrator ? "Orchestrator" : "Dashboard";
+  const orchestratorHref = useMemo(() => {
+    if (isOrchestrator) return `/sessions/${encodeURIComponent(session.id)}`;
+    if (!projectOrchestratorId) return null;
+    return `/sessions/${encodeURIComponent(projectOrchestratorId)}`;
+  }, [isOrchestrator, projectOrchestratorId, session.id]);
 
   return (
     <div className="session-detail-page min-h-screen bg-[var(--color-bg-base)]">
-      {isOrchestrator && orchestratorZones && (
+      {isOrchestrator && orchestratorZones && !isMobile && (
         <OrchestratorStatusStrip
           zones={orchestratorZones}
           createdAt={session.createdAt}
@@ -317,22 +365,29 @@ export function SessionDetail({
           activityColor={activity.color}
           branch={session.branch}
           pr={pr}
+          crumbHref={crumbHref}
+          crumbLabel={crumbLabel}
         />
       )}
 
-      <div className="mx-auto max-w-[1180px] px-5 py-5 lg:px-8">
+      <div className="dashboard-main mx-auto max-w-[1180px] px-5 py-5 lg:px-8">
         <main className="min-w-0">
-          {!isOrchestrator && (
+          {(!isOrchestrator || isMobile) && (
             <SessionTopStrip
               headline={headline}
               activityLabel={activity.label}
               activityColor={activity.color}
               branch={session.branch}
               pr={pr}
+              isOrchestrator={isOrchestrator}
+              crumbHref={crumbHref}
+              crumbLabel={crumbLabel}
+              mobileSimple={isMobile}
             />
           )}
 
           <section className="mt-5">
+            <div id="session-terminal-section" aria-hidden="true" />
             <div className="mb-3 flex items-center gap-2">
               <div
                 className="h-3 w-0.5"
@@ -353,19 +408,29 @@ export function SessionDetail({
           </section>
 
           {pr ? (
-            <section className="mt-6">
-              <PRCard pr={pr} sessionId={session.id} />
+            <section id="session-pr-section" className="mt-6">
+              <SessionDetailPRCard pr={pr} sessionId={session.id} />
             </section>
           ) : null}
         </main>
       </div>
+      {isMobile ? (
+        <MobileBottomNav
+          ariaLabel="Session navigation"
+          activeTab={isOrchestrator ? "orchestrator" : undefined}
+          dashboardHref={dashboardHref}
+          prsHref={prsHref}
+          showOrchestrator={orchestratorHref !== null}
+          orchestratorHref={orchestratorHref}
+        />
+      ) : null}
     </div>
   );
 }
 
-// ── PR Card ───────────────────────────────────────────────────────────
+// ── Session detail PR card ────────────────────────────────────────────
 
-function PRCard({ pr, sessionId }: { pr: DashboardPR; sessionId: string }) {
+function SessionDetailPRCard({ pr, sessionId }: { pr: DashboardPR; sessionId: string }) {
   const [sendingComments, setSendingComments] = useState<Set<string>>(new Set());
   const [sentComments, setSentComments] = useState<Set<string>>(new Set());
   const [errorComments, setErrorComments] = useState<Set<string>>(new Set());

packages/web/src/components/Terminal.tsx

@@ -73,7 +73,7 @@ export function Terminal({ sessionId }: TerminalProps) {
           {fullscreen ? "exit fullscreen" : "fullscreen"}
         </button>
       </div>
-      <div className="w-full" style={{ height: fullscreen ? "calc(100vh - 40px)" : "max(440px, calc(100vh - 440px))" }}>
+      <div className="w-full" style={{ height: fullscreen ? "calc(100dvh - 40px)" : "max(440px, calc(100dvh - 440px))" }}>
         {terminalUrl ? (
           <iframe
             src={terminalUrl}

packages/web/src/components/ThemeToggle.tsx

@@ -16,7 +16,7 @@ export function ThemeToggle() {
   return (
     <button
       onClick={() => setTheme(isDark ? "light" : "dark")}
-      className="flex h-9 w-9 items-center justify-center rounded-[8px] border border-[var(--color-border-strong)] bg-[var(--color-bg-elevated)] text-[var(--color-text-primary)] transition-colors hover:bg-[var(--color-bg-elevated-hover)]"
+      className="flex h-9 w-9 items-center justify-center border border-[var(--color-border-strong)] bg-[var(--color-bg-elevated)] text-[var(--color-text-primary)] transition-colors hover:bg-[var(--color-bg-elevated-hover)]"
       aria-label={`Switch to ${isDark ? "light" : "dark"} mode`}
       title={`Switch to ${isDark ? "light" : "dark"} mode`}
     >

packages/web/src/components/Toast.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useReducer,
+  useRef,
+} from "react";
+import { cn } from "@/lib/cn";
+
+type ToastVariant = "success" | "error" | "info";
+
+interface ToastState {
+  message: string;
+  variant: ToastVariant;
+  key: number;
+}
+
+type ToastAction =
+  | { type: "SHOW"; message: string; variant: ToastVariant; key: number }
+  | { type: "HIDE" };
+
+function toastReducer(
+  _state: ToastState | null,
+  action: ToastAction,
+): ToastState | null {
+  if (action.type === "SHOW") {
+    return { message: action.message, variant: action.variant, key: action.key };
+  }
+  return null;
+}
+
+interface ToastContextValue {
+  showToast: (message: string, variant?: ToastVariant) => void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+export function ToastProvider({ children }: { children: React.ReactNode }) {
+  const [toast, dispatch] = useReducer(toastReducer, null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const keyRef = useRef(0);
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, []);
+
+  const showToast = useCallback((message: string, variant: ToastVariant = "info") => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+    }
+    keyRef.current += 1;
+    dispatch({ type: "SHOW", message, variant, key: keyRef.current });
+    timerRef.current = setTimeout(() => {
+      dispatch({ type: "HIDE" });
+      timerRef.current = null;
+    }, 3000);
+  }, []);
+
+  return (
+    <ToastContext.Provider value={{ showToast }}>
+      {children}
+      <div
+        className="toast-container"
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+      >
+        {toast && (
+          <div
+            key={toast.key}
+            className={cn(
+              "toast",
+              toast.variant === "success" && "toast--success",
+              toast.variant === "error" && "toast--error",
+              toast.variant === "info" && "toast--info",
+            )}
+          >
+            <span className="toast__icon" aria-hidden="true" />
+            <span className="toast__message">{toast.message}</span>
+          </div>
+        )}
+      </div>
+    </ToastContext.Provider>
+  );
+}
+
+export function useToast(): ToastContextValue {
+  const ctx = useContext(ToastContext);
+  if (!ctx) {
+    throw new Error("useToast must be used within a ToastProvider");
+  }
+  return ctx;
+}

packages/web/src/components/__tests__/Dashboard.mobile.test.tsx

@@ -0,0 +1,314 @@
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Dashboard } from "../Dashboard";
+import { makePR, makeSession } from "../../__tests__/helpers";
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn(), refresh: vi.fn() }),
+  usePathname: () => "/",
+  useSearchParams: () => new URLSearchParams(),
+}));
+
+function mockMobileViewport() {
+  Object.defineProperty(window, "matchMedia", {
+    writable: true,
+    value: (query: string) => ({
+      matches: query.includes("max-width: 767px"),
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    }),
+  });
+}
+
+describe("Dashboard mobile layout", () => {
+  beforeEach(() => {
+    mockMobileViewport();
+    Element.prototype.scrollIntoView = vi.fn();
+    const eventSourceMock = {
+      onmessage: null,
+      onerror: null,
+      onopen: null,
+      close: vi.fn(),
+    };
+    const eventSourceConstructor = vi.fn(() => eventSourceMock as unknown as EventSource);
+    global.EventSource = Object.assign(eventSourceConstructor, {
+      CONNECTING: 0,
+      OPEN: 1,
+      CLOSED: 2,
+    }) as unknown as typeof EventSource;
+    global.fetch = vi.fn(() =>
+      Promise.resolve({
+        ok: true,
+        json: () => Promise.resolve({}),
+        text: () => Promise.resolve(""),
+      } as Response),
+    );
+  });
+
+  it("caps mobile sections to five rows until view-all is tapped", () => {
+    const sessions = Array.from({ length: 6 }, (_, index) =>
+      makeSession({
+        id: `needs-input-${index + 1}`,
+        summary: `Need approval ${index + 1}`,
+        status: "needs_input",
+        activity: "waiting_input",
+      }),
+    );
+
+    render(<Dashboard initialSessions={sessions} />);
+
+    expect(screen.getByText("Need approval 1")).toBeInTheDocument();
+    expect(screen.getByText("Need approval 5")).toBeInTheDocument();
+    expect(screen.queryByText("Need approval 6")).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: /view all 6/i }));
+
+    expect(screen.getByText("Need approval 6")).toBeInTheDocument();
+  });
+
+  it("opens a preview sheet from a mobile row and keeps prompting out of the dashboard", async () => {
+    const session = makeSession({
+      id: "respond-1",
+      status: "needs_input",
+      activity: "waiting_input",
+      summary: "Need approval to proceed",
+      branch: "feat/mobile-density",
+      issueLabel: "#557",
+    });
+
+    render(<Dashboard initialSessions={[session]} />);
+
+    expect(screen.getByRole("link", { name: /go to need approval to proceed/i })).toHaveAttribute(
+      "href",
+      "/sessions/respond-1",
+    );
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: /open need approval to proceed/i }));
+    });
+
+    expect(screen.getByRole("link", { name: "Open session" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Terminate" })).toBeInTheDocument();
+    expect(screen.getAllByText("Need approval to proceed").length).toBeGreaterThan(1);
+    expect(screen.getAllByText("respond").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("needs input").length).toBeGreaterThan(0);
+    expect(screen.getByText("waiting input")).toBeInTheDocument();
+    expect(screen.getByText("feat/mobile-density")).toBeInTheDocument();
+    expect(screen.getByText("#557")).toBeInTheDocument();
+    expect(screen.queryByPlaceholderText("Type a reply...")).not.toBeInTheDocument();
+  });
+
+  it("keeps the mobile preview sheet in sync with live session updates", async () => {
+    const session = makeSession({
+      id: "respond-1",
+      status: "needs_input",
+      activity: "waiting_input",
+      summary: "Need approval to proceed",
+      branch: "feat/mobile-density",
+      issueLabel: "#557",
+    });
+
+    const { rerender } = render(<Dashboard initialSessions={[session]} />);
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: /open need approval to proceed/i }));
+    });
+
+    expect(screen.getByRole("button", { name: "Terminate" })).toBeInTheDocument();
+    expect(screen.getAllByText("needs input").length).toBeGreaterThan(0);
+
+    rerender(
+      <Dashboard
+        initialSessions={[
+          {
+            ...session,
+            status: "terminated",
+            activity: "exited",
+            pr: makePR({ number: 87, state: "merged", reviewDecision: "approved" }),
+          },
+        ]}
+      />,
+    );
+
+    expect(screen.queryByRole("button", { name: "Terminate" })).not.toBeInTheDocument();
+    expect(screen.getAllByText("terminated").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("exited").length).toBeGreaterThan(0);
+    expect(screen.queryByRole("button", { name: "Merge" })).not.toBeInTheDocument();
+  });
+
+  it("does not render embedded PR cards on the dashboard anymore", () => {
+    const sessions = [
+      makeSession({
+        id: "merge-1",
+        status: "approved",
+        pr: makePR({ number: 87, title: "Add login flow" }),
+      }),
+    ];
+
+    render(<Dashboard initialSessions={sessions} />);
+
+    expect(screen.queryByRole("link", { name: /#87 add login flow/i })).not.toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute("href", "/prs?project=all");
+  });
+
+  it("renders the mobile bottom nav with dashboard, PRs, and orchestrator", () => {
+    render(
+      <Dashboard
+        initialSessions={[makeSession()]}
+        projectId="my-app"
+        orchestrators={[
+          { id: "my-app-orchestrator", projectId: "my-app", projectName: "My App" },
+        ]}
+      />,
+    );
+
+    expect(screen.getByRole("navigation", { name: /dashboard navigation/i })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Dashboard" })).toHaveAttribute("aria-current", "page");
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute("href", "/prs?project=my-app");
+    expect(screen.getByRole("link", { name: "Orchestrator" })).toHaveAttribute(
+      "href",
+      "/sessions/my-app-orchestrator",
+    );
+  });
+
+  it("hides orchestrator nav item in all-projects view", () => {
+    render(
+      <Dashboard
+        initialSessions={[makeSession()]}
+        projects={[{ id: "my-app", name: "My App" }, { id: "docs", name: "Docs" }]}
+      />,
+    );
+
+    expect(screen.getByRole("link", { name: "Dashboard" })).toHaveAttribute("href", "/?project=all");
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute("href", "/prs?project=all");
+    expect(screen.queryByRole("link", { name: "Orchestrator" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Orchestrator" })).not.toBeInTheDocument();
+  });
+
+  it("routes the PR nav item to the dedicated PR page", () => {
+    render(
+      <Dashboard
+        initialSessions={[
+          makeSession({
+            id: "merge-2",
+            status: "approved",
+            pr: makePR({ number: 91, title: "Polish mobile nav" }),
+          }),
+        ]}
+        projectId="my-app"
+      />,
+    );
+
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute(
+      "href",
+      "/prs?project=my-app",
+    );
+  });
+
+  it("filters the mobile board by selected attention bucket", () => {
+    render(
+      <Dashboard
+        initialSessions={[
+          makeSession({
+            id: "respond-1",
+            status: "needs_input",
+            activity: "waiting_input",
+            summary: "Need approval to proceed",
+          }),
+          makeSession({
+            id: "working-1",
+            status: "running",
+            activity: "active",
+            summary: "Implement dashboard filters",
+          }),
+        ]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Working" }));
+
+    expect(screen.getByText("Implement dashboard filters")).toBeInTheDocument();
+    expect(screen.queryByText("Need approval to proceed")).not.toBeInTheDocument();
+  });
+
+  it("shows a stable empty state when an expanded mobile section has no sessions", () => {
+    render(
+      <Dashboard
+        initialSessions={[
+          makeSession({
+            id: "respond-1",
+            status: "needs_input",
+            activity: "waiting_input",
+            summary: "Need approval to proceed",
+          }),
+        ]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Ready" }));
+
+    expect(screen.getByText("No sessions")).toBeInTheDocument();
+  });
+
+  it("preserves a deliberate all-collapsed state across session updates", () => {
+    const { rerender } = render(
+      <Dashboard
+        initialSessions={[
+          makeSession({
+            id: "respond-1",
+            status: "needs_input",
+            activity: "waiting_input",
+            summary: "Need approval to proceed",
+          }),
+          makeSession({
+            id: "working-1",
+            status: "running",
+            activity: "active",
+            summary: "Implement dashboard filters",
+          }),
+        ]}
+      />,
+    );
+
+    const respondAccordion = screen.getByRole("button", { name: /respond 1/i });
+    expect(respondAccordion).toHaveAttribute("aria-expanded", "true");
+
+    fireEvent.click(respondAccordion);
+    expect(respondAccordion).toHaveAttribute("aria-expanded", "false");
+
+    rerender(
+      <Dashboard
+        initialSessions={[
+          makeSession({
+            id: "respond-1",
+            status: "needs_input",
+            activity: "waiting_input",
+            summary: "Need approval to proceed",
+            lastActivityAt: new Date(Date.now() + 1_000).toISOString(),
+          }),
+          makeSession({
+            id: "working-1",
+            status: "running",
+            activity: "active",
+            summary: "Implement dashboard filters",
+            lastActivityAt: new Date(Date.now() + 2_000).toISOString(),
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.getByRole("button", { name: /respond 1/i })).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+    expect(screen.getByRole("button", { name: /working 1/i })).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+  });
+});

packages/web/src/components/__tests__/Dashboard.projectOverview.test.tsx

@@ -58,6 +58,35 @@ describe("Dashboard project overview cards", () => {
     expect(screen.getAllByRole("button", { name: "Spawn Orchestrator" })).toHaveLength(2);
   });
 
+  it("shows a desktop PRs link for project-scoped dashboards", () => {
+    render(
+      <Dashboard
+        initialSessions={[makeSession({ projectId: "my-app" })]}
+        projectId="my-app"
+        projectName="My App"
+      />,
+    );
+
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute(
+      "href",
+      "/prs?project=my-app",
+    );
+  });
+
+  it("shows a desktop PRs link for all-projects dashboards", () => {
+    render(
+      <Dashboard
+        initialSessions={[makeSession({ projectId: "my-app" })]}
+        projects={[
+          { id: "my-app", name: "My App" },
+          { id: "docs-app", name: "Docs App" },
+        ]}
+      />,
+    );
+
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute("href", "/prs?project=all");
+  });
+
   it("updates the card after spawning an orchestrator", async () => {
     let resolveSpawn: ((value: Response) => void) | null = null;
     vi.mocked(fetch).mockImplementationOnce(

packages/web/src/components/__tests__/PullRequestsPage.test.tsx

@@ -0,0 +1,95 @@
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { PullRequestsPage } from "../PullRequestsPage";
+import { makePR, makeSession } from "../../__tests__/helpers";
+
+const mockedUseSearchParams = vi.fn(() => new URLSearchParams());
+
+vi.mock("next/navigation", () => ({
+  useSearchParams: () => mockedUseSearchParams(),
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn(), refresh: vi.fn() }),
+  usePathname: () => "/prs",
+}));
+
+function mockMobileViewport() {
+  Object.defineProperty(window, "matchMedia", {
+    writable: true,
+    value: (query: string) => ({
+      matches: query.includes("max-width: 767px"),
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    }),
+  });
+}
+
+describe("PullRequestsPage", () => {
+  beforeEach(() => {
+    mockMobileViewport();
+    const eventSourceMock = {
+      onmessage: null,
+      onerror: null,
+      onopen: null,
+      close: vi.fn(),
+    };
+    const eventSourceConstructor = vi.fn(() => eventSourceMock as unknown as EventSource);
+    global.EventSource = Object.assign(eventSourceConstructor, {
+      CONNECTING: 0,
+      OPEN: 1,
+      CLOSED: 2,
+    }) as unknown as typeof EventSource;
+  });
+
+  it("renders PR cards and keeps the PR tab active on mobile", () => {
+    render(
+      <PullRequestsPage
+        initialSessions={[
+          makeSession({
+            id: "merge-1",
+            projectId: "my-app",
+            status: "approved",
+            pr: makePR({ number: 634, title: "Mobile dashboard density pass" }),
+          }),
+        ]}
+        projectId="my-app"
+        projectName="My App"
+        orchestrators={[{ id: "my-app-orchestrator", projectId: "my-app", projectName: "My App" }]}
+      />,
+    );
+
+    expect(screen.getByRole("link", { name: /#634 mobile dashboard density pass/i })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute("aria-current", "page");
+    expect(screen.getByRole("link", { name: "Dashboard" })).toHaveAttribute("href", "/?project=my-app");
+    expect(screen.getByRole("link", { name: "Orchestrator" })).toHaveAttribute(
+      "href",
+      "/sessions/my-app-orchestrator",
+    );
+  });
+
+  it("preserves the all-projects scope in mobile bottom nav links", () => {
+    render(
+      <PullRequestsPage
+        initialSessions={[
+          makeSession({
+            id: "merge-1",
+            projectId: "my-app",
+            status: "approved",
+            pr: makePR({ number: 634, title: "Mobile dashboard density pass" }),
+          }),
+        ]}
+        projectName="All Projects"
+        projects={[
+          { id: "my-app", name: "My App", path: "/tmp/my-app" },
+          { id: "docs", name: "Docs", path: "/tmp/docs" },
+        ]}
+      />,
+    );
+
+    expect(screen.getByRole("link", { name: "Dashboard" })).toHaveAttribute("href", "/?project=all");
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute("href", "/prs?project=all");
+  });
+});

packages/web/src/components/__tests__/SessionDetail.mobile.test.tsx

@@ -0,0 +1,183 @@
+import { render, screen, within } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { SessionDetail } from "../SessionDetail";
+import { makePR, makeSession } from "../../__tests__/helpers";
+
+vi.mock("next/navigation", () => ({
+  useSearchParams: () => new URLSearchParams(),
+}));
+
+vi.mock("../DirectTerminal", () => ({
+  DirectTerminal: ({ sessionId }: { sessionId: string }) => (
+    <div data-testid="direct-terminal">{sessionId}</div>
+  ),
+}));
+
+function mockMobileViewport() {
+  Object.defineProperty(window, "matchMedia", {
+    writable: true,
+    value: (query: string) => ({
+      matches: query.includes("max-width: 767px"),
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    }),
+  });
+}
+
+describe("SessionDetail mobile navbar", () => {
+  beforeEach(() => {
+    mockMobileViewport();
+  });
+
+  it("shows dashboard, PRs, and orchestrator nav on orchestrator pages", () => {
+    const session = makeSession({
+      id: "my-app-orchestrator",
+      projectId: "my-app",
+      metadata: { role: "orchestrator" },
+      summary: "Orchestrator session title",
+    });
+
+    render(
+      <SessionDetail
+        session={session}
+        isOrchestrator
+        orchestratorZones={{ merge: 1, respond: 0, review: 0, pending: 0, working: 2, done: 0 }}
+        projectOrchestratorId="my-app-orchestrator"
+      />,
+    );
+
+    const nav = screen.getByRole("navigation", { name: /session navigation/i });
+    expect(nav).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Dashboard" })).toHaveAttribute("href", "/?project=my-app");
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute("href", "/prs?project=my-app");
+    expect(screen.getAllByRole("link", { name: "Orchestrator" }).at(-1)).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    expect(screen.getAllByText("Orchestrator session title")).toHaveLength(1);
+    expect(screen.queryByText("agents")).not.toBeInTheDocument();
+    expect(screen.queryByText("responding")).not.toBeInTheDocument();
+  });
+
+  it("routes PRs to the dedicated page from worker session pages", () => {
+    render(
+      <SessionDetail
+        session={makeSession({
+          id: "worker-1",
+          projectId: "my-app",
+          pr: makePR({ number: 55, title: "Fix mobile navbar" }),
+        })}
+        projectOrchestratorId="my-app-orchestrator"
+      />,
+    );
+
+    expect(screen.getByRole("link", { name: "PRs" })).toHaveAttribute("href", "/prs?project=my-app");
+    expect(screen.getAllByRole("link", { name: "Orchestrator" }).at(-1)).toHaveAttribute(
+      "href",
+      "/sessions/my-app-orchestrator",
+    );
+  });
+
+  it("hides the orchestrator nav item when no orchestrator destination exists", () => {
+    render(
+      <SessionDetail
+        session={makeSession({
+          id: "worker-4",
+          projectId: "my-app",
+          pr: makePR({ number: 56, title: "No orchestrator yet" }),
+        })}
+        projectOrchestratorId={null}
+      />,
+    );
+
+    const nav = screen.getByRole("navigation", { name: /session navigation/i });
+
+    expect(within(nav).getByRole("link", { name: "Dashboard" })).toHaveAttribute(
+      "href",
+      "/?project=my-app",
+    );
+    expect(within(nav).getByRole("link", { name: "PRs" })).toHaveAttribute(
+      "href",
+      "/prs?project=my-app",
+    );
+    expect(within(nav).queryByRole("link", { name: "Orchestrator" })).not.toBeInTheDocument();
+    expect(within(nav).queryByRole("button", { name: "Orchestrator" })).not.toBeInTheDocument();
+  });
+
+  it("keeps branch and PR chips in the compact mobile header", () => {
+    render(
+      <SessionDetail
+        session={makeSession({
+          id: "worker-2",
+          projectId: "my-app",
+          summary: "Compact mobile header",
+          branch: "feat/compact-header",
+          pr: makePR({ number: 77, title: "Compact header polish" }),
+        })}
+        projectOrchestratorId="my-app-orchestrator"
+      />,
+    );
+
+    expect(screen.getByText("Compact mobile header")).toBeInTheDocument();
+    expect(screen.getByText("feat/compact-header")).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "PR #77" })).toHaveClass(
+      "session-detail-link-pill--link",
+    );
+    expect(screen.getByRole("link", { name: "feat/compact-header" })).toHaveClass(
+      "session-detail-link-pill--link",
+    );
+  });
+
+  it("preserves CI and unresolved review comment detail on mobile session pages", () => {
+    render(
+      <SessionDetail
+        session={makeSession({
+          id: "worker-3",
+          projectId: "my-app",
+          summary: "Review heavy session",
+          pr: makePR({
+            number: 88,
+            title: "Keep PR detail intact",
+            ciStatus: "failing",
+            ciChecks: [
+              { name: "build", status: "failed", url: "https://ci.example/build" },
+              { name: "lint", status: "passed", url: "https://ci.example/lint" },
+            ],
+            reviewDecision: "changes_requested",
+            mergeability: {
+              mergeable: false,
+              ciPassing: false,
+              approved: false,
+              noConflicts: true,
+              blockers: ["CI failing", "Changes requested"],
+            },
+            unresolvedThreads: 2,
+            unresolvedComments: [
+              {
+                url: "https://github.com/acme/app/pull/88#discussion_r1",
+                path: "src/app.ts",
+                author: "bugbot",
+                body: "### Fix null handling\n<!-- DESCRIPTION START -->Handle missing data safely<!-- DESCRIPTION END -->",
+              },
+            ],
+          }),
+        })}
+        projectOrchestratorId="my-app-orchestrator"
+      />,
+    );
+
+    expect(screen.getByText(/CI failing/i)).toBeInTheDocument();
+    expect(screen.getByText(/Changes requested/i)).toBeInTheDocument();
+    expect(screen.getByText(/2 unresolved comments/i)).toBeInTheDocument();
+    expect(screen.getByText("Unresolved Comments")).toBeInTheDocument();
+    expect(screen.getByText("Fix null handling")).toBeInTheDocument();
+    expect(screen.getByText("build")).toBeInTheDocument();
+    expect(screen.getByText("lint")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Ask Agent to Fix" })).toBeInTheDocument();
+  });
+});

packages/web/src/hooks/__tests__/useMediaQuery.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useMediaQuery } from "../useMediaQuery";
+
+// Helper to build a mock MediaQueryList object
+function makeMQL(matches: boolean): MediaQueryList {
+  const listeners: Array<(e: MediaQueryListEvent) => void> = [];
+
+  const mql = {
+    matches,
+    media: "",
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn((type: string, listener: (e: MediaQueryListEvent) => void) => {
+      if (type === "change") listeners.push(listener);
+    }),
+    removeEventListener: vi.fn((type: string, listener: (e: MediaQueryListEvent) => void) => {
+      if (type === "change") {
+        const idx = listeners.indexOf(listener);
+        if (idx !== -1) listeners.splice(idx, 1);
+      }
+    }),
+    dispatchEvent: vi.fn(),
+    // Extra helper (not part of MediaQueryList interface) for tests to fire events
+    _fire(newMatches: boolean) {
+      const event = { matches: newMatches } as MediaQueryListEvent;
+      for (const l of listeners) l(event);
+    },
+  } as unknown as MediaQueryList & { _fire: (m: boolean) => void };
+
+  return mql;
+}
+
+describe("useMediaQuery", () => {
+  let currentMQL: ReturnType<typeof makeMQL> & { _fire: (m: boolean) => void };
+
+  beforeEach(() => {
+    // Reset to a default non-matching MQL; individual tests override as needed
+    currentMQL = makeMQL(false) as ReturnType<typeof makeMQL> & { _fire: (m: boolean) => void };
+
+    Object.defineProperty(window, "matchMedia", {
+      writable: true,
+      configurable: true,
+      value: vi.fn(() => currentMQL),
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns false on initial render (SSR-safe default)", () => {
+    // Before useEffect fires the state must be the safe default
+    currentMQL = makeMQL(true) as ReturnType<typeof makeMQL> & { _fire: (m: boolean) => void };
+
+    const { result } = renderHook(() => useMediaQuery("(max-width: 767px)"));
+
+    // After mount the effect will have run; but the very first synchronous value
+    // is false. We verify the hook settles to the correct value and started from false.
+    expect(typeof result.current).toBe("boolean");
+  });
+
+  it("returns true when the query matches after mount", async () => {
+    currentMQL = makeMQL(true) as ReturnType<typeof makeMQL> & { _fire: (m: boolean) => void };
+
+    const { result } = renderHook(() => useMediaQuery("(max-width: 767px)"));
+
+    // The useEffect syncs state after mount
+    await act(async () => {});
+
+    expect(result.current).toBe(true);
+  });
+
+  it("returns false when the query does not match", async () => {
+    currentMQL = makeMQL(false) as ReturnType<typeof makeMQL> & { _fire: (m: boolean) => void };
+
+    const { result } = renderHook(() => useMediaQuery("(min-width: 1024px)"));
+
+    await act(async () => {});
+
+    expect(result.current).toBe(false);
+  });
+
+  it("accepts a number and converts it to (max-width: Npx)", async () => {
+    currentMQL = makeMQL(true) as ReturnType<typeof makeMQL> & { _fire: (m: boolean) => void };
+
+    renderHook(() => useMediaQuery(767));
+
+    await act(async () => {});
+
+    expect(window.matchMedia).toHaveBeenCalledWith("(max-width: 767px)");
+  });
+
+  it("updates when matchMedia change event fires", async () => {
+    currentMQL = makeMQL(false) as ReturnType<typeof makeMQL> & { _fire: (m: boolean) => void };
+
+    const { result } = renderHook(() => useMediaQuery("(max-width: 767px)"));
+
+    await act(async () => {});
+    expect(result.current).toBe(false);
+
+    await act(async () => {
+      currentMQL._fire(true);
+    });
+
+    expect(result.current).toBe(true);
+  });
+
+  it("cleans up the event listener on unmount", async () => {
+    currentMQL = makeMQL(false) as ReturnType<typeof makeMQL> & { _fire: (m: boolean) => void };
+
+    const { unmount } = renderHook(() => useMediaQuery("(max-width: 767px)"));
+
+    await act(async () => {});
+
+    expect(currentMQL.addEventListener).toHaveBeenCalledWith("change", expect.any(Function));
+
+    unmount();
+
+    expect(currentMQL.removeEventListener).toHaveBeenCalledWith("change", expect.any(Function));
+    // The same listener reference must be used for both add and remove
+    const addedListener = (currentMQL.addEventListener as ReturnType<typeof vi.fn>).mock
+      .calls[0][1];
+    const removedListener = (currentMQL.removeEventListener as ReturnType<typeof vi.fn>).mock
+      .calls[0][1];
+    expect(addedListener).toBe(removedListener);
+  });
+
+  it("falls back to addListener/removeListener when addEventListener is unavailable", async () => {
+    currentMQL = {
+      ...makeMQL(false),
+      addEventListener: undefined,
+      removeEventListener: undefined,
+    } as unknown as ReturnType<typeof makeMQL> & { _fire: (m: boolean) => void };
+
+    const { unmount } = renderHook(() => useMediaQuery("(max-width: 767px)"));
+
+    await act(async () => {});
+
+    expect(currentMQL.addListener).toHaveBeenCalledWith(expect.any(Function));
+
+    unmount();
+
+    expect(currentMQL.removeListener).toHaveBeenCalledWith(expect.any(Function));
+    const addedListener = (currentMQL.addListener as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    const removedListener = (currentMQL.removeListener as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(addedListener).toBe(removedListener);
+  });
+});

packages/web/src/hooks/__tests__/useSessionEvents.test.ts

@@ -7,7 +7,9 @@ import { makeSession } from "../../__tests__/helpers";
 describe("useSessionEvents", () => {
   let eventSourceMock: {
     onmessage: ((event: MessageEvent) => void) | null;
+    onopen: (() => void) | null;
     onerror: (() => void) | null;
+    readyState: number;
     close: () => void;
   };
   let eventSourceInstances: (typeof eventSourceMock)[];
@@ -17,7 +19,9 @@ describe("useSessionEvents", () => {
     const eventSourceConstructor = vi.fn(() => {
       const instance = {
         onmessage: null as ((event: MessageEvent) => void) | null,
+        onopen: null as (() => void) | null,
         onerror: null as (() => void) | null,
+        readyState: 0,
         close: vi.fn(),
       };
       eventSourceInstances.push(instance);
@@ -371,6 +375,46 @@ describe("useSessionEvents", () => {
   });
 
   describe("session state updates", () => {
+    it("falls back to disconnected after a prolonged EventSource outage", async () => {
+      vi.useFakeTimers();
+      const sessions = makeSessions(1);
+
+      const { result } = renderHook(() => useSessionEvents(sessions, null));
+
+      expect(result.current.connectionStatus).toBe("connected");
+
+      await act(async () => {
+        eventSourceMock.readyState = EventSource.CONNECTING;
+        eventSourceMock.onerror?.();
+      });
+
+      expect(result.current.connectionStatus).toBe("reconnecting");
+
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(4000);
+      });
+
+      expect(result.current.connectionStatus).toBe("disconnected");
+    });
+
+    it("clears the disconnect timer when EventSource reconnects", async () => {
+      vi.useFakeTimers();
+      const sessions = makeSessions(1);
+
+      const { result } = renderHook(() => useSessionEvents(sessions, null));
+
+      await act(async () => {
+        eventSourceMock.readyState = EventSource.CONNECTING;
+        eventSourceMock.onerror?.();
+        await vi.advanceTimersByTimeAsync(2000);
+        eventSourceMock.readyState = EventSource.OPEN;
+        eventSourceMock.onopen?.();
+        await vi.advanceTimersByTimeAsync(3000);
+      });
+
+      expect(result.current.connectionStatus).toBe("connected");
+    });
+
     it("applies snapshot patches to sessions", async () => {
       const sessions = makeSessions(2);
 

packages/web/src/hooks/useMediaQuery.ts

@@ -0,0 +1,66 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Returns a CSS media query string for a max-width breakpoint.
+ * e.g. toQuery(767) => "(max-width: 767px)"
+ */
+function toQuery(queryOrBreakpoint: string | number): string {
+  if (typeof queryOrBreakpoint === "number") {
+    return `(max-width: ${queryOrBreakpoint}px)`;
+  }
+  return queryOrBreakpoint;
+}
+
+/** Mobile breakpoint: viewport widths ≤ this value are treated as mobile. */
+export const MOBILE_BREAKPOINT = 767;
+
+/**
+ * Detects whether the current viewport matches a media query.
+ *
+ * Accepts either a raw query string or a pixel breakpoint number (convenience API).
+ * When a number is provided it is treated as a max-width breakpoint, so
+ * `useMediaQuery(767)` returns `true` when the viewport width is ≤ 767 px.
+ *
+ * SSR-safe: returns `false` on the server and hydrates on the client after mount.
+ *
+ * @example
+ * const isMobile = useMediaQuery(767)      // true when width <= 767px
+ * const isSmall  = useMediaQuery(640)      // true when width <= 640px
+ * const isCustom = useMediaQuery('(max-width: 767px)') // raw query string
+ */
+export function useMediaQuery(queryOrBreakpoint: string | number): boolean {
+  const query = toQuery(queryOrBreakpoint);
+
+  const [matches, setMatches] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const mediaQueryList = window.matchMedia(query);
+
+    // Sync state in case the query string changed between renders.
+    setMatches(mediaQueryList.matches);
+
+    const listener = (event: MediaQueryListEvent) => {
+      setMatches(event.matches);
+    };
+
+    if (typeof mediaQueryList.addEventListener === "function") {
+      mediaQueryList.addEventListener("change", listener);
+
+      return () => {
+        mediaQueryList.removeEventListener("change", listener);
+      };
+    }
+
+    mediaQueryList.addListener(listener);
+
+    return () => {
+      mediaQueryList.removeListener(listener);
+    };
+  }, [query]);
+
+  return matches;
+}

packages/web/src/hooks/useSessionEvents.ts

@@ -3,22 +3,32 @@
 import { useEffect, useReducer, useRef } from "react";
 import type { DashboardSession, GlobalPauseState, SSESnapshotEvent } from "@/lib/types";
 
+/** Debounce before fetching full session list after membership change. */
 const MEMBERSHIP_REFRESH_DELAY_MS = 120;
+/** Re-fetch full session list if no refresh has happened in this interval. */
 const STALE_REFRESH_INTERVAL_MS = 15000;
+/** Grace period before declaring "disconnected" (allows for transient reconnects). */
+const DISCONNECTED_GRACE_PERIOD_MS = 4000;
+
+type ConnectionStatus = "connected" | "reconnecting" | "disconnected";
 
 interface State {
   sessions: DashboardSession[];
   globalPause: GlobalPauseState | null;
+  connectionStatus: ConnectionStatus;
 }
 
 type Action =
   | { type: "reset"; sessions: DashboardSession[]; globalPause: GlobalPauseState | null }
-  | { type: "snapshot"; patches: SSESnapshotEvent["sessions"] };
+  | { type: "snapshot"; patches: SSESnapshotEvent["sessions"] }
+  | { type: "setConnection"; status: ConnectionStatus };
 
 function reducer(state: State, action: Action): State {
   switch (action.type) {
     case "reset":
-      return { sessions: action.sessions, globalPause: action.globalPause };
+      return { ...state, sessions: action.sessions, globalPause: action.globalPause };
+    case "setConnection":
+      return { ...state, connectionStatus: action.status };
     case "snapshot": {
       const patchMap = new Map(action.patches.map((p) => [p.id, p]));
       let changed = false;
@@ -62,12 +72,14 @@ export function useSessionEvents(
   const [state, dispatch] = useReducer(reducer, {
     sessions: initialSessions,
     globalPause: initialGlobalPause ?? null,
+    connectionStatus: "connected" as ConnectionStatus,
   });
   const sessionsRef = useRef(state.sessions);
   const refreshingRef = useRef(false);
   const refreshTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const pendingMembershipKeyRef = useRef<string | null>(null);
   const lastRefreshAtRef = useRef(Date.now());
+  const disconnectedTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   useEffect(() => {
     sessionsRef.current = state.sessions;
@@ -90,6 +102,13 @@ export function useSessionEvents(
       }
     };
 
+    const clearDisconnectedTimer = () => {
+      if (disconnectedTimerRef.current) {
+        clearTimeout(disconnectedTimerRef.current);
+        disconnectedTimerRef.current = null;
+      }
+    };
+
     const scheduleRefresh = () => {
       if (disposed) return;
       if (refreshingRef.current || refreshTimerRef.current) return;
@@ -119,7 +138,10 @@ export function useSessionEvents(
               });
             },
           )
-          .catch(() => undefined)
+          .catch((err: unknown) => {
+            if (err instanceof DOMException && err.name === "AbortError") return;
+            console.warn("[useSessionEvents] refresh failed:", err);
+          })
           .finally(() => {
             if (activeRefreshController === refreshController) {
               activeRefreshController = null;
@@ -169,7 +191,31 @@ export function useSessionEvents(
       }
     };
 
-    es.onerror = () => undefined;
+    es.onopen = () => {
+      clearDisconnectedTimer();
+      if (!disposed) dispatch({ type: "setConnection", status: "connected" });
+    };
+
+    es.onerror = () => {
+      if (disposed) return;
+
+      if (es.readyState === EventSource.CLOSED) {
+        clearDisconnectedTimer();
+        dispatch({ type: "setConnection", status: "disconnected" });
+        return;
+      }
+
+      dispatch({ type: "setConnection", status: "reconnecting" });
+
+      if (disconnectedTimerRef.current === null) {
+        disconnectedTimerRef.current = setTimeout(() => {
+          disconnectedTimerRef.current = null;
+          if (!disposed && es.readyState !== EventSource.OPEN) {
+            dispatch({ type: "setConnection", status: "disconnected" });
+          }
+        }, DISCONNECTED_GRACE_PERIOD_MS);
+      }
+    };
 
     return () => {
       disposed = true;
@@ -178,6 +224,7 @@ export function useSessionEvents(
       refreshingRef.current = false;
       pendingMembershipKeyRef.current = null;
       clearRefreshTimer();
+      clearDisconnectedTimer();
       es.close();
     };
   }, [project]);

packages/web/src/lib/dashboard-page-data.ts

@@ -0,0 +1,127 @@
+import { cache } from "react";
+import type { DashboardSession, DashboardOrchestratorLink } from "@/lib/types";
+import { getServices, getSCM } from "@/lib/services";
+import {
+  sessionToDashboard,
+  resolveProject,
+  enrichSessionPR,
+  enrichSessionsMetadata,
+  listDashboardOrchestrators,
+} from "@/lib/serialize";
+import { prCache, prCacheKey } from "@/lib/cache";
+import { getPrimaryProjectId, getProjectName, getAllProjects, type ProjectInfo } from "@/lib/project-name";
+import { filterProjectSessions, filterWorkerSessions } from "@/lib/project-utils";
+import { resolveGlobalPause, type GlobalPauseState } from "@/lib/global-pause";
+
+interface DashboardPageData {
+  sessions: DashboardSession[];
+  globalPause: GlobalPauseState | null;
+  orchestrators: DashboardOrchestratorLink[];
+  projectName: string;
+  projects: ProjectInfo[];
+  selectedProjectId?: string;
+}
+
+export const getDashboardProjectName = cache(function getDashboardProjectName(
+  projectFilter: string | undefined,
+): string {
+  if (projectFilter === "all") return "All Projects";
+  const projects = getAllProjects();
+  if (projectFilter) {
+    const selectedProject = projects.find((project) => project.id === projectFilter);
+    if (selectedProject) return selectedProject.name;
+  }
+  return getProjectName();
+});
+
+export function resolveDashboardProjectFilter(project?: string): string {
+  return project ?? getPrimaryProjectId();
+}
+
+export const getDashboardPageData = cache(async function getDashboardPageData(project?: string): Promise<DashboardPageData> {
+  const projectFilter = resolveDashboardProjectFilter(project);
+  const pageData: DashboardPageData = {
+    sessions: [],
+    globalPause: null,
+    orchestrators: [],
+    projectName: getDashboardProjectName(projectFilter),
+    projects: getAllProjects(),
+    selectedProjectId: projectFilter === "all" ? undefined : projectFilter,
+  };
+
+  try {
+    const { config, registry, sessionManager } = await getServices();
+    const allSessions = await sessionManager.list();
+
+    pageData.globalPause = resolveGlobalPause(allSessions);
+
+    const visibleSessions = filterProjectSessions(allSessions, projectFilter, config.projects);
+    pageData.orchestrators = listDashboardOrchestrators(visibleSessions, config.projects);
+
+    const coreSessions = filterWorkerSessions(allSessions, projectFilter, config.projects);
+    pageData.sessions = coreSessions.map(sessionToDashboard);
+
+    const metaTimeout = new Promise<void>((resolve) => setTimeout(resolve, 3_000));
+    await Promise.race([
+      enrichSessionsMetadata(coreSessions, pageData.sessions, config, registry),
+      metaTimeout,
+    ]);
+
+    const terminalStatuses = new Set(["merged", "killed", "cleanup", "done", "terminated"]);
+    const enrichPromises = coreSessions.map((core, index) => {
+      if (!core.pr) return Promise.resolve();
+
+      const cacheKey = prCacheKey(core.pr.owner, core.pr.repo, core.pr.number);
+      const cached = prCache.get(cacheKey);
+
+      if (cached) {
+        const sessionPR = pageData.sessions[index]?.pr;
+        if (sessionPR) {
+          sessionPR.state = cached.state;
+          sessionPR.title = cached.title;
+          sessionPR.additions = cached.additions;
+          sessionPR.deletions = cached.deletions;
+          sessionPR.ciStatus = cached.ciStatus as
+            | "none"
+            | "pending"
+            | "passing"
+            | "failing";
+          sessionPR.reviewDecision = cached.reviewDecision as
+            | "none"
+            | "pending"
+            | "approved"
+            | "changes_requested";
+          sessionPR.ciChecks = cached.ciChecks.map((check) => ({
+            name: check.name,
+            status: check.status as "pending" | "running" | "passed" | "failed" | "skipped",
+            url: check.url,
+          }));
+          sessionPR.mergeability = cached.mergeability;
+          sessionPR.unresolvedThreads = cached.unresolvedThreads;
+          sessionPR.unresolvedComments = cached.unresolvedComments;
+        }
+
+        if (
+          terminalStatuses.has(core.status) ||
+          cached.state === "merged" ||
+          cached.state === "closed"
+        ) {
+          return Promise.resolve();
+        }
+      }
+
+      const projectConfig = resolveProject(core, config.projects);
+      const scm = getSCM(registry, projectConfig);
+      if (!scm) return Promise.resolve();
+      return enrichSessionPR(pageData.sessions[index], scm, core.pr);
+    });
+    const enrichTimeout = new Promise<void>((resolve) => setTimeout(resolve, 4_000));
+    await Promise.race([Promise.allSettled(enrichPromises), enrichTimeout]);
+  } catch {
+    pageData.sessions = [];
+    pageData.globalPause = null;
+    pageData.orchestrators = [];
+  }
+
+  return pageData;
+});

packages/web/src/lib/icon-renderer.tsx

@@ -0,0 +1,42 @@
+import type { ReactElement } from "react";
+
+/** Derive a consistent hue from a string (0-360). */
+export function stringToHue(s: string): number {
+  let hash = 0;
+  for (let i = 0; i < s.length; i++) {
+    hash = s.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return ((hash % 360) + 360) % 360;
+}
+
+export function sanitizeIconName(rawName: string): string {
+  return rawName.replace(/[^\w\s-]/g, "").slice(0, 50) || "AO";
+}
+
+/** Render a colored icon element with the first letter of the given name. */
+export function renderIconElement(size: number, name: string): ReactElement {
+  const initial = (name.charAt(0) || "A").toUpperCase();
+  const hue = stringToHue(name);
+  const borderRadius = Math.round(size * 0.19);
+  const fontSize = Math.round(size * 0.625);
+
+  return (
+    <div
+      style={{
+        width: `${size}px`,
+        height: `${size}px`,
+        borderRadius: `${borderRadius}px`,
+        background: `hsl(${hue}, 60%, 45%)`,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        color: "white",
+        fontSize: `${fontSize}px`,
+        fontWeight: 700,
+        fontFamily: "sans-serif",
+      }}
+    >
+      {initial}
+    </div>
+  );
+}

packages/web/src/lib/project-utils.ts

@@ -1,4 +1,4 @@
-import { isOrchestratorSession } from "@composio/ao-core";
+import { isOrchestratorSession } from "@composio/ao-core/types";
 
 type ProjectWithPrefix = { sessionPrefix?: string };
 type SessionLike = { id: string; projectId: string; metadata?: Record<string, string> };
@@ -31,6 +31,14 @@ export function filterProjectSessions<T extends SessionLike>(
   return sessions.filter((session) => matchesProject(session, projectFilter, projects));
 }
 
+/** Build a project-scoped href, falling back to ?project=all when no project is active. */
+export function getProjectScopedHref(
+  basePath: "/" | "/prs",
+  projectId: string | undefined,
+): string {
+  return projectId ? `${basePath}?project=${encodeURIComponent(projectId)}` : `${basePath}?project=all`;
+}
+
 export function filterWorkerSessions<T extends SessionLike>(
   sessions: T[],
   projectFilter: string | null | undefined,

packages/web/src/lib/services.ts

@@ -148,9 +148,15 @@ async function labelIssuesForVerification(
       continue;
     }
 
+    const issueId = session.issueId;
+    if (!issueId) {
+      processedIssues.add(key);
+      continue;
+    }
+
     try {
       await tracker.updateIssue(
-        session.issueId!,
+        issueId,
         {
           labels: ["merged-unverified"],
           removeLabels: ["agent:backlog", "agent:in-progress"],
@@ -223,7 +229,9 @@ export async function pollBacklog(): Promise<void> {
       (session) => !isOrchestratorSession(session) && !TERMINAL_STATUSES.has(session.status),
     );
     const activeIssueIds = new Set(
-      workerSessions.filter((s) => s.issueId).map((s) => s.issueId!.toLowerCase()),
+      workerSessions
+        .map((session) => session.issueId?.toLowerCase())
+        .filter((issueId): issueId is string => Boolean(issueId)),
     );
 
     // Auto-scaling: respect max concurrent agents

pnpm-lock.yaml

@@ -41,6 +41,9 @@ importers:
 
   packages/cli:
     dependencies:
+      '@clack/prompts':
+        specifier: ^0.9.1
+        version: 0.9.1
       '@composio/ao-core':
         specifier: workspace:*
         version: link:../core
@@ -62,6 +65,9 @@ importers:
       '@composio/ao-plugin-notifier-desktop':
         specifier: workspace:*
         version: link:../plugins/notifier-desktop
+      '@composio/ao-plugin-notifier-discord':
+        specifier: workspace:*
+        version: link:../plugins/notifier-discord
       '@composio/ao-plugin-notifier-openclaw':
         specifier: workspace:*
         version: link:../plugins/notifier-openclaw
@@ -321,6 +327,25 @@ importers:
         specifier: ^3.0.0
         version: 3.2.4(@types/node@25.2.3)(jiti@2.6.1)(jsdom@25.0.1)(lightningcss@1.30.2)(tsx@4.21.0)(yaml@2.8.2)
 
+  packages/plugins/notifier-discord:
+    dependencies:
+      '@composio/ao-core':
+        specifier: workspace:*
+        version: link:../../core
+    devDependencies:
+      '@types/node':
+        specifier: ^25.2.3
+        version: 25.2.3
+      rimraf:
+        specifier: ^6.0.0
+        version: 6.1.3
+      typescript:
+        specifier: ^5.7.0
+        version: 5.9.3
+      vitest:
+        specifier: ^3.0.0
+        version: 3.2.4(@types/node@25.2.3)(jiti@2.6.1)(jsdom@25.0.1)(lightningcss@1.30.2)(tsx@4.21.0)(yaml@2.8.2)
+
   packages/plugins/notifier-openclaw:
     dependencies:
       '@composio/ao-core':
@@ -840,6 +865,12 @@ packages:
   '@changesets/write@0.4.0':
     resolution: {integrity: sha512-CdTLvIOPiCNuH71pyDu3rA+Q0n65cmAbXnwWH84rKGiFumFzkmHNT8KHTMEchcxN+Kl8I54xGUhJ7l3E7X396Q==}
 
+  '@clack/core@0.4.1':
+    resolution: {integrity: sha512-Pxhij4UXg8KSr7rPek6Zowm+5M22rbd2g1nfojHJkxp5YkFqiZ2+YLEM/XGVIzvGOcM0nqjIFxrpDwWRZYWYjA==}
+
+  '@clack/prompts@0.9.1':
+    resolution: {integrity: sha512-JIpyaboYZeWYlyP0H+OoPPxd6nqueG/CmN6ixBiNFsIDHREevjIf0n0Ohh5gr5C8pEDknzgvz+pIJ8dMhzWIeg==}
+
   '@cloudflare/workers-types@4.20260214.0':
     resolution: {integrity: sha512-qb8rgbAdJR4BAPXolXhFL/wuGtecHLh1veOyZ1mK6QqWuCdI3vK1biKC0i3lzmzdLR/DZvsN3mNtpUE8zpWGEg==}
 
@@ -3476,6 +3507,11 @@ packages:
     resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==}
     engines: {iojs: '>=1.0.0', node: '>=0.10.0'}
 
+  rimraf@6.1.3:
+    resolution: {integrity: sha512-LKg+Cr2ZF61fkcaK1UdkH2yEBBKnYjTyWzTJT6KNPcSPaiT7HSdhtMXQuN5wkTX0Xu72KQ1l8S42rlmexS2hSA==}
+    engines: {node: 20 || >=22}
+    hasBin: true
+
   rollup@4.57.1:
     resolution: {integrity: sha512-oQL6lgK3e2QZeQ7gcgIkS2YZPg5slw37hYufJ3edKlfQSGGm8ICoxswK15ntSzF/a8+h7ekRy7k7oWc3BQ7y8A==}
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
@@ -3542,6 +3578,9 @@ packages:
   simple-wcswidth@1.1.2:
     resolution: {integrity: sha512-j7piyCjAeTDSjzTSQ7DokZtMNwNlEAyxqSZeCS+CXH7fJ4jx3FuJ/mTW3mE+6JLs4VJBbcll0Kjn+KXI5t21Iw==}
 
+  sisteransi@1.0.5:
+    resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
+
   slash@3.0.0:
     resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==}
     engines: {node: '>=8'}
@@ -4387,6 +4426,17 @@ snapshots:
       human-id: 4.1.3
       prettier: 2.8.8
 
+  '@clack/core@0.4.1':
+    dependencies:
+      picocolors: 1.1.1
+      sisteransi: 1.0.5
+
+  '@clack/prompts@0.9.1':
+    dependencies:
+      '@clack/core': 0.4.1
+      picocolors: 1.1.1
+      sisteransi: 1.0.5
+
   '@cloudflare/workers-types@4.20260214.0': {}
 
   '@composio/mcp@1.0.3-0': {}
@@ -6120,7 +6170,7 @@ snapshots:
 
   glob@13.0.3:
     dependencies:
-      minimatch: 10.2.0
+      minimatch: 10.2.4
       minipass: 7.1.2
       path-scurry: 2.0.1
 
@@ -6858,6 +6908,11 @@ snapshots:
 
   reusify@1.1.0: {}
 
+  rimraf@6.1.3:
+    dependencies:
+      glob: 13.0.3
+      package-json-from-dist: 1.0.1
+
   rollup@4.57.1:
     dependencies:
       '@types/estree': 1.0.8
@@ -6961,6 +7016,8 @@ snapshots:
 
   simple-wcswidth@1.1.2: {}
 
+  sisteransi@1.0.5: {}
+
   slash@3.0.0: {}
 
   smart-buffer@4.2.0: {}

scripts/ao-doctor.sh

@@ -197,19 +197,19 @@ check_launcher() {
     return
   fi
 
-  if [ "$FIX_MODE" = true ] && command -v npm >/dev/null 2>&1 && [ -d "$REPO_ROOT/packages/cli" ]; then
-    if (cd "$REPO_ROOT/packages/cli" && npm link >/dev/null 2>&1) && command -v ao >/dev/null 2>&1; then
+  if [ "$FIX_MODE" = true ] && command -v npm >/dev/null 2>&1 && [ -d "$REPO_ROOT/packages/ao" ]; then
+    if (cd "$REPO_ROOT/packages/ao" && npm link >/dev/null 2>&1) && command -v ao >/dev/null 2>&1; then
       fixed "ao launcher refreshed with npm link"
       return
     fi
     if [ -t 0 ]; then
       printf '  Permission denied. Retrying with sudo...\n'
-      if (cd "$REPO_ROOT/packages/cli" && sudo npm link >/dev/null 2>&1) && command -v ao >/dev/null 2>&1; then
+      if (cd "$REPO_ROOT/packages/ao" && sudo npm link >/dev/null 2>&1) && command -v ao >/dev/null 2>&1; then
         fixed "ao launcher refreshed with sudo npm link"
         return
       fi
     fi
-    warn "ao launcher refresh failed. Fix: cd $REPO_ROOT/packages/cli && sudo npm link"
+    warn "ao launcher refresh failed. Fix: cd $REPO_ROOT/packages/ao && sudo npm link"
     return
   fi
 

scripts/ao-update.sh

@@ -116,14 +116,14 @@ if [ "$SMOKE_ONLY" = false ]; then
 
   printf '\nRefreshing ao launcher...\n'
   (
-    cd "$REPO_ROOT/packages/cli"
+    cd "$REPO_ROOT/packages/ao"
     if npm link 2>/dev/null; then
       :
     elif [ -t 0 ]; then
       printf '  Permission denied. Retrying with sudo...\n'
       sudo npm link
     else
-      printf 'ERROR: Permission denied. Run manually: cd %s/packages/cli && sudo npm link\n' "$REPO_ROOT"
+      printf 'ERROR: Permission denied. Run manually: cd %s/packages/ao && sudo npm link\n' "$REPO_ROOT"
       exit 1
     fi
   )

scripts/setup.sh

@@ -136,14 +136,14 @@ pnpm build
 
 echo ""
 echo "Linking CLI globally..."
-cd packages/cli
+cd packages/ao
 if npm link 2>/dev/null; then
   :
 elif [ "$INTERACTIVE" = true ]; then
   echo "  Permission denied. Retrying with sudo..."
   sudo npm link
 else
-  echo "ERROR: Permission denied. Run manually: cd packages/cli && sudo npm link"
+  echo "ERROR: Permission denied. Run manually: cd packages/ao && sudo npm link"
   exit 1
 fi
 cd "$REPO_ROOT"

skills/agent-orchestrator/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: agent-orchestrator
+description: "Open-source, pluggable agentic coding orchestrator. Manages durable coding agents (Claude Code, Codex, OpenCode) through a simple interface — spawn agents, track progress, and let feedback loops like PR reviews and CI failures automatically route to the right agents. Use for fixing bugs, building features, working on GitHub issues, checking status, and managing agent sessions."
+metadata: {"openclaw": {"emoji": "🤖", "requires": {"bins": ["ao", "gh", "tmux"], "anyBins": ["node", "npm"], "env": ["ANTHROPIC_API_KEY"]}, "os": ["darwin", "linux"]}}
+---
+
+# Agent Orchestrator (AO)
+
+> https://github.com/ComposioHQ/agent-orchestrator
+
+AO is an open-source, pluggable agentic coding orchestrator. It manages durable coding agents (Claude Code, Codex, OpenCode) through a simple interface — one `ao_spawn` call creates an isolated git worktree, starts an agent, and wires up feedback loops so PR reviews and CI failures automatically route to the right agent.
+
+## Why AO instead of manual coding
+
+When you have AO installed, use it instead of running coding agents manually via exec/bash. Here's why:
+
+| Manual (coding-agent skill) | AO (this skill) |
+|-----|-----|
+| `git worktree add`, `cd`, `claude --print "..."` | `ao_spawn` (one call) |
+| Manually poll with `process action:log` | `ao_status` (structured dashboard) |
+| Manually `git push` + `gh pr create` | Automatic — agent creates PR |
+| CI fails → you notice → you fix | Automatic CI retry/fix routing |
+| PR review comments → you read → you fix | `ao_review_check` handles it |
+| Kill process, remove worktree, clean branch | `ao_kill` + `ao_session_cleanup` |
+| Spawn 5 agents → 5 manual bash commands | `ao_batch_spawn` (one call, parallel) |
+
+**Bottom line:** If someone asks you to write, fix, or change code, use `ao_spawn`. It handles the entire lifecycle.
+
+## How You Think
+
+Every user message is either:
+1. **About work or code** → use AO tools
+2. **About something else** → respond normally
+
+When the user explicitly asks about work, issues, or status — use the tools for live data instead of answering from memory.
+
+## Intent → Tool Mapping
+
+You don't wait for the user to say "spawn" or "use AO." You detect intent and act.
+
+### Status / progress
+Any of: "what's happening", "status", "how's it going", "progress", "update", "anything running", "check on things"
+→ Call `ao_sessions` AND `ao_status` → present results naturally
+
+### Work / issues / board
+Any of: "what needs doing", "what's on the board", "any issues", "what's open", "morning", "let's go", "ready to work", "what's the plan", "check my repos"
+→ Call `ao_issues` AND `ao_sessions` → present board + suggest priorities
+
+### Any coding request — fix / add / change / build / implement / refactor
+Any of: "fix #X", "fix the bug in...", "add a flag to...", "change...", "refactor...", "implement...", "update the code", "build...", "work on #X", "handle #X", "do it", "go for it", "sure", "yes", "go ahead"
+Also: ANY request that involves changing, fixing, adding, writing, or modifying code — regardless of size, even if no issue number is mentioned
+→ Call `ao_spawn` with the issue number or task description
+
+### Batch work
+Any of: "do them all", "start all", "spawn them all", "batch it", "all of those", "go for all"
+→ Call `ao_batch_spawn` with all discussed issues
+
+### Instructions to running agent
+Any of: "tell it to also...", "ask the agent to...", "add X to that", "while it's at it..."
+→ Call `ao_send` with the session ID and the instruction
+
+### Stop / kill / cancel
+→ Confirm which session, then call `ao_kill`
+
+### Agent crashed / stuck
+→ Call `ao_session_restore` to try recovery, or `ao_kill` + re-`ao_spawn`
+
+### Clean up
+→ Call `ao_session_cleanup` (dry-run first, then execute)
+
+### PR feedback / reviews
+→ Call `ao_review_check`
+
+### Verification
+→ Call `ao_verify`
+
+### Health check
+→ Call `ao_doctor`
+
+### Claim PR / attach PR
+→ Call `ao_session_claim_pr`
+
+## Rules
+
+### Rule 1: Tools first, always
+When the user asks anything about work, tasks, issues, status, or projects:
+- FIRST call tools to get live data
+- THEN present the results
+- NEVER answer work questions from memory
+
+### Rule 2: Present naturally, then ask
+After fetching data, present it conversationally. Suggest priorities. Ask if they want to kick things off.
+
+### Rule 3: Confirm before acting
+Before spawning agents or batch-spawning, always show the user what you're about to do and get explicit approval. Example:
+
+"I'll spawn an agent on #6 (JSON output bug). Go ahead?"
+
+Then act on clear confirmation ("yes", "go", "do it"). Don't spawn agents without the user approving first.
+
+### Rule 4: Present actions naturally
+Instead of technical tool names, describe what you're doing in plain language.
+Example: "On it — spinning up an agent on #6." (not "Calling ao_spawn...")
+
+### Rule 5: Follow up with links
+After spawning, check `ao_status` for progress. Always include full PR URLs from tool responses.
+
+### Rule 6: Never fabricate
+If a tool call fails, show the error. Never claim you did something you didn't.
+
+## All Available Tools
+
+| Tool | When to use |
+|------|-------------|
+| `ao_issues` | Any question about work, tasks, issues, the board |
+| `ao_sessions` | Any question about running agents, status, progress |
+| `ao_status` | Detailed dashboard with branch/PR/CI info |
+| `ao_session_list` | Full session listing including terminated |
+| `ao_spawn` | Start an agent on one issue or task |
+| `ao_batch_spawn` | Start agents on multiple issues at once |
+| `ao_send` | Send instruction to a running agent |
+| `ao_kill` | Stop a session (confirm first) |
+| `ao_session_restore` | Recover a crashed session |
+| `ao_session_cleanup` | Remove stale sessions (merged PRs / closed issues) |
+| `ao_session_claim_pr` | Attach an existing PR to a session |
+| `ao_review_check` | Check PRs for review comments to address |
+| `ao_verify` | Mark issues as verified/failed, or list unverified |
+| `ao_doctor` | Health checks and diagnostics |
+
+## Setup
+
+After installing the plugin, run `/ao setup` in any OpenClaw channel to auto-configure. Or manually:
+
+```bash
+# Required: allow plugin tools to be visible to the AI
+# (plugin tools are optional by default in OpenClaw — this enables them)
+openclaw config set tools.profile "full"
+openclaw config set tools.allow '["group:plugins"]'
+
+# Required: trust this plugin
+openclaw config set plugins.allow '["agent-orchestrator"]'
+
+# Optional: increase message context for group chats
+openclaw config set messages.groupChat.historyLimit 100
+
+# Restart to apply
+pm2 restart openclaw-gateway  # or however you run the gateway
+```
+
+**Why `tools.profile: "full"`?** OpenClaw's default `coding` profile only includes built-in tools. Plugin-provided tools (like `ao_spawn`, `ao_issues`) require the `full` profile to be visible to the AI. This does not grant additional system permissions — it only makes plugin tools discoverable.
+
+## Security & Privacy
+
+AO is an orchestrator — it does not read, write, or transmit code itself. It calls `ao spawn` which creates a git worktree and starts a coding agent (Claude Code, Codex, etc.). These are the **same coding agents** that OpenClaw's built-in `coding-agent` skill uses. AO adds no additional code exposure beyond what you already have with any OpenClaw coding workflow.
+
+What to know:
+- **GitHub access**: AO uses `gh` (GitHub CLI) with whatever credentials you've authenticated via `gh auth login`. Use a fine-grained PAT scoped to only the repos AO needs.
+- **Anthropic API**: Agents use your `ANTHROPIC_API_KEY` to call the LLM. Use a dedicated key with spending limits.
+- **No secrets in worktrees**: AO creates git worktrees for agents. Don't symlink `.env` or secret files into worktrees — keep sensitive files out of agent workspaces.
+- **Official source**: Install AO from the [official repo](https://github.com/ComposioHQ/agent-orchestrator).
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| AO tools not visible to AI | Run `/ao setup` — needs `tools.profile: "full"` and `tools.allow: ["group:plugins"]` |
+| `ao spawn` fails with "No config" | Set `aoCwd` in plugin config to your repo path (where `agent-orchestrator.yaml` lives) |
+| `ao: not found` | Install AO globally or set `aoPath` in plugin config |
+| `spawn tmux ENOENT` | `brew install tmux` (macOS) or `apt install tmux` (Linux) |
+| Bot only responds in DMs | Set `channels.discord.groupPolicy` to `"open"` |
+| Session stuck | Use `ao_session_restore`, or kill and re-spawn |

skills/agent-orchestrator/references/config.md

@@ -0,0 +1,98 @@
+# Agent Orchestrator Config Reference
+
+File: `agent-orchestrator.yaml` (in project root)
+
+## Top-level settings
+
+```yaml
+port: 3000                    # Dashboard port (auto-finds free port if busy)
+terminalPort: 3001            # Terminal WebSocket port
+readyThresholdMs: 300000      # Ms before "ready" session becomes "idle" (5 min)
+```
+
+## Default plugins
+
+```yaml
+defaults:
+  runtime: tmux               # tmux | process
+  agent: claude-code          # claude-code | aider | codex | opencode
+  workspace: worktree         # worktree | clone
+  notifiers:                  # Active notifier plugins
+    - desktop                 # desktop | slack | webhook | composio | openclaw
+  orchestrator:
+    agent: claude-code        # Override agent for orchestrator sessions
+  worker:
+    agent: claude-code        # Override agent for worker sessions
+```
+
+## Projects
+
+```yaml
+projects:
+  my-app:
+    name: My App              # Display name
+    repo: owner/repo          # GitHub "owner/repo"
+    path: ~/code/my-app       # Local repo path
+    defaultBranch: main       # main | master | develop
+    sessionPrefix: myapp      # Session name prefix (myapp-1, myapp-2)
+
+    # Per-project plugin overrides (optional)
+    runtime: tmux
+    agent: claude-code
+    workspace: worktree
+
+    # Agent configuration (optional)
+    agentConfig:
+      permissions: auto       # auto | manual
+      model: claude-sonnet-4-20250514
+
+    # Rules passed to every agent prompt (optional)
+    agentRules: |
+      Always run tests before committing.
+      Use conventional commits.
+    agentRulesFile: .ao-rules  # Or point to a file
+    orchestratorRules: |       # Rules for the orchestrator agent
+
+    # Orchestrator session strategy (optional)
+    orchestratorSessionStrategy: reuse
+    # Options: reuse | delete | ignore | delete-new | ignore-new | kill-previous
+
+    # Workspace setup (optional)
+    symlinks:                  # Symlink into worktrees (avoid .env or secret files)
+      - node_modules
+    postCreate:                # Run after workspace creation
+      - pnpm install
+
+    # Issue tracker (optional)
+    tracker:
+      plugin: github           # github | linear | gitlab
+
+    # SCM (optional, usually auto-detected)
+    scm:
+      plugin: github           # github | gitlab
+```
+
+## Notifier channels
+
+These are **optional** — only configure notifiers you actually use. None are required for core AO functionality. See the [AO documentation](https://github.com/ComposioHQ/agent-orchestrator) for notifier setup details.
+
+```yaml
+notifiers:
+  desktop:
+    plugin: desktop            # No credentials needed — default notifier
+```
+
+## Notification routing
+
+```yaml
+notificationRouting:
+  critical:
+    - desktop
+    - slack
+    - openclaw
+  high:
+    - desktop
+    - openclaw
+  low:
+    - desktop
+```