docs: tighten the inbox, push and idle-detection wording

Follow-up to the previous commit, after a fact check against the code. - Answer surfaces: the header bell answers Claude prompts, the phone strip only Claude dialogs (and only with the inbox on), and push Approve/Deny only a Claude permission prompt (PUSH_EVENT_MAP gives actions to permission_prompt alone). README, its Chinese mirror, the notifications page and the phone guide now say so. - Antigravity and Grok Build: after the 3 s launch settle, idle is armed only by Claude's prompt marker and working only by a braille spinner, so "idle when output stops changing" was wrong. The wiki, the grok guide and the API reference now call their status unreliable. - DeepSeek Harness: its idle and working reports become stop and agent_working, which drive respawn, waits and the inbox but not the session's own working/idle display. Keeping Agents Running says that, and that the respawn path needs the status bridge. - The wait section of the API reference no longer calls exit the only dependable signal for screen-checked modes; the inbox page names how Codex and DeepSeek items clear; Core Concepts and Hooks And Integrations no longer call DeepSeek "the one" exception; Agent CLIs notes that Codex dialogs still raise the red alert; the inbox design doc notes the alert-only items. - Skill: stop and blocked list deepseek, and SKILL.md no longer says codex has neither a transcript nor blocked. Mirrored with scripts/sync-plugin.mjs. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-20 09:09:35 +02:00 · 2026-10-17 18:28:03 +02:00
1 parent e17eb633c3
commit de99a6d57a
@@ -277,7 +277,7 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 - **Paste, drop or attach images, videos and documents** (PDF, Office files, zip and plain text) directly into the session. They are saved in a hidden `.codeman-uploads/` folder in the workspace (it ignores itself in git and is swept after 7 days), and the file's path lands on your prompt, unsent.
 - **Voice input** — `Ctrl+Shift+V` (Deepgram Nova-3, or this machine's Claude Code login with no API key; auto-silence stop).
 - **Attachments** — register external files/docs and preview Office/PDF inline; any file path an agent prints is clickable, in the terminal and in the chat view, including `~/` and relative paths and paths broken across lines. An `.html` report opens as a real page, Markdown opens rendered, and a folder opens as a grid of its files.
- **When it needs you** — the tab turns yellow (waiting for input) or red (a question is blocking). The **Approvals Inbox** _(opt-in)_ queues the prompts waiting on you from Claude Code, Codex and DeepSeek Harness sessions in one list. Claude prompts are answerable from the header bell, the phone home screen or a push notification's Approve/Deny buttons; Codex and DeepSeek items are alerts that tell you to answer in the terminal, and prompts from the other CLIs do not enter it. 🧠 **Read My Mind** _(opt-in)_ drafts your next prompt from the case's goals and recent work.
+- **When it needs you** — the tab turns yellow (waiting for input) or red (a question is blocking). The **Approvals Inbox** _(opt-in)_ queues the prompts waiting on you from Claude Code, Codex and DeepSeek Harness sessions in one list. Claude prompts are answerable from the header bell, Claude dialogs also from the phone home screen, and a Claude permission prompt also from a push notification's Approve/Deny buttons; Codex and DeepSeek items are alerts that tell you to answer in the terminal, and prompts from the other CLIs do not enter it. 🧠 **Read My Mind** _(opt-in)_ drafts your next prompt from the case's goals and recent work.
 - **Copy what you see** — `Shift+drag` selects text even while the CLI owns the mouse, right-click copies it, and Auto Copy _(opt-in)_ copies a selection the moment you release it. A program that copies with OSC 52 (Claude Code's `/copy`, a tmux yank, vim) puts the text on your browser's clipboard too.

 ### 5. Make it autonomous
@@ -279,7 +279,7 @@ codeman service install           # systemd/launchd 服务：重启后自动回
 - **粘贴、拖放或附加图片、视频和文档**（PDF、Office 文件、zip 和纯文本），直接进入会话。它们保存在工作区里一个隐藏的 `.codeman-uploads/` 文件夹中（它在 git 里会忽略自己，7 天后被清理），文件路径会落在你的提示里，但不会自动发送。
 - **语音输入** —— `Ctrl+Shift+V`（Deepgram Nova-3，或者直接用这台机器的 Claude Code 登录、不需要任何 API key；自动静音停止）。
 - **附件** —— 注册外部文件/文档，并内联预览 Office/PDF；智能体打印出的任何文件路径都可以点击，终端里和对话视图里都行，包括 `~/` 路径、相对路径和被折成多行的路径。`.html` 报告会以真实网页打开，Markdown 会渲染后打开，文件夹则以其文件的网格打开。
- **需要你的时候** —— 标签会变黄（等待输入）或变红（有个问题挡住了它）。**审批收件箱（Approvals Inbox）**（可选启用）把 Claude Code、Codex 和 DeepSeek Harness 会话里等着你的提示排成一个队列。Claude 的提示可以从页头的铃铛、手机首页或推送通知上的 Approve/Deny 按钮直接作答；Codex 和 DeepSeek 的条目只是提醒，会告诉你去终端里作答；其他 CLI 的提示不会进入收件箱。🧠 **Read My Mind**（可选启用）会根据这个 case 的目标和最近的工作替你起草下一条提示。
+- **需要你的时候** —— 标签会变黄（等待输入）或变红（有个问题挡住了它）。**审批收件箱（Approvals Inbox）**（可选启用）把 Claude Code、Codex 和 DeepSeek Harness 会话里等着你的提示排成一个队列。Claude 的提示可以在页头的铃铛里直接作答，Claude 的对话框也可以在手机首页作答，Claude 的权限请求还可以用推送通知上的 Approve/Deny 按钮作答；Codex 和 DeepSeek 的条目只是提醒，会告诉你去终端里作答；其他 CLI 的提示不会进入收件箱。🧠 **Read My Mind**（可选启用）会根据这个 case 的目标和最近的工作替你起草下一条提示。
 - **看到什么就能复制什么** —— `Shift+拖动` 在 CLI 接管了鼠标时也能选中文本，右键复制选中内容，自动复制（Auto Copy，可选启用）在松开鼠标的瞬间就复制。用 OSC 52 复制的程序（Claude Code 的 `/copy`、tmux 的 yank、vim）也会把文本放进你浏览器的剪贴板。

 ### 5. 让它自主运行
@@ -216,8 +216,10 @@ runs no agent, and the external CLIs render their own TUIs and post no hooks
 (`deepseek`'s status bridge reports the same two, see its own docs). The one exception
 is `blocked` on `codex`: Codeman reads codex's approval, question and trust dialogs off
 its screen and raises `blocked` for them (see [Signals](#signals)). For every other mode
-only `idle`, `working` and `exit` are accepted, and of those only `exit` is
-dependable: see the caveats under [Signals](#signals) before building on `idle`.
+only `idle`, `working` and `exit` are accepted. `exit` is dependable everywhere; `idle` and
+`working` are screen-checked for `opencode`, `gemini`, `pi` and `omp` (as for `claude` and
+`codex`) and not guaranteed elsewhere: see the caveats under [Signals](#signals) before
+building on `idle`.
 Requesting a signal the session can never emit **explicitly** is a `400` (`stop` on
 `codex` included); omitting `until` never fails, the server just drops them from the
 default set and echoes the narrowed set back as `wait.until`. Three more places hooks can go
@@ -11,7 +11,7 @@ One cross-session inbox for every prompt that is waiting on a human: permission

 ## Scope

- Claude mode only (hooks fire only for `claude`; external CLIs keep their output-stabilization heuristics and get no inbox items). This mirrors the wait-primitive `stop`/`blocked` gating.
+- Claude mode only (hooks fire only for `claude`; external CLIs keep their output-stabilization heuristics and get no inbox items). This mirrors the wait-primitive `stop`/`blocked` gating. Since then, DeepSeek Harness (through its status bridge) and Codex (through dialogs read off its screen) open alert-only items; answerable items are still Claude's alone (see `src/web/approval-inbox.ts`).
 - Permission prompts occur for sessions running `ClaudeMode` `normal` / `auto` / `allowedTools` (and the trust-folder dialog even under skip-permissions). Question and idle prompts occur in every mode including `dangerously-skip-permissions`.
 - In-memory store (plus the frontend seeding from it on load). Server restart drops items; hooks re-fire on the next prompt. No new state file in v1.

@@ -265,9 +265,8 @@ siblings; no other external CLI mode qualifies. Two edges are worth repeating he
  reports a turn that never ran, and leaves the prompt in a pane that was not yet
  accepting input. Wait for the composer (`❯`) instead.
 - **Wait on `stop`, not on the default signal set.** That set also carries `idle`,
-  which for dsh, as for every external CLI that declares no working line, is
-  inferred from output stabilization; a dsh TUI that repaints rarely reads as idle
-  mid-turn.
+  which for dsh is inferred from output stabilization; a dsh TUI that repaints
+  rarely reads as idle mid-turn.

 ## 6. The web UI as a tab

@@ -121,10 +121,12 @@ the remote host, `grok login --device-auth` exists for exactly this.

 ## Known gaps

- **No idle/completion hook yet.** Idle detection falls back to output-stabilization,
-  as it does for Antigravity: the registry entry declares no `workDetect` prompt marker
-  or working line, which is what gives Codex, OpenCode, Gemini, Pi and OMP a screen
-  check instead. Grok has a hooks system, so a Codeman hook POSTing to
+- **No idle/completion hook yet.** The registry entry declares no `workDetect` prompt
+  marker or working line, which is what gives Codex, OpenCode, Gemini, Pi and OMP a
+  screen check. So Codeman calls a new grok pane idle 3 seconds after launch, and after
+  that it has only generic cues: Claude's `❯` marker, which grok does not print (see the
+  cron item below), and a braille spinner glyph. Working and idle are unreliable for
+  grok, as for Antigravity. Grok has a hooks system, so a Codeman hook POSTing to
  `/api/hook-event` is the highest-value follow-up.
 - **No response viewer.** Grok writes ACP JSONL sessions under
  `~/.grok/sessions/<encoded-cwd>/<session-id>/updates.jsonl`; nothing reads them yet.
@@ -69,7 +69,7 @@ output. The other CLIs expose no equivalent.
 | Respawn cycling and unattended runs               | Yes    | Yes                                                  |
 | Cron jobs                                         | Yes    | Yes                                                  |
 | Docker cases, remote SSH cases                    | Yes    | Yes                                                  |
-| Precise idle detection                            | Yes    | Codex, Pi, OpenCode, OMP and Gemini: same screen check, via their own prompt and working line. DeepSeek: reports its state itself. Others: output stabilization, coarser |
+| Precise idle detection                            | Yes    | Codex, Pi, OpenCode, OMP and Gemini: same screen check, via their own prompt and working line. DeepSeek: reports its end of turn itself. Antigravity and Grok: generic cues only, unreliable |
 | Auto-resume when a usage limit resets             | Yes    | No                                                   |
 | Plan usage chip                                   | Yes    | No                                                   |
 | Approvals Inbox                                   | Yes    | DeepSeek and Codex as alerts (answer in the terminal); others no |
@@ -305,7 +305,8 @@ into the case's `.claude/settings.local.json` so that `/model` keeps working.
  auto-resume, the Approvals Inbox, and subagent visualization all assume it.
 - **Codex, OpenCode, Gemini, Antigravity, Grok, OMP** when you prefer that agent or that
  model. You get the session layer, respawn, cron, Docker, and remote SSH; you do not get the
-  hook-driven features.
+  hook-driven features (Codex dialogs still raise the red alert and an alert-only inbox card,
+  see [Codex](#codex) above).
 - **DeepSeek Harness** if you want DeepSeek's models with real status signals. It is the one
  non-Claude mode that reports idle, working and blocked to Codeman itself.
 - **Pi** if you want a fast, unsandboxed agent and you understand what project trust does.
@@ -164,7 +164,7 @@ report events back: a permission prompt appeared, the turn finished, the agent w
 task completed. Those events drive tab alerts, the Approvals Inbox, notifications, and the
 wait primitives.

-This is why some features are Claude-only. The one partial exception is DeepSeek Harness,
+This is why some features are Claude-only. One partial exception is DeepSeek Harness,
 whose terminal front door reports idle, working and blocked to Codeman over the harness's
 own supervisor contract, so it gets the hook-driven signals without a hook file. Codex gets
 one of them from its screen: Codeman reads its approval, question and trust dialogs off the
@@ -19,7 +19,7 @@ terminal into something that can notify you.
 | `teammate_idle`        | An agent-team member goes idle.                  | Team surfaces.                                 |
 | `task_completed`       | A task finishes.                                 | Task tracking, run summary.                    |

-This is why several Codeman features are Claude-only. The one partial exception is DeepSeek
+This is why several Codeman features are Claude-only. One partial exception is DeepSeek
 Harness, whose terminal front door reports idle, working and blocked to Codeman over the
 harness's own supervisor contract, so it gets the hook-driven surfaces without any hook
 file. Codex gets one of them from its screen: Codeman reads its approval, question and
@@ -30,9 +30,12 @@ output silence, and token stability.
 **For the other CLIs** it depends on what the CLI tells Codeman. Codex, OpenCode, Gemini
 CLI, Pi and OMP each declare their own prompt marker and working line, so they get the same
 screen check Claude does (before 1.26.1 every Codex session reported idle for its whole
-life). DeepSeek Harness reports idle, working and blocked to Codeman itself, which is as
-precise as hooks. Antigravity and Grok Build declare neither, so they fall back to output
-stabilization: the session is idle when output stops changing, which is coarser.
+life). DeepSeek Harness reports its end of turn and its dialogs to Codeman itself, which is
+as precise as hooks; its working and idle display still comes from its output. Antigravity
+and Grok Build declare neither. Codeman calls a new pane of theirs idle 3 seconds after
+launch, and after that it has only generic cues to go on (Claude's `❯` prompt marker, a
+braille spinner glyph), which these CLIs may not draw, so their working and idle status is
+unreliable.

 ## The Respawn Controller

@@ -163,7 +166,8 @@ run summary and lifecycle log carry the detail.
  a vague next cycle.
 - **Non-Claude sessions can respawn**, but with no usage-limit auto-resume, and with
  output-based idle detection except on DeepSeek Harness, whose own end-of-turn report
-  reaches the respawn controller the way Claude's `stop` hook does.
+  reaches the respawn controller the way Claude's `stop` hook does while its status bridge
+  is on (a local session, by default).
 - **Do not run respawn on a session you are actively typing in.** It will send prompts
  underneath you.

@@ -43,9 +43,9 @@ as the keyboard appearing.

 Tapping the "C" logo gives a session overview rather than a welcome page:

-1. **NEEDS YOU** first: sessions blocked on a question, with answer strips so you can
-   resolve a Claude prompt without opening the session. A Codex or DeepSeek Harness row
-   offers **Answer in terminal** instead, which opens the session.
+1. **NEEDS YOU** first: sessions blocked on a question, with answer strips (Approvals Inbox
+   on) so you can resolve a Claude dialog without opening the session. A Codex or DeepSeek
+   Harness row offers **Answer in terminal** instead, which opens the session.
 2. **CURRENT SESSIONS** with live status.
 3. **PAST SESSIONS**, resumable.

@@ -169,8 +169,8 @@ phone, and it is the main reason the feature exists.
 ## Notifications

 Push notifications reach you with no tab open, and with the Approvals Inbox on, those for a
-Claude prompt carry **Approve** and **Deny** buttons handled by the service worker, so you
-can unblock a Claude agent from the lock screen.
+Claude permission prompt carry **Approve** and **Deny** buttons handled by the service
+worker, so you can unblock a Claude agent from the lock screen.

 Setup in [Notifications And Approvals](Notifications-And-Approvals).

@@ -39,8 +39,8 @@ hooks, but its dialogs are distinctive enough to read off the screen, so a Codex
 waiting on an approval, a question or the "Trust this folder?" prompt turns red too, and
 clears a few seconds after you answer. For the other CLIs there are no hooks and no dialog
 reading, so you get only the coarser working and idle state: read off the screen for
-OpenCode, Gemini CLI, Pi and OMP, and inferred from output settling for Antigravity and
-Grok Build.
+OpenCode, Gemini CLI, Pi and OMP, and unreliable for Antigravity and Grok Build, which
+declare nothing Codeman can read it from.

 ## Window title and OS notifications

@@ -141,17 +141,19 @@ Behaviour worth knowing:
  sending, and refuses with a conflict if the dialog is no longer there. Otherwise your
  keystroke would land in the composer as stray text.
 - **Permission and question items clear only on definitive signals**: the turn ending, the
-  dialog completing, an answer, a supersede, the session exiting, or a 12 hour timeout. They
-  do not clear on a heuristic "looks busy again" signal, because that signal is wrong often
-  enough to lose a real prompt.
+  dialog completing, an answer, a supersede, the session exiting, or a 12 hour timeout. A
+  Codex item also clears a few seconds after its dialog leaves the screen, and a DeepSeek
+  Harness item when the harness reports it is working again. They do not clear on a
+  heuristic "looks busy again" signal, because that signal is wrong often enough to lose a
+  real prompt.
 - **In memory only.** Restarting the server clears the queue; the prompts themselves are
  still sitting in the sessions.

 ### Approve and Deny from the notification

-With the inbox enabled, push notifications for a Claude prompt carry **Approve** and
-**Deny** buttons. Those are handled by the service worker directly, so they work with no tab
-open: tap Approve on a locked phone and the agent continues. A Codex or DeepSeek Harness
+With the inbox enabled, push notifications for a Claude permission prompt carry **Approve**
+and **Deny** buttons. Those are handled by the service worker directly, so they work with no
+tab open: tap Approve on a locked phone and the agent continues. A Codex or DeepSeek Harness
 notification carries no Approve or Deny, since those dialogs are answered in the terminal.

 With the inbox off, the buttons are stripped from the notification payload entirely rather
@@ -192,9 +194,9 @@ current sessions, then past ones. Rows use the same language as the tab strip: a
 when fine, pulsing while working, yellow when waiting for input, red when a question is
 pending.

-Answer strips let you resolve a Claude prompt straight from the home screen without opening
-the session. A Codex or DeepSeek Harness strip offers **Answer in terminal** instead, which
-opens the session.
+With the Approvals Inbox on, answer strips let you resolve a Claude permission or question
+dialog straight from the home screen without opening the session. A Codex or DeepSeek
+Harness strip offers **Answer in terminal** instead, which opens the session.

 ## The Away Digest

@@ -116,11 +116,12 @@ seconds in. Current versions confirm against the actual screen before believing

 ### A session is stuck showing busy

-For Antigravity and Grok Build, idle detection is output-based and coarser by necessity:
-those CLIs expose no hooks and declare no working line Codeman can read off the screen.
-Codex, OpenCode, Gemini CLI, Pi and OMP get the same screen check Claude does, and DeepSeek
-Harness reports its own state. A session that has genuinely gone quiet will settle. If it
-never does, interrupt it (`Ctrl+C` with nothing selected).
+For Antigravity and Grok Build the busy and idle status is unreliable: those CLIs expose no
+hooks and declare no working line, so after launch Codeman has only generic cues to go on
+(Claude's `❯` prompt marker, a braille spinner glyph), which they may not draw. Codex,
+OpenCode, Gemini CLI, Pi and OMP get the same screen check Claude does, so a session of
+theirs that has genuinely gone quiet will settle. If it never does, interrupt it (`Ctrl+C`
+with nothing selected).

 ### The agent asks about bypass permissions every time

@@ -552,8 +552,9 @@ That is true of no other non-claude mode, and it is worth knowing why: the DeepS
 Harness TUI reports `idle`/`working`/`blocked` to Codeman over the supervisor contract it
 implements, so dsh is the one external CLI with definitive `stop`/`blocked` signals
 instead of guessed-from-silence ones — and it writes a structured transcript, which is
-what `last-response` reads for it. `shell`, `opencode`, `codex`, `gemini`, `antigravity`,
-`pi`, `grok` and `omp` have neither and still need markers ([§5.5](reference/verbs.md#55-markers-for-hook-less-workers)).
+what `last-response` reads for it. `shell`, `opencode`, `gemini`, `antigravity`, `pi`,
+`grok` and `omp` have neither, and `codex` has a transcript and a screen-read `blocked` but
+no `stop`, so all of them still need markers ([§5.5](reference/verbs.md#55-markers-for-hook-less-workers)).

 Three things to know before you spawn one:

@@ -634,8 +634,8 @@ Three bounded long-polls. Shared semantics:
 |--------|---------|---------------|
 | `idle` | output stabilized + prompt detected, heuristic, can flap mid-turn | every mode |
 | `working` | session started producing output | every mode |
-| `stop` | Claude Code `stop` hook, the definitive end-of-turn | `claude` only |
-| `blocked` | `permission_prompt` / `elicitation_dialog` hook, the worker needs an answer | `claude`; also `codex`, whose approval, question and trust dialogs Codeman reads off its screen (answer them in the terminal, never through the inbox) |
+| `stop` | Claude Code `stop` hook, the definitive end-of-turn | `claude`; also `deepseek`, whose harness reports its own end of turn while its status bridge is on |
+| `blocked` | `permission_prompt` / `elicitation_dialog` hook, the worker needs an answer | `claude`; also `deepseek` (its harness reports its dialogs, same condition), and `codex`, whose approval, question and trust dialogs Codeman reads off its screen (answer both in the terminal, never through the inbox) |
 | `exit` | PTY exited or session deleted | every mode |

 ⚠️ **`claude` mode is necessary for `stop`/`blocked`, not sufficient. The real
@@ -552,8 +552,9 @@ That is true of no other non-claude mode, and it is worth knowing why: the DeepS
 Harness TUI reports `idle`/`working`/`blocked` to Codeman over the supervisor contract it
 implements, so dsh is the one external CLI with definitive `stop`/`blocked` signals
 instead of guessed-from-silence ones — and it writes a structured transcript, which is
-what `last-response` reads for it. `shell`, `opencode`, `codex`, `gemini`, `antigravity`,
-`pi`, `grok` and `omp` have neither and still need markers ([§5.5](reference/verbs.md#55-markers-for-hook-less-workers)).
+what `last-response` reads for it. `shell`, `opencode`, `gemini`, `antigravity`, `pi`,
+`grok` and `omp` have neither, and `codex` has a transcript and a screen-read `blocked` but
+no `stop`, so all of them still need markers ([§5.5](reference/verbs.md#55-markers-for-hook-less-workers)).

 Three things to know before you spawn one:

@@ -634,8 +634,8 @@ Three bounded long-polls. Shared semantics:
 |--------|---------|---------------|
 | `idle` | output stabilized + prompt detected, heuristic, can flap mid-turn | every mode |
 | `working` | session started producing output | every mode |
-| `stop` | Claude Code `stop` hook, the definitive end-of-turn | `claude` only |
-| `blocked` | `permission_prompt` / `elicitation_dialog` hook, the worker needs an answer | `claude`; also `codex`, whose approval, question and trust dialogs Codeman reads off its screen (answer them in the terminal, never through the inbox) |
+| `stop` | Claude Code `stop` hook, the definitive end-of-turn | `claude`; also `deepseek`, whose harness reports its own end of turn while its status bridge is on |
+| `blocked` | `permission_prompt` / `elicitation_dialog` hook, the worker needs an answer | `claude`; also `deepseek` (its harness reports its dialogs, same condition), and `codex`, whose approval, question and trust dialogs Codeman reads off its screen (answer both in the terminal, never through the inbox) |
 | `exit` | PTY exited or session deleted | every mode |

 ⚠️ **`claude` mode is necessary for `stop`/`blocked`, not sufficient. The real