getdevintern · danii1 · Aug 26, 2026 · Aug 26, 2026
diff --git a/docs/code/configuration.md b/docs/code/configuration.md
@@ -85,7 +85,7 @@ You can also pass file paths directly as arguments without setting `TASK_TRACKER
 
 **Personal / interactive:** a `GITHUB_TOKEN` (personal access token). That is enough for free CLI use from your terminal (`devintern TICKET-123`, `--create-pr`).
 
-**Team / unattended automation:** a GitHub App (`GITHUB_APP_ID` plus a private key). That is what `@mention` matching, `devintern worker --listen` / webhooks, and `slug[bot]` commit attribution need so the bot has a shared team identity. Unattended runs also need a `LICENSE_KEY`. See [Pricing](https://devintern.com/pricing/).
+**Team / unattended automation:** a GitHub App (`GITHUB_APP_ID` plus a private key). That is what `@mention` matching, `devintern webhook serve`, and `slug[bot]` commit attribution need so the bot has a shared team identity. Unattended runs also need a `LICENSE_KEY`. See [Pricing](https://devintern.com/pricing/).
 
 The two credentials are complementary, not drop-in replacements. A team setup that also uses GitHub Issues as the tracker still needs `GITHUB_TOKEN`.
 
@@ -102,7 +102,7 @@ Set both when you run mention-driven automation and also use GitHub Issues as a
 **Precedence when both are set:**
 
 - CLI and PR creation use `GITHUB_TOKEN`
-- `devintern worker --listen` and the webhook server prefer the App so the bot identity (`slug[bot]`) resolves
+- `devintern webhook serve` prefers the App so the bot identity (`slug[bot]`) resolves
 
 Do not set `GITHUB_APP_ID` without `GITHUB_APP_PRIVATE_KEY_PATH` or `GITHUB_APP_PRIVATE_KEY_BASE64`. The ID alone is ignored for auth, but the worker treats it as "GitHub credentials present."
 
@@ -120,7 +120,7 @@ GITHUB_TOKEN=your-github-token
 
 ### GitHub App Authentication
 
-For team / unattended automation (`@mention` matching, webhook / `worker --listen`, `slug[bot]` commit attribution):
+For team / unattended automation (`@mention` matching, `webhook serve`, `slug[bot]` commit attribution):
 
 ```bash
 GITHUB_APP_ID=123456

diff --git a/docs/code/github-integration.md b/docs/code/github-integration.md
@@ -433,17 +433,17 @@ export WEBHOOK_DEBUG="true"       # Verbose request/processing logging
 
 ### Start the Server
 
-`devintern worker --listen` runs the webhook listener inside the worker daemon. The previous `devintern serve` command still works as a deprecated alias.
+`devintern webhook serve` runs the advanced repo-local webhook listener. Keep it separate from the workspace worker so webhook delivery and tracker automation can be operated independently. The old `devintern worker --listen` combined mode and `devintern serve` alias remain temporarily available with deprecation warnings.
 
 ```bash
 # Development
 bun run src/webhook-server.ts
 
 # Production (after build)
-devintern worker --listen --port 3000
+devintern webhook serve --port 3000
 
 # With PM2 (process manager)
-pm2 start "devintern worker --listen" --name devintern-webhooks
+pm2 start "devintern webhook serve" --name devintern-webhooks
 ```
 
 ### Systemd Service (Linux)
@@ -467,7 +467,7 @@ Environment=WEBHOOK_SECRET=your-secret
 Environment=GITHUB_TOKEN=ghp_...
 Environment=WEBHOOK_AUTO_REPLY=true
 Environment=WEBHOOK_AUTO_REVIEW=true
-ExecStart=/usr/local/bin/devintern worker --listen --port 3000
+ExecStart=/usr/local/bin/devintern webhook serve --port 3000
 Restart=always
 RestartSec=10
 
@@ -537,7 +537,7 @@ curl https://webhooks.yourdomain.com/health
 Run with verbose logging:
 
 ```bash
-WEBHOOK_DEBUG=true devintern worker --listen
+WEBHOOK_DEBUG=true devintern webhook serve
 ```
 
 ---
@@ -577,7 +577,7 @@ export LICENSE_KEY="your-server-automation-key"
 export GITHUB_TOKEN="ghp_..."   # or GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY_PATH
 
 # 4. Start server
-devintern worker --listen &
+devintern webhook serve &
 
 # 5. Start tunnel
 cloudflared tunnel run devintern-webhooks

diff --git a/docs/code/worker.md b/docs/code/worker.md
@@ -21,7 +21,7 @@ devintern worker init
 devintern worker
 ```
 
-`worker init` reuses tracker config from `devintern init` (or runs that subset if missing), writes a 1-repo [workspace](./workspaces.md), validates and stores the ready-tasks query, checks any automation license (Supporter or Team/Business), offers zero-port relay setup, and can generate a native user service for Linux or macOS. Polling is always on. `--listen` (direct webhooks) is an advanced path, not part of this wizard.
+`worker init` reuses tracker config from `devintern init` (or runs that subset if missing), writes a 1-repo [workspace](./workspaces.md), validates and stores the ready-tasks query, checks any automation license (Supporter or Team/Business), offers zero-port relay setup, and can generate a native user service for Linux or macOS. Polling is always on. The repo-local direct webhook server is an advanced, separate service and is not part of this wizard.
 
 Or configure by hand and start directly:
 
@@ -32,11 +32,11 @@ devintern worker
 # Override the workspace query for this process
 devintern worker --query "status=todo"
 
-# Also run the GitHub webhook listener (direct webhooks; single-repo)
-devintern worker --query "status=todo" --listen --no-workspace
+# Advanced: run the repo-local GitHub webhook listener separately
+devintern webhook serve
 ```
 
-`devintern serve` still works as a deprecated alias for `devintern worker --listen`.
+`devintern worker --listen` preserves the old combined single-repo process for compatibility, but is deprecated. Run the workspace worker and `devintern webhook serve` as separate processes instead. `devintern serve` remains a deprecated alias for `devintern webhook serve`.
 
 ## Recurring automations
 
@@ -155,9 +155,9 @@ The worker log is the diagnostic. Look for `[poll:<tracker>]` (for Jira, `[poll:
 | Option              | Description                                                         |
 | ------------------- | ------------------------------------------------------------------- |
 | `--query <query>`   | Poll the tracker for ready tasks matching this query                |
-| `--listen`          | Also run the GitHub webhook listener (direct webhooks)              |
-| `--port <port>`     | Webhook listener port (default: 3000 or `WEBHOOK_PORT`)             |
-| `--host <host>`     | Webhook listener host (default: 0.0.0.0 or `WEBHOOK_HOST`)          |
+| `--listen`          | Deprecated combined repo-local webhook listener                    |
+| `--port <port>`     | Deprecated listener port used only with `--listen`                 |
+| `--host <host>`     | Deprecated listener host used only with `--listen`                 |
 | `--interval <secs>` | Polling interval in seconds (default: 60 or `WORKER_POLL_INTERVAL`) |
 | `--ui`              | Serve the local [observability dashboard](./dashboard.md) (default) |
 | `--no-ui`           | Disable the dashboard for this worker process                        |
@@ -173,7 +173,7 @@ In polling mode the worker also watches the pull requests it created (no webhook
 
 The watch list is scoped to the project the worker runs in: single-repo mode watches only PRs on that checkout's GitHub repo, and workspace mode only repos listed in `workspace.toml`. Registry entries for any other repo — typically left behind when a repository is renamed or transferred, or by an older checkout sharing the same `.devintern-code/` state — are unwatched automatically at startup instead of being polled (and failing auth) forever.
 
-The regular polling requests use ETags, and GitHub does not count `304 Not Modified` responses against the API rate limit. The worker makes unconditional PR requests only once to hydrate state after startup and immediately before an eligible base-sync attempt. Comparison results are reused for each immutable base/head SHA pair. With `--listen`, review handling comes from webhooks instead and this poller stays off, so feedback is never handled twice.
+The regular polling requests use ETags, and GitHub does not count `304 Not Modified` responses against the API rate limit. The worker makes unconditional PR requests only once to hydrate state after startup and immediately before an eligible base-sync attempt. Comparison results are reused for each immutable base/head SHA pair. The deprecated combined `--listen` mode disables this poller so feedback is never handled twice.
 
 ### Merge conflicts on the agent's PRs
 

diff --git a/docs/code/workspaces.md b/docs/code/workspaces.md
@@ -119,7 +119,7 @@ devintern worker --workspace /path/to/workspace.toml
 devintern worker --no-workspace   # force single-repo mode in the current repo
 ```
 
-The fleet query comes from `[defaults].task_query`, or `--query` / `WORKER_TASK_QUERY` to override. A workspace with automations can omit the query and run as an automation-only worker. `--listen` (direct webhooks) is single-repo and cannot be combined with workspace mode. Workspace and automation configuration is loaded at startup; restart the worker after editing it. Schedule state and leases for automations live in the central workspace database.
+The fleet query comes from `[defaults].task_query`, or `--query` / `WORKER_TASK_QUERY` to override. A workspace with automations can omit the query and run as an automation-only worker. Direct webhooks are an advanced repo-local service: run `devintern webhook serve` from that repository as a separate process. Workspace and automation configuration is loaded at startup; restart the worker after editing it. Schedule state and leases for automations live in the central workspace database.
 
 `devintern worker init` can generate a user-level systemd unit on Linux or launchd agent on macOS. One service runs the whole workspace. For a hand-written Linux unit:
 

diff --git a/packages/code/CHANGELOG.md b/packages/code/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 - **`devintern worker init` is the complete unattended setup**: the wizard reuses tracker config from `devintern init` (or runs that subset), imports the current repo into `~/.devintern/workspace.toml` as a 1-repo workspace, dry-runs the ready-tasks query into `[defaults].task_query`, checks any automation license, offers zero-port relay pairing, and generates a user-level systemd unit or macOS launchd agent. It no longer asks about `--listen` or writes worker env vars
 - **Worker dashboard is on by default**: `devintern worker` serves localhost:4400 unless `--no-ui` is passed; dashboard startup failures no longer stop task processing
+- **Direct webhooks have a dedicated command**: `devintern webhook serve` is the canonical advanced repo-local listener. `devintern worker --listen` keeps its legacy combined behavior for compatibility but is deprecated, and `devintern serve` is now a deprecated alias for the dedicated command
 
 ### Fixed