fix: consolidate verified workspace issue sweep (#432)

* fix(start): use server-entry wrapper for production

* fix(swarm): reconcile oneshot checkpoints and ignore phantom blockers

* fix(profiles): sync editable descriptions from profile config

* fix: show cron jobs across Hermes profiles

* fix(capabilities): clarify dashboard-backed API detection

* feat: make Conductor use native Swarm fallback

Treat Workspace-native Swarm as the official Conductor fallback when the dashboard mission API is unavailable. Preserve dashboard-first dispatch, native status/cancel handling, provider-neutral setup docs, and regression coverage for gateway capability detection, swarm health, roster/profile handling, and native Conductor responses.

* fix(usage-meter): reposition menu trigger for better alignment

- Adjusted the position of the menu trigger in the usage meter component to enhance layout consistency and user experience.

fix(chat-panel): adjust position of chat panel toggle button

- Updated the positioning of the chat panel toggle button to improve visibility and accessibility by changing its bottom and right offsets.

* fix(stt): wire Groq/OpenAI voice transcription into chat

* Fix Workspace Kanban loopback dashboard link

* fix(update): do not open historical release notes on startup

* fix(chat): clear stale thinking runs reliably

* fix(dashboard): trust sessions endpoint for status

* fix(settings): address review — local default, OAuth lifecycle, validation

* fix(dashboard): always scrape live session token from HTML

* fix(chat): avoid portable history replay on bound sessions

* fix(settings): remove dead smart routing controls

* fix(tasks-api): guard against HTML catch-all in probeBackend

The /api/hermes-tasks route was renamed to /api/claude-tasks in commit
efcb7d1, but the probe logic still listed the old route as a candidate.
When probed, the SPA catch-all returned a 200 HTML response instead of
a 404, so probeBackend() treated it as a valid (empty) backend and then
failed when the actual task fetch threw.

Fixes:
- probeBackend() now checks Content-Type: application/json and returns
  -1 for non-JSON responses, so future route renames degrade gracefully.
- resolveBackend() now only selects hermes if hermesCount > 0, defaulting
  to claude-tasks (the active backend post rename) when hermes is absent.

* fix(terminal): default cwd to ~ and fallback if path missing

PTY helper chdir fails when ~/.hermes is absent (common in Docker).
Default shell cwd to home; server falls back to HOME if cwd does not exist.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(settings): satisfy lint on custom providers UI

* fix(docker): add -m flag to useradd so workspace home dir is created

Without -m, the system account has no /home/workspace directory.
The auth middleware tries to write the session store at
/home/workspace/.hermes/workspace-sessions.json; mkdirSync fails with
EACCES because /home/ is root-owned (755), causing the 'Failed to
persist session store' warning and a 500 on every authenticated route.

Adding -m causes useradd to create and chown /home/workspace correctly
so the session store can be written on first login.

* fix(tasks): preserve real session links and restore task launch flow

* fix(launchd): install macOS plist from server-entry template

* fix(docker): expose dashboard API and persist workspace volumes

* fix(jobs): serialize deliver targets for cron API

* Make Hermes Workspace installable as PWA

* chore(deps): pin direct tanstack versions

* feat: align semantic Hermes swarm agents

Add semantic swarm roster metadata, profile/tool/skill docs, shared semantic worker ID validation, focused roster regression coverage, and one-shot checkpoint capture for dispatch smoke tests.

* fix(conductor): pass through sessionKeyPrefix from portable spawn result

sessionKeyPrefix was hardcoded to null in conductor-spawn.ts, breaking
async session resolution when the dashboard backend returns a prefix.
Now mirrors the sessionKey pattern and passes through the value from
the spawn result.

Co-authored-by: Hermes Agent

* feat(swarm): bridge workspace kanban to native Hermes

* fix(chat): keep portable main pinned without breaking resolved sessions

* Add Windows startup script for Hermes Workspace

Document PowerShell usage for launching and restarting gateway + workspace via WSL tmux.

Co-Authored-By: Oz <oz-agent@warp.dev>

* fix(config): name Hermes Agent in restart notice

* fix(swarm): reconcile aggregate semantic worker exports

---------

Co-authored-by: Aurora release bot <release@outsourc-e.com>
Co-authored-by: motoki takahashi <motokitakahashi@motokinoMac-mini.local>
Co-authored-by: Vicky Wonder <vicky@openclaw.ai>
Co-authored-by: Vitaliy Isikov <visikov+supagoku@gmail.com>
Co-authored-by: Hermes Agent <hermes-agent@local>
Co-authored-by: Nikolay Mohr <nikomohr96@gmail.com>
Co-authored-by: Niko Mohr <niko@friendsfromcollege.de>
Co-authored-by: wtchronos <262830926+wtchronos@users.noreply.github.com>
Co-authored-by: Dak0verflow <dakotaferris@gmail.com>
Co-authored-by: norema <mamadou.marone.19@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: daoyuan <ludaoyuan1989@gmail.com>
Co-authored-by: firemountain <firemountain@gmail.com>
Co-authored-by: RAZSOC Local <razsoc@local>
Co-authored-by: Waylon Kenning <waylonkenning@Waylons-MacBook-Pro.local>
Co-authored-by: Kublai <kublai@kublai.local>
Co-authored-by: justa <justa@local>
Co-authored-by: Oz <oz-agent@warp.dev>

Author: 19 people

.env.example

@@ -10,15 +10,14 @@
 # container needs the key for whichever provider you configured in
 # ~/.hermes/config.yaml. Common options:
 #
-#   Anthropic (Claude):      https://console.anthropic.com/settings/keys
+#   OpenAI Codex / OpenAI-compatible: configure through `hermes setup` / `hermes model`
 #   OpenAI (GPT / o-series): https://platform.openai.com/api-keys
 #   OpenRouter (many models, free tier available): https://openrouter.ai/keys
 #   Google (Gemini):         https://aistudio.google.com/app/apikey
 #   Ollama / local:          No key needed — just run `ollama serve`
 #
 # Uncomment ONLY the key(s) for the providers you actually use.
 
-# ANTHROPIC_API_KEY=sk-ant-...
 # OPENAI_API_KEY=sk-...
 # OPENROUTER_API_KEY=sk-or-v1-...
 # GOOGLE_API_KEY=AIza...
@@ -51,8 +50,8 @@
 # Set this if hermes-agent is installed elsewhere
 # HERMES_AGENT_PATH=/path/to/hermes-agent
 
-# Server port (default: 3002)
-# PORT=3002
+# Server port (default: 3000)
+# PORT=3000
 
 # ══════════════════════════════════════════════════════════════
 # Security
@@ -110,11 +109,11 @@
 # all live on the dashboard, not the gateway.
 # HERMES_DASHBOARD_URL=http://127.0.0.1:9119
 
-# Dashboard API bearer token (optional)
+# Dashboard session token
 #
-# Preferred over the legacy HTML-scrape token flow. Set this to a dashboard
-# bearer and the workspace uses it directly for dashboard API calls (see #124).
-# HERMES_DASHBOARD_TOKEN=
+# Workspace scrapes the dashboard's ephemeral session token from the root HTML
+# automatically. Do not copy this token into .env: it changes whenever the
+# dashboard restarts and stale values cause 401s on /api/sessions and related APIs.
 
 # Bypass fail-closed startup guard (NOT recommended)
 #

.npmrc

@@ -1,3 +1 @@
 legacy-peer-deps=true
-
-

AGENTS.md

@@ -0,0 +1,25 @@
+# Hermes Workspace Agent Contract
+
+This workspace uses semantic Hermes swarm workers, not numbered-only lanes. The source of truth for routing is `swarm.yaml`; each worker also has a matching profile under `~/.hermes/profiles/<worker-id>/`, a role skill `<worker-id>-core`, and a wrapper in `~/.local/bin/`.
+
+## Current semantic roster
+
+| Worker | Wrapper | Tools | Skills | MCP | Plugins |
+|---|---|---|---|---|---|
+| `orchestrator` | `orchestrator:plan` | todo, kanban, delegation, terminal, file, gbrain, session_search, cronjob, skills, clarify, web | orchestrator-core, gstack-for-hermes, gbrain, kanban-orchestrator, subagent-driven-development, writing-plans, requesting-code-review, workspace-dispatch | gbrain | none |
+| `km-agent` | `km:health` | gbrain, file, terminal, session_search, skills, todo, cronjob, web | km-agent-core, gbrain, obsidian-markdown, obsidian-cli, obsidian-bases, json-canvas, gstack-for-hermes | gbrain | none |
+| `builder` | `builder:task` | terminal, file, browser, web, gbrain, session_search, skills, todo | builder-core, gstack-for-hermes, test-driven-development, systematic-debugging, github-pr-workflow, requesting-code-review, codebase-inspection | gbrain | none |
+| `reviewer` | `reviewer:gate` | terminal, file, web, gbrain, session_search, skills | reviewer-core, requesting-code-review, github-code-review, systematic-debugging, gstack-for-hermes, gbrain, codebase-inspection | gbrain | none |
+| `qa` | `qa:smoke` | browser, terminal, file, vision, gbrain, session_search, skills, web | qa-core, browser-harness-power-use, dogfood, gstack-for-hermes | gbrain | none |
+| `researcher` | `researcher:quick` | gbrain, web, browser, terminal, file, vision, session_search, skills, todo | researcher-core, gbrain, autoresearch, browser-harness-power-use, gstack-for-hermes, researcher-quick, researcher-autoresearch, arxiv, youtube-content, polymarket | gbrain | none |
+| `ops-watch` | `ops:health` | terminal, cronjob, file, gbrain, skills, session_search, web | ops-watch-core, gbrain, hermes-agent, systematic-debugging, webhook-subscriptions | gbrain | none |
+| `maintainer` | `maintainer:check` | terminal, file, web, browser, gbrain, session_search, skills | maintainer-core, github-repo-management, github-pr-workflow, github-issues, github-code-review, gbrain, gstack-for-hermes, hermes-agent | gbrain | none |
+| `strategist` | `strategist:review` | gbrain, web, session_search, file, skills, todo, clarify | strategist-core, gstack-for-hermes, gbrain, writing-plans, polymarket | gbrain | none |
+| `inbox-triage` | `inbox:triage` | gbrain, web, file, session_search, todo, skills, terminal | inbox-triage-core, gbrain, obsidian-markdown, gstack-for-hermes, defuddle, youtube-content | gbrain | none |
+
+## Operating rules
+
+- Keep `swarm.yaml`, profile `config.yaml`, profile core skills, and wrappers aligned when changing a worker.
+- Prefer GBrain-first lookup for context-sensitive RAZSOC/Hermes/workflow decisions.
+- Builder implements; Reviewer gates; QA verifies behavior; Orchestrator routes and enforces greenlight.
+- Do not enable optional Hermes plugins globally unless the task explicitly needs them; record plugin/toolset alignment in `swarm.yaml` first.

Dockerfile

@@ -30,7 +30,7 @@ FROM node:22-slim
 RUN apt-get update && apt-get install -y --no-install-recommends \
       ca-certificates curl tini python3 \
     && rm -rf /var/lib/apt/lists/* \
-    && groupadd -r workspace && useradd -r -g workspace -u 10010 workspace
+    && groupadd -r workspace && useradd -r -g workspace -u 10010 -m workspace
 
 WORKDIR /app
 

README.md

@@ -14,7 +14,7 @@
 
 > Not a chat wrapper. A complete workspace — orchestrate agents, browse memory, manage skills, and control everything from one interface.
 
-> **v2 — zero-fork.** Clone, don't fork. Runs on vanilla [`NousResearch/hermes-agent`](https://github.com/NousResearch/hermes-agent) installed via Nous's own installer. Chat, sessions, memory, skills, jobs, MCP, terminal, dashboard, Agent View, and Operations are all in vanilla parity. **Conductor** currently requires an additional dashboard plugin not in upstream yet — the UI shows a clear placeholder when that endpoint isn't available ([#262](https://github.com/outsourc-e/hermes-workspace/issues/262)). Everything else works with zero patches.
+> **v2 — zero-fork.** Clone, don't fork. Runs on vanilla [`NousResearch/hermes-agent`](https://github.com/NousResearch/hermes-agent) installed via Nous's own installer. Chat, sessions, memory, skills, jobs, MCP, terminal, dashboard, Agent View, and Operations are all in vanilla parity. **Conductor** uses the dashboard mission API when available and falls back to Workspace-native Swarm dispatch (`mode: native-swarm`) when the dashboard endpoint is absent, preserving zero-fork behavior ([#262](https://github.com/outsourc-e/hermes-workspace/issues/262)).
 
 ![Hermes Workspace](./docs/screenshots/splash.png)
 
@@ -48,7 +48,7 @@ Start here: [docs/swarm/](./docs/swarm/)
 - 🔌 **MCP** — Full /mcp page (catalog + marketplace + sources), or fallback to local config CRUD
 - 📁 **Files + Terminal** — Full workspace file browser with Monaco; cross-platform PTY terminal
 - 🎮 **Operations** — Multi-agent dashboard with profile presets (Sage/Trader/Builder/Scribe/Ops) and 'Needs setup' detection
-- 📡 **Conductor** — Mission dispatch + decomposition (requires upstream dashboard plugin, see [#262](https://github.com/outsourc-e/hermes-workspace/issues/262))
+- 📡 **Conductor** — Mission dispatch + decomposition with dashboard-backed missions when available and Workspace-native Swarm fallback otherwise
 - 👥 **Agent View** — Live agent panel in chat with avatar, queue, history, usage meter
 - 🐝 **Swarm Mode** — Persistent tmux-backed Hermes Agent workers with role-based dispatch
 - 🗄️ **Dashboard** — Aggregated overview: sessions, model mix, cost ledger, attention card, ops strip
@@ -213,8 +213,7 @@ HERMES_API_URL=http://127.0.0.1:8642
 
 # Optional: provider keys the Hermes Agent gateway can read at runtime.
 # You only need the key(s) for whichever provider(s) you actually use.
-# ANTHROPIC_API_KEY=***         # Anthropic
-# OPENAI_API_KEY=sk-...                # GPT / o-series
+# OPENAI_API_KEY=sk-...                # GPT / o-series / OpenAI-compatible
 # OPENROUTER_API_KEY=sk-or-v1-...      # OpenRouter (incl. free models)
 # GOOGLE_API_KEY=AIza...               # Gemini
 # (Ollama / LM Studio / local servers don't need a key)
@@ -331,6 +330,26 @@ cd ~/hermes-workspace && pnpm dev   # terminal 3 · :3000 · the UI
 
 > **Tip:** `pnpm start:all` starts gateway + dashboard + workspace in one shot if you've installed via the one-liner.
 
+### Windows (PowerShell + WSL) one-command startup
+
+If you use Hermes Workspace from Windows with the agent running in WSL, use the helper script in this repo:
+
+```powershell
+# from the repo root
+.\scripts\start-hermes-workspace.ps1
+```
+
+To force a clean relaunch of the tmux session:
+
+```powershell
+.\scripts\start-hermes-workspace.ps1 -Restart
+```
+
+Optional parameters:
+- `-Distro <name>` to target a non-default WSL distro
+- `-WorkspacePath </path/in/wsl>` if your clone is not at `~/hermes-workspace`
+- `-SessionName <name>` to use a custom tmux session name
+
 ### Verify the pairing
 
 ```bash
@@ -388,7 +407,7 @@ The Docker setup runs both the **Hermes Agent gateway** and **Hermes Workspace**
 
 - **Docker**
 - **Docker Compose**
-- **Anthropic API Key** — [Get one here](https://console.anthropic.com/settings/keys) (required for the agent gateway)
+- **A configured Hermes Agent model provider** — run `hermes setup` / `hermes model`, or provide a key for whichever provider you use. This workspace does not require Anthropic.
 
 ### Step 1: Configure Environment
 
@@ -402,8 +421,7 @@ Edit `.env` and add **at least one** LLM provider key — whichever provider you
 
 ```env
 # Pick one (or more). You do NOT need all of these.
-# ANTHROPIC_API_KEY=***         # Anthropic
-# OPENAI_API_KEY=sk-...                # GPT / o-series
+# OPENAI_API_KEY=sk-...                # GPT / o-series / OpenAI-compatible
 # OPENROUTER_API_KEY=sk-or-v1-...      # OpenRouter (free models available)
 # GOOGLE_API_KEY=AIza...               # Gemini
 ```
@@ -654,7 +672,7 @@ Verify: `curl http://localhost:8642/health` should return `{"status": "ok"}`.
 
 v2+ runs on vanilla `hermes-agent`. **No fork required.** The upstream ships every endpoint the workspace needs for chat, sessions, memory, skills, config, jobs, MCP, terminal, and Agent View.
 
-**One known exception:** **Conductor** uses a dashboard plugin that hasn't landed upstream yet. When the workspace detects the missing endpoint, the Conductor screen shows a clear "Upstream not ready" placeholder with a link to [issue #262](https://github.com/outsourc-e/hermes-workspace/issues/262) instead of failing mid-action. Everything else works.
+**Conductor note:** when the dashboard mission API is available, Workspace uses it directly. When that endpoint is absent, Workspace uses its native Swarm fallback and returns `mode: native-swarm`. The fallback dispatches through Workspace Swarm workers, keeps status available through `/api/conductor-spawn?missionId=...`, and cancels through `/api/conductor-stop`.
 
 If you're pinned to an older `hermes-agent` version and missing core endpoints, the workspace will degrade gracefully to **portable mode** with basic chat — upgrade upstream to restore full features.
 
@@ -666,7 +684,7 @@ If using Docker Compose and getting auth errors:
 
    ```bash
    grep -E '_API_KEY' .env
-   # Should show one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, GOOGLE_API_KEY, ...
+   # Should show one of: OPENAI_API_KEY, OPENROUTER_API_KEY, GOOGLE_API_KEY, or another provider key you intentionally use.
    ```
 
    (hermes-agent reads whichever key matches the provider configured in `~/.hermes/config.yaml`.)
@@ -729,13 +747,13 @@ The Docker setup runs both automatically — no action needed if using `docker c
 | Mobile PWA + Tailscale | Install as native-feeling app on any device |
 | Themes | Hermes / Nous / Bronze / Slate / Mono (light + dark) |
 | Capability gates | Graceful 'upstream not ready' placeholders |
-| Multi-provider | Anthropic, OpenAI, OpenRouter, Google, Ollama, LM Studio, vLLM, Atomic Chat |
+| Multi-provider | OpenAI/OpenAI-compatible, OpenRouter, Google, Ollama, LM Studio, vLLM, Atomic Chat, and other Hermes-supported providers |
 
 ### In progress 🔨
 
 | Feature | Status |
 |---|---|
-| Conductor missions | Workspace UI is shipped; awaiting upstream dashboard plugin (see [#262](https://github.com/outsourc-e/hermes-workspace/issues/262)) |
+| Conductor missions | Workspace UI is shipped; uses dashboard mission API when available and Workspace-native Swarm fallback otherwise (see [#262](https://github.com/outsourc-e/hermes-workspace/issues/262)) |
 | Native Desktop App (Electron) | Spec'd; PWA install path works today |
 
 ### Coming 🔜

agents/builder/README.md

@@ -0,0 +1,19 @@
+# Builder
+
+Profile: `builder`
+Wrapper: `builder:task`
+Modes: task
+
+## Tools
+terminal, file, browser, web, gbrain, session_search, skills, todo
+
+## Skills
+builder-core, gstack-for-hermes, test-driven-development, systematic-debugging, github-pr-workflow, requesting-code-review, codebase-inspection
+
+## MCP servers
+gbrain
+
+## Plugins
+none
+
+This file mirrors `swarm.yaml` and the profile config under `~/.hermes/profiles/builder/`.

agents/inbox-triage/README.md

@@ -0,0 +1,19 @@
+# Inbox Triage
+
+Profile: `inbox-triage`
+Wrapper: `inbox:triage`
+Modes: triage
+
+## Tools
+gbrain, web, file, session_search, todo, skills, terminal
+
+## Skills
+inbox-triage-core, gbrain, obsidian-markdown, gstack-for-hermes, defuddle, youtube-content
+
+## MCP servers
+gbrain
+
+## Plugins
+none
+
+This file mirrors `swarm.yaml` and the profile config under `~/.hermes/profiles/inbox-triage/`.

agents/km-agent/README.md

@@ -0,0 +1,19 @@
+# KM Agent
+
+Profile: `km-agent`
+Wrapper: `km:health`
+Modes: health, curate
+
+## Tools
+gbrain, file, terminal, session_search, skills, todo, cronjob, web
+
+## Skills
+km-agent-core, gbrain, obsidian-markdown, obsidian-cli, obsidian-bases, json-canvas, gstack-for-hermes
+
+## MCP servers
+gbrain
+
+## Plugins
+none
+
+This file mirrors `swarm.yaml` and the profile config under `~/.hermes/profiles/km-agent/`.

agents/maintainer/README.md

@@ -0,0 +1,19 @@
+# Maintainer
+
+Profile: `maintainer`
+Wrapper: `maintainer:check`
+Modes: check
+
+## Tools
+terminal, file, web, browser, gbrain, session_search, skills
+
+## Skills
+maintainer-core, github-repo-management, github-pr-workflow, github-issues, github-code-review, gbrain, gstack-for-hermes, hermes-agent
+
+## MCP servers
+gbrain
+
+## Plugins
+none
+
+This file mirrors `swarm.yaml` and the profile config under `~/.hermes/profiles/maintainer/`.

agents/ops-watch/README.md

@@ -0,0 +1,19 @@
+# Ops Watch
+
+Profile: `ops-watch`
+Wrapper: `ops:health`
+Modes: health
+
+## Tools
+terminal, cronjob, file, gbrain, skills, session_search, web
+
+## Skills
+ops-watch-core, gbrain, hermes-agent, systematic-debugging, webhook-subscriptions
+
+## MCP servers
+gbrain
+
+## Plugins
+none
+
+This file mirrors `swarm.yaml` and the profile config under `~/.hermes/profiles/ops-watch/`.