Merge pull request #741: feat(discord): two-way Discord bridge with a thread per tab

docs/api-reference.md

@@ -1523,6 +1523,19 @@ Posts the Web Push events to ntfy, Slack, Discord or a generic JSON URL (Setting
 
 Delivery goes through the same egress guard as web tabs (refused on the resolved address too), does not follow redirects, times out after 5 s, sends the same event for the same session at most once per 3 s, and has at most 5 requests in flight. Error text never contains the URL.
 
+## Discord bridge
+
+One thread per tab in a private Discord channel, alerts out and replies typed back in. Setup (bot, least-privilege permissions, IDs) is in [discord-bridge.md](discord-bridge.md). The bot token is a bearer secret: stored in `~/.codeman/discord.json` (0600), never returned, and the three settings routes are admin only in multi-user mode.
+
+| Method | Path | Body | Notes |
+| ------ | ------ | ------ | ------ |
+| `GET` | `/api/discord` | none | Config without the token, plus `hasToken`, `tokenMasked`, `gateway` (`off` \| `connecting` \| `connected` \| `error`), `gatewayError` and `lastResult`. |
+| `PUT` | `/api/discord` | `{ enabled?, token?, guildId?, parentChannelId?, allowedUserIds?, threadCreation?, onSessionDelete?, staleThreads?, pingMode?, scope?, startupHint?, typedHint? }` (strict) | `threadCreation`: `lazy` \| `onSessionStart`. `onSessionDelete`: `keep` \| `archive` \| `delete`. `pingMode`: `off` \| `critical` \| `all`. `scope`: `attention` \| `all`. An absent `token` keeps the saved one; `""` clears it. `400` for a non-numeric id or enabling without a token, guild, channel and at least one allowed user. |
+| `POST` | `/api/discord/test` | none | Posts one message to the parent channel with the saved config, even while disabled. `200` with `data.ok`; `400` if no token or channel is saved. |
+| `POST` | `/api/sessions/:id/discord-notify` | `{ message, urgent?, file? }` (strict, message 1 to 1500 characters) | A CLI asks for the user: posts into that tab's thread, pinging when `urgent`. `file` is an absolute path inside the tab's working folder (real path, regular file, at most 8 MB, local sessions only) uploaded with the post; `400` otherwise. A `200` carries the delivery result: `data.ok` is `false` (with `data.error`) when Discord refused or failed the post. `409` while the bridge is disabled, `429` past 6 posts a minute per tab. The `codeman notify "message" [--urgent] [--file path]` command wraps this route. |
+
+Only replies from `allowedUserIds`, in `guildId`, inside a thread the bridge created are typed into a session, as one printable line plus Enter (a lone digit while a permission or question is pending goes as the key alone), at most one per second per tab. Attached files are saved under `.codeman-discord/` in the tab's folder and their paths appended to that line (see [discord-bridge.md](discord-bridge.md)).
+
 ## Diagnostics
 
 `GET /api/doctor[?category=core|office|other]` returns the `codeman doctor --json` report (`platform`, `summary`, `tools[]` with `status` `ok` \| `missing` \| `outdated` \| `skipped` \| `error`, `version`, `path`, `installHint`). The probe engine is synchronous, so it runs in a child process of the same entry script, never on the server's event loop (30 s timeout). It names install paths and versions, so it is admin only in multi-user mode (`403`). `400` for an unknown category, `500` if the child produces no report.

docs/architecture-invariants.md

@@ -1372,3 +1372,16 @@ refuses them (`GuardedInputBusyError`, which `send-key` answers as `409 CONFLICT
 not edits. Never retry ambiguous Enter delivery or clear an unverified composer.
 The ordinary SubmitVerifier uses the shared write boundary, so each re-press
 updates `lastSubmitAt` just like any other Enter.
+
+## Discord bridge
+
+`src/discord-bridge.ts`, `src/web/routes/discord-routes.ts`, `src/cli-notify.ts`. Opt-in, two-way, one thread per tab. User docs: [discord-bridge](discord-bridge.md).
+
+- **Who can type into a tab.** Only `allowedUserIds`, in `guildId`, inside a thread the bridge created. Everything else is dropped unread. A reply is one printable line plus Enter (a lone digit while a permission or question is pending goes as the key alone, since the dialog acts on it), capped and rate limited, and typed with `fromUser: true`. The bridge's own startup hint is typed with `fromUser: false`.
+- **A Discord failure never reaches a session.** `notify()` never throws; a failed thread creation is returned by `threadFor` as a `DiscordResult`, not read back from shared state.
+- **`null` means the bridge is off.** A deduped automatic event answers `{ ok: true, deduped: true }`; a deliberate `codeman notify` is never deduped. A 200 from `discord-notify` carries the delivery result in `data.ok`, and `codeman notify` exits 1 when it is false.
+- **Threads belong to a parent channel.** `discord-bridge.json` is `{ parentChannelId, threads }`; `reload()` drops the map when the channel changes, and a creation that finishes after the change is discarded.
+- **Deletes come from the cleanup path** (`killMux` true), never from `session:deleted`, which a detach also fires.
+- **Files.** Received files come only from Discord's HTTPS hosts into `<tab folder>/.codeman-discord/` (bounded probe, refused if a symlink, self-ignoring). A sent file's real path must lie inside the tab's folder; both the folder and the file are probed with the bounded probe first.
+- **The whole last message.** A finished turn or an error posts the CLI's whole last message, not the screen: `WebServer.lastResponseFor` is the response viewer's reader (the body of `GET /api/sessions/:id/last-response`, registered on the route context by `registerSessionRoutes`), so the source is the same per-CLI transcript, or the pane split into turns where a CLI keeps none; a dialog and a shell keep the screen tail (its composer row and the status lines under it cut, never a `❯ 1.` option row). The read is bounded to 4 s and any failure or empty read falls back to the screen. It is split into at most 8 posts of 1,900 characters, a cut code fence closed and reopened, and Markdown tables become aligned code blocks (the separator test strips whitespace first: a regex over a run of spaces is quadratic, and the text is steerable by whatever the agent read). The repeat check is keyed on the text plus the turn it came from (the transcript stamp, else the last submit) and is recorded only after the first post succeeds, so a failed post is sent again and a later turn ending on the same words is not dropped. Only some CLIs raise a turn end (`/api/hook-event`: Claude's `stop` and `idle_prompt`, DeepSeek's `stop`), so the others reach this path through errors, a blocked respawn or a crash loop.
+- **Cost guards.** The alert tail is a function called only once a post will happen (no tmux exec while off), and `discord-notify` is a per-session token bucket (6 a minute, `429 RATE_LIMITED`).

docs/discord-bridge.md

@@ -0,0 +1,138 @@
+# Discord bridge
+
+Codeman can post to a private Discord server when a session needs you, give every tab its own thread, and type your thread reply into that tab. It only makes outbound connections, so Codeman is not exposed to the internet and it works when you are away from your network.
+
+> [!WARNING]
+> A reply from an allowed Discord account is typed into agents that can run shell commands. Treat that Discord account like a login to the machine: turn on 2FA and use a strong, unique password.
+
+## What it does
+
+- Posts when a session asks for permission, asks a question, goes idle or errors. Which of these a CLI can raise depends on the hooks it has: Claude Code sends a turn end (`stop`, an `info` event that posts only when **Which events** is set to Everything, and `idle_prompt`, which posts by default after the turn has waited a minute). DeepSeek Harness sends only `stop`. Codex, OMP, OpenCode, Gemini, Antigravity, Pi, Grok and Copilot send no turn end, so they reach Discord through an error, a blocked respawn, a stopped crash loop or their own `codeman notify`; Codex's permission and question dialogs are also read off its screen.
+- Posts a finished turn, and an error or blocked alert, as the CLI's whole last message, with its bold, lists and numbered questions kept (a Markdown table, which Discord cannot draw, becomes an aligned code block), split over several posts if it is long. It reads the CLI's transcript where it keeps one (Claude Code, Codex, DeepSeek Harness, OMP) and otherwise splits the screen into turns (OpenCode, Gemini, Antigravity, Pi, Grok, Copilot), which can start mid-message when a long answer has scrolled off. A shell, and a permission or question dialog, show the last lines of the screen instead, without the prompt row and status lines under them.
+- Creates one thread per tab in a single parent channel, so a reply always reaches exactly one session.
+- Types your reply into that session as a single line followed by Enter. A single digit sent while a permission or question is waiting goes as the key alone, without Enter, because the dialog acts on the keypress.
+- Lets a CLI post a deliberate message (for example "press the reset button on the case") with the `codeman notify` command, which calls `POST /api/sessions/:id/discord-notify`. Each tab may post 6 a minute; past that the command says "too many messages", so a looping agent cannot ping your phone without end.
+- Saves files you attach in a thread into that tab's working folder and tells the CLI the path. A CLI can send a file back with `codeman notify "message" --file <path>`.
+- Tells each CLI about `codeman notify` (see [Telling the CLIs](#telling-the-clis)).
+
+## Setup
+
+Do these once, in order. Never paste the bot token into a chat or a session.
+
+### 1. Create a private server
+
+1. In Discord choose **Add a Server**, **Create My Own**, **For me and my friends**.
+2. Invite nobody and create no invite links.
+3. Create one text channel, for example `#codeman-cli`.
+
+### 2. Copy the IDs
+
+1. Open **User Settings**, **Advanced** and turn on **Developer Mode**.
+2. Right-click the server, the channel and your own avatar, and choose **Copy ID** for each. You need the guild ID, the parent channel ID and your user ID.
+
+### 3. Create the application
+
+1. Go to <https://discord.com/developers/applications> and choose **New Application**.
+2. Name it `Codeman`.
+
+### 4. Configure the bot
+
+On the **Bot** tab:
+
+1. Choose **Reset Token** and copy it. It is shown once.
+2. Turn **Public Bot** off, so nobody else can add it. Discord refuses this while the app has a default install link, so first open the **Installation** tab, set **Install Link** to **None** (untick Guild Install and User Install if it will not save) and save, then come back here.
+3. Leave **Requires OAuth2 Code Grant** off.
+4. Under **Privileged Gateway Intents** turn **Message Content Intent** on. Leave **Server Members Intent** and **Presence Intent** off.
+
+### 5. Invite the bot with minimal permissions
+
+On **OAuth2**, **URL Generator**:
+
+1. Tick the scope `bot` only. Do not tick `applications.commands` or anything else.
+2. Tick only these permissions (Attach Files and Embed Links are optional: without them, files cannot be sent from a CLI and links show no preview):
+
+   | Permission               | Why                                  |
+   | ------------------------ | ------------------------------------ |
+   | View Channels            | See the parent channel               |
+   | Send Messages            | Post in the parent channel           |
+   | Send Messages in Threads | Post in each tab's thread            |
+   | Create Public Threads    | Make a thread per tab                |
+   | Read Message History     | Read your replies                    |
+   | Add Reactions            | Acknowledge a reply that was typed   |
+   | Attach Files             | Send a file from a CLI to the thread |
+   | Embed Links              | Show previews for links in posts     |
+
+3. Open the generated URL, choose your private server and authorise.
+4. Check the **Installation** tab still shows **Install Link: None**, so there is no public way to add the bot.
+
+The ticked boxes are the source of truth. As a cross-check, these eight permissions add up to the permissions integer `309237763136`.
+
+### 6. Optional: allow deleting threads
+
+Only needed for `onSessionDelete: delete`. Give the bot role **Manage Threads** on the parent channel only, as a channel permission override and not server-wide. Skip this if you are happy to keep or archive threads.
+
+### 7. Never grant
+
+Administrator, Manage Channels, Manage Roles, Manage Messages, Mention Everyone, or any voice permission.
+
+### 8. Configure Codeman
+
+1. Open **Settings**, **Notifications**, then the **Discord** group.
+2. Enter the bot token, guild ID, parent channel ID and your user ID in the allowlist.
+3. Choose the options below and press **Send test**. A test message should appear in the channel.
+
+The token is stored in `~/.codeman/discord.json` with mode 0600. It is never returned by the API, written to logs or sent over SSE.
+
+### 9. Phone alerts
+
+In the Discord mobile app set the server to **All Messages**. Discord's own push notification is what reaches you off-network.
+
+## Options
+
+| Option            | Values                      | Default     | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ----------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `threadCreation`  | `lazy`, `onSessionStart`    | `lazy`      | `lazy` makes a thread on the first notification. `onSessionStart` makes one per new tab                                                                                                                                                                                                                                                                                                                                                           |
+| `onSessionDelete` | `keep`, `archive`, `delete` | `archive`   | What happens to the thread when its tab is deleted. `delete` needs Manage Threads                                                                                                                                                                                                                                                                                                                                                                 |
+| `staleThreads`    | `keep`, `archive`, `delete` | `keep`      | What happens to threads this bot made that no tab uses any more, checked after startup and then daily. A deleted tab's thread leaves the map, so this also archives or deletes threads that `onSessionDelete` kept or archived. Skips threads under an hour old, other people's threads and other channels, does nothing while the thread map is empty, and closes at most 25 per run. `delete` needs Manage Threads. Use one channel per Codeman |
+| `pingMode`        | `off`, `critical`, `all`    | `critical`  | `critical` pings you for permission prompts, questions, errors and urgent posts                                                                                                                                                                                                                                                                                                                                                                   |
+| `scope`           | `attention`, `all`          | `attention` | `attention` skips the quiet "response complete" event. `all` sends it too                                                                                                                                                                                                                                                                                                                                                                         |
+| `startupHint`     | on, off                     | on          | Tell Claude about `codeman notify` in its system prompt at launch                                                                                                                                                                                                                                                                                                                                                                                 |
+| `typedHint`       | on, off                     | off         | Also send the note once, as a first message, to brand-new non-Claude CLI tabs                                                                                                                                                                                                                                                                                                                                                                     |
+
+## Telling the CLIs
+
+A CLI only posts deliberately if it knows it can. While the bridge is on:
+
+- **Claude** (`startupHint`, on by default) is launched with `--append-system-prompt`, so nothing shows in the conversation. This reaches local tabs only: remote (ssh) and Docker launches are built outside the CLI registry, and have no `codeman` command anyway.
+- **Every other CLI** is sent nothing unless you turn on `typedHint` (off by default: it costs one model turn per tab, and for a spawned worker or a scheduled run it arrives together with the first real prompt). With it on, the same text is sent once, as a message, the first time a brand-new tab becomes idle. Tabs that are restored when Codeman starts, shell tabs, and remote (ssh) and Docker tabs (which have no `codeman` command) are never sent it.
+
+The text explains `codeman notify "message" --urgent`. `codeman` is on the PATH of every session from the installer or an npm install (a git checkout run without the installer has no `codeman` command) and reads `CODEMAN_SESSION_ID` and `CODEMAN_API_URL`, so no other setup is needed. Without a bridge it prints that the bridge is off and exits cleanly. Tabs started before the bridge was enabled are not told; use the skill or `CLAUDE.md` for those.
+
+## Files
+
+- **Received:** files you attach to a reply from an allowed user are saved as `<working folder>/.codeman-discord/<message id>-<name>` (mode 0600) and the one-line reply the CLI sees ends with `[attached: <paths>]`. At most 5 files of 8 MB each; names are reduced to letters, digits, `.`, `_` and `-`; only Discord's own HTTPS addresses are fetched. Anything skipped is named in the thread. The folder ignores itself (it holds a `.gitignore` of `*`), so nothing in it is committed. Remote (ssh) tabs have no local folder, so no file is saved for them.
+- **Sent:** `codeman notify "message" --file <path>` uploads a regular file of at most 8 MB. The real path (symlinks followed) must be inside the tab's working folder, which stops an upload of something outside it by mistake. The agent runs as your user, so this is a guard against accidents, not a sandbox. Remote tabs cannot send files.
+- A downloaded file is untrusted content: only allowed users can send one, but a CLI that opens it is exposed to anything written inside it.
+
+## Security model
+
+- Only messages from IDs in `allowedUserIds`, in the configured guild, inside a thread Codeman created, are acted on. Everything else is dropped.
+- A reply is reduced to one line, stripped of control characters and capped in length before it is typed.
+- Replies are rate limited per session.
+- A Discord outage or a bad token never affects sessions. The bridge backs off, and the last error shows in Settings.
+
+## Rotating and revoking
+
+- **Rotate:** in the Developer Portal choose **Bot**, **Reset Token**, paste the new token into Codeman and press **Send test**.
+- **Revoke:** kick the bot from the server or delete the application, then choose **Remove token** in Settings. Deleting `~/.codeman/discord.json` alone does not reach a running bridge, which keeps the token it loaded until Codeman restarts.
+- If the token is ever pasted somewhere it should not be, reset it straight away.
+
+## Troubleshooting
+
+| Symptom                             | Check                                                                    |
+| ----------------------------------- | ------------------------------------------------------------------------ |
+| Test fails with 401                 | The token is wrong or was reset. Paste the current one                   |
+| Test fails with 403 or 50001        | The bot cannot see the parent channel. Check the role and the channel ID |
+| Posts arrive but replies do nothing | Message Content Intent is off, or your user ID is not in the allowlist   |
+| Thread is not deleted               | The bot lacks Manage Threads on the parent channel                       |
+| Nothing arrives on the phone        | Check the Discord app's notification setting for the server              |

docs/security-architecture.md

@@ -582,6 +582,7 @@ Opt-in and off by default: the server POSTs the Web Push events (permission prom
 
 - **A second server-side outbound channel through the web-tab egress guard (§10b).** Delivery goes through `webviewFetch`, so link-local and cloud-metadata targets are refused at save time and again on the RESOLVED address at connect time; redirects are not followed (`redirect: 'manual'`) and each send is bounded by a 5 s timeout. Loopback and RFC1918 stay allowed on purpose (a self-hosted ntfy is the point), so **Send test** works as a blind reachability probe (status, refused or timed out, never a response body) for whoever may call it. Web tabs already give that caller full LAN reach with bodies, so nothing new is exposed.
 - **The URL is a bearer secret** (anyone holding a Slack or Discord webhook URL can post as it). It lives in `~/.codeman/webhook.json` (0600, tmp+rename), is kept out of `settings.json` (which every logged-in user reads through `GET /api/settings`), is never returned (`GET /api/webhook` gives scheme + host only), and never appears in a log line, a delivery result or an error message.
+- **Discord bridge** (`src/discord-bridge.ts`, [setup](discord-bridge.md)): the bot token lives in `~/.codeman/discord.json` (0600, tmp+rename) and is never returned, logged or put in an error. Inbound replies are typed into a session only from `allowedUserIds`, in the configured guild, inside a thread the bridge created; anything else is dropped unread. A reply becomes one printable line plus Enter, capped at 1000 characters and one per second per tab. Posts send `allowed_mentions` limited to the allowlisted ids, so agent output cannot ping a server. **Files:** an attachment is fetched only from Discord's own HTTPS hosts (no redirects followed), at most 5 per reply and 8 MB each, saved 0600 under `<tab folder>/.codeman-discord/` with the name reduced to `[A-Za-z0-9._-]`; a file a CLI sends must be a regular file whose real path (symlinks followed) lies inside its own tab's folder, which stops a file outside that folder being uploaded by mistake, and remote sessions send and receive none. A received file is untrusted content to whatever opens it. **What the checks do not stop:** the agent runs as the same OS user, so the path check prevents accidental uploads, not a determined agent that pastes a file's contents into the message. **What leaves the machine:** a permission or question alert sends the rendered screen (whatever the agent printed), and a finished turn or an error sends the CLI's whole last message, read from its transcript (up to 8 posts of 1,900 characters). `idle_prompt` is a warning, so with the default scope every Claude turn left unanswered for a minute is posted, and with **Which events** set to Everything every turn end is; treat the Discord server as holding that output. **Multi-user:** the bridge is one allowlist for the whole server, so an allowlisted Discord account can type into every user's sessions; only an admin can configure it. **Startup hint:** a fixed text (no user input) is added to Claude's system prompt, or, only when `typedHint` is on, typed once to a brand-new external CLI tab, never to a shell. The bridge only dials out (REST and the gateway WebSocket), so it needs no inbound exposure. A Discord account on the allowlist can drive agents that run shell commands: it needs 2FA.
 - **It carries session data to a third party.** Titles and bodies include session names, tool names and error text, all agent- or user-controlled, so Discord gets `allowed_mentions: { parse: [] }` and Slack's `& < >` are escaped: agent output cannot ping a channel. In multi-user mode all three routes are admin-only and the channel is instance-wide: it receives every user's session events, the same reach an admin's own Web Push has, which means non-admins' session details leave the box at the admin's choice.
 
 ---

docs/wiki/Config-Backups.md

@@ -15,6 +15,7 @@ A fixed list of files from the data directory (`~/.codeman/`, or the directory o
 | `clis.json` | CLI enable/disable and custom CLI entries. |
 | `custom-model-hosts.json` | Saved custom model endpoints. **Holds API keys.** |
 | `webhook.json` | Webhook notification target. |
+| `discord.json` | Discord bridge settings. **Holds a bot token.** |
 | `intents.json` | Read My Mind per-case profiles. |
 | `linked-cases.json` | Registered cases. |
 | `remote-hosts.json`, `remote-cases.json`, `docker-hosts.json`, `docker-cases.json` | Remote SSH and Docker overlay configuration. |
@@ -188,15 +189,15 @@ that are the same are listed on one line. A file that is not JSON shows only tha
 a file with more than 200 changes is cut short, so use the files themselves for a full diff. The
 self-rewritten fields listed under "When a backup is made" are not counted as changes.
 
-**Credential values are never shown.** `.env`, `users.json`, `push-keys.json`, `webhook.json` (the
-URL is a bearer secret) and `intents.json` (captured prompts) list only the names that changed, and in every other file a key that looks like a token, secret, password,
+**Credential values are never shown.** `.env`, `users.json`, `push-keys.json`, `webhook.json` (the URL is a bearer secret), `discord.json` (the
+bot token) and `intents.json` (captured prompts) list only the names that changed, and in every other file a key that looks like a token, secret, password,
 credential or key is shown as "changed" without its value. URL values lose any `user:password@`,
 query and fragment.
 
 ## Security
 
 - Some tracked files carry credentials (`.env`, `users.json`, `custom-model-hosts.json`,
-  `push-keys.json`, `webhook.json`). Each backup folder is mode `0700` and its files `0600`, so the default
+  `push-keys.json`, `webhook.json`, `discord.json`). Each backup folder is mode `0700` and its files `0600`, so the default
   location exposes nothing the data directory does not already.
 - **A custom folder is your decision.** Putting it on a shared drive, a synced folder or a
   network share copies those credentials there, with whatever permissions that location has.

docs/wiki/Discord-Bridge.md

@@ -0,0 +1,107 @@
+# Discord Bridge
+
+Answer a blocked agent from your phone, from anywhere. Codeman posts to a private Discord
+server when a session needs you, gives every tab its own thread, and types your reply in that
+thread into that tab. It only makes outbound connections, so nothing is exposed to the internet
+and it works when you are away from your network.
+
+**Opt-in, off by default. One server, one channel, threads per tab.**
+
+> **Treat the Discord account like a login to the machine.** A reply from an allowed account is
+> typed into agents that can run shell commands. Turn on 2FA and use a strong, unique password.
+
+## What it does
+
+- **Alerts** for permission prompts, questions, idle sessions, errors and a stopped crash loop. A
+  question or permission prompt shows what is on the tab's screen right now, so you can see what is
+  being asked; a finished turn or an error carries the CLI's whole last message.
+- **One thread per tab** in a parent channel, so a reply always reaches exactly one session.
+- **Replies** from an allowed user are typed into that tab as one line plus Enter (a single digit answering a waiting permission or question goes as the key alone, without Enter).
+- **Files** you attach are saved in the tab's folder and the agent is given the path. An agent can
+  send a file back.
+- **Agents can ask for you.** `codeman notify "Press the reset button on the case" --urgent`
+  posts to the tab's thread. Sessions from the installer or an npm install have the command (a git checkout run without the installer does not); see [below](#telling-the-agents).
+
+## Set it up
+
+The full least-privilege walkthrough (private server, bot, the exact permissions, IDs, token
+handling) is in [docs/discord-bridge.md](https://github.com/Ark0N/Codeman/blob/master/docs/discord-bridge.md).
+In short:
+
+1. Make a private Discord server with one text channel, and copy the server, channel and your user IDs.
+2. Create an application with a bot. Turn **Public Bot** off, turn **Message Content Intent** on, and
+   invite it with the `bot` scope and only the permissions the guide lists (no Administrator).
+3. In **App Settings → Notifications → Discord**, paste the bot token and the three IDs, press **Save**,
+   then **Send test**, then turn **Talk to your sessions from Discord** on and **Save** again.
+
+The token is a secret: it is kept in its own file (`~/.codeman/discord.json`, readable by its owner
+only), never in the shared settings, and never shown again once saved.
+
+## Options
+
+| Option                                   | Choices                                     | Default         |
+| ---------------------------------------- | ------------------------------------------- | --------------- |
+| Create threads                           | On the first alert, or for every new tab    | First alert     |
+| When a tab is deleted                    | Keep, archive or delete the thread          | Archive         |
+| Stale threads                            | Keep, archive or delete threads no tab uses | Keep            |
+| @ ping                                   | Never, critical events only, every post     | Critical only   |
+| Which events                             | Needs attention, or everything              | Needs attention |
+| Tell Claude how to reach you             | On or off                                   | On              |
+| Also tell other CLIs, as a first message | On or off                                   | Off             |
+
+A finished turn, and an error, is posted as the CLI's whole last message, with its formatting and questions
+kept, split over several posts if it is long. A shell, and permission or question dialogs, show the last lines
+of the screen instead.
+
+Only some CLIs raise a turn end. Claude Code does (an idle alert by default, and a stop alert when **Which
+events** is Everything), and DeepSeek Harness sends a stop. The others (Codex, OMP, OpenCode, Gemini,
+Antigravity, Pi, Grok, Copilot) send none, so their messages reach Discord with an error or `codeman notify`;
+Codex's dialogs are read off its screen.
+
+The stale-thread setting also archives or deletes threads that **When a tab is deleted** kept or archived, because a
+deleted tab's thread leaves the bridge's map.
+
+Deleting a thread needs the **Manage Threads** permission on the channel. "Critical" means a
+permission prompt, a question, an error, or a post an agent marked urgent.
+
+## Telling the agents
+
+An agent only posts deliberately if it knows it can:
+
+- **Claude** is launched with the instruction as part of its system prompt (**Tell Claude how to reach you**, on by default), so nothing shows in the chat. This reaches local tabs only (remote and Docker tabs have no `codeman` command).
+- **Every other CLI** is told only if you turn on **Also tell other CLIs, as a first message** (off by default: it costs one model turn per tab, and for a spawned worker or a scheduled run it arrives with the first real prompt). Then the same text is sent once, as a message, the first time a brand-new tab goes idle.
+  Restored tabs, shell tabs, and remote (ssh) and Docker tabs (which have no `codeman` command) are never sent it.
+
+Tabs that were already open when you turned the bridge on are not told. The alerts still reach
+Discord for them; only the agent-initiated `codeman notify` habit is missing.
+
+## Files
+
+- **You to the agent:** attach a file to a reply. It is saved as
+  `<tab folder>/.codeman-discord/<message id>-<name>` and the line the agent sees ends with
+  `[attached: <path>]`. At most 5 files of 8 MB each. The folder ignores itself, so nothing in it is committed.
+- **Agent to you:** `codeman notify "message" --file <path>` uploads a file of at most 8 MB that lies
+  inside the tab's folder.
+- Remote (ssh) tabs have no local folder, so they neither send nor receive files.
+- A file you send is untrusted content to the agent that opens it.
+
+## Safety
+
+- Only user IDs on the allowlist, in your server, inside a thread Codeman made, are acted on.
+  Everything else is dropped.
+- A reply is cut to one printable line (1000 characters) and limited to one per second per tab.
+- Posts can ping only the allowlisted users, so agent output cannot ping the whole server.
+- A Discord outage or a bad token never affects a session; it backs off, and the last error shows in Settings.
+
+## Troubleshooting
+
+| Symptom                                          | Check                                                          |
+| ------------------------------------------------ | -------------------------------------------------------------- |
+| Send test says 401                               | The token is wrong or was reset. Paste the current one.        |
+| Send test says the bot cannot see it             | Check the bot's role and the channel ID.                       |
+| Posts arrive but replies do nothing              | Message Content Intent is off, or your user ID is not allowed. |
+| Status line says "Message Content Intent is off" | Turn it on in the Developer Portal, Bot tab.                   |
+| A thread is not deleted                          | The bot lacks Manage Threads on the channel.                   |
+
+See also: [Notifications And Approvals](Notifications-And-Approvals) for the other ways to hear
+from an agent, and [Security](Security) for how secrets are handled.

docs/wiki/Home.md

@@ -79,6 +79,7 @@ codeman web    # then open http://localhost:3000
 | ------------------------------------------------------------- | --------------------------------------------------- |
 | [Keeping Agents Running](Keeping-Agents-Running)              | How does it run unattended overnight?               |
 | [Notifications And Approvals](Notifications-And-Approvals)    | How do I know an agent needs me, and answer from my phone? |
+| [Discord Bridge](Discord-Bridge)                              | How do I answer a blocked agent from Discord, in a thread per tab? |
 | [Cron Jobs](Cron-Jobs)                                        | How do I run an agent on a schedule?                |
 | [Autonomous Loops](Autonomous-Loops)                          | What are the Ralph and Orchestrator loops for?      |
 | [Watching Agents Work](Watching-Agents-Work)                  | How do I see what the subagents are doing?          |

docs/wiki/Notifications-And-Approvals.md

@@ -13,6 +13,7 @@ opening the session.
 | Desktop notification           | Another window on the same machine               | Opt-in  |
 | Push notification              | Anywhere, even with no tab open                  | Opt-in  |
 | Webhook (ntfy, Slack, Discord) | Anywhere, with no browser or subscription at all | Opt-in  |
+| Discord bridge (two-way)       | Anywhere, and you can answer in a thread per tab | Opt-in  |
 | Approvals Inbox                | One queue for Claude, Codex and DeepSeek prompts | Opt-in  |
 | Phone overview                 | Phone home screen, NEEDS YOU section             | On      |
 | Away Digest                    | Afterwards, as a summary                         | Opt-in  |
@@ -66,6 +67,11 @@ Setup:
 
 Once subscribed, a blocking prompt reaches your phone even from a locked screen.
 
+## Discord bridge: answer from your phone
+
+A webhook is one-way. To also **reply** to a blocked agent, use the [Discord Bridge](Discord-Bridge): a
+thread per tab, your reply typed into that tab, files in both directions.
+
 ## Webhooks: ntfy, Slack, Discord
 
 **Opt-in, off by default. One channel for the whole server.**

docs/wiki/Settings-Reference.md

@@ -213,8 +213,9 @@ how long a desktop notification stays up before Codeman closes it (**Browser
 notification display time**, default 8; both per device, and your OS may close a
 desktop notification sooner), the idle
 threshold that decides when a quiet session counts as needing you, and the server-wide
-webhook (ntfy, Slack, Discord or generic JSON; admins only in multi-user mode). See
-[Notifications And Approvals](Notifications-And-Approvals).
+webhook (ntfy, Slack, Discord or generic JSON; admins only in multi-user mode), and the
+Discord group for the two-way bot (token, IDs, thread and ping options; see
+[Discord Bridge](Discord-Bridge)). See [Notifications And Approvals](Notifications-And-Approvals).
 
 ### Voice
 

docs/wiki/_Sidebar.md

@@ -25,6 +25,7 @@
 
 - [Unattended Runs](Keeping-Agents-Running)
 - [Notifications & Approvals](Notifications-And-Approvals)
+- [Discord Bridge](Discord-Bridge)
 - [Cron Jobs](Cron-Jobs)
 - [Autonomous Loops](Autonomous-Loops)
 - [Watching Agents Work](Watching-Agents-Work)