diff --git a/README.md b/README.md index f496be07..816f8b57 100644 --- a/README.md +++ b/README.md @@ -847,7 +847,7 @@ When a CLI runs in a Codeman-managed session, these environment variables are se 4. **Response envelope.** Most endpoints return `{ "success": true, "data": … }` (errors: `{ "success": false, "error", "errorCode" }`). A few legacy GETs return bare bodies — **handle both** (`body.data ?? body`). 5. **`/api/v1/*`** is a stable alias of `/api/*`. 6. **Wait instead of polling, and don't treat a timeout as an error.** The wait endpoints answer with HTTP `200` and `wait.timedOut: true` when nothing happened in time, so loop over short waits (60s is the default) rather than issuing one long call, because tunnels cut idle connections. `wait.timeoutMs` tells you the timeout the server actually applied after clamping (600s ceiling). -7. **Only `claude` and `deepseek` sessions emit `stop` and `blocked`.** Those two come from hooks (Claude Code's own, and the DeepSeek Harness status bridge); `shell` and the other external CLIs (opencode/codex/gemini/antigravity/pi/grok/omp) accept only `idle`, `working` and `exit`. Asking for `stop` explicitly on those is a `400`; omitting `until` is always safe. ⚠️ On a `shell` session `idle` fires **once**, at startup, and never again, so send-and-wait there can only time out; synchronize hook-less sessions with a `wait-output` marker. +7. **Only `claude` and `deepseek` sessions emit `stop`; `codex` emits `blocked` too.** Those come from hooks (Claude Code's own, and the DeepSeek Harness status bridge), except codex's `blocked`, which Codeman reads off its screen while an approval, question or trust dialog is up (answer it in the terminal). `shell` and the other external CLIs (opencode/gemini/antigravity/pi/grok/omp) accept only `idle`, `working` and `exit`, and codex adds `blocked`. Asking for `stop` explicitly on those is a `400`; omitting `until` is always safe. ⚠️ On a `shell` session `idle` fires **once**, at startup, and never again, so send-and-wait there can only time out; synchronize hook-less sessions with a `wait-output` marker. 8. **Nothing reports "ready", so wait for it explicitly.** A new session answers `{"signal":"exit","immediate":true}` (that means *not started*, not *crashed*) until its PID exists, and a `claude` worker in a fresh case then sits on the CLI's trust dialog. Prompt it there and the wait resolves on `idle` in ~2s looking exactly like a finished turn, while the text sits stuck in the dialog. Recipe 2b below is the sequence that avoids it. ### Recipes diff --git a/README.zh-CN.md b/README.zh-CN.md index 38dd8e25..aee92d87 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -849,7 +849,7 @@ deleted 9f2d8e5f, aff9c691, be9f1f15 标签消失 4. **响应信封。** 多数端点返回 `{ "success": true, "data": … }`(错误:`{ "success": false, "error", "errorCode" }`)。少数遗留 GET 返回裸响应体 —— **两种都要处理**(`body.data ?? body`)。 5. **`/api/v1/*`** 是 `/api/*` 的稳定别名。 6. **用等待代替轮询,别把超时当成错误。** 等待类端点在没等到事情发生时也以 HTTP `200` 加 `wait.timedOut: true` 应答,所以要循环调用短等待(默认 60 秒),而不是发一个超长的调用:隧道会掐断空闲连接。`wait.timeoutMs` 告诉你服务端钳制之后真正采用的超时(上限 600 秒)。 -7. **只有 `claude` 与 `deepseek` 会话会发出 `stop` 与 `blocked`。** 这两个来自 hook(Claude Code 自己的,以及 DeepSeek Harness 的状态桥接);`shell` 与其他外部 CLI(opencode/codex/gemini/antigravity/pi/grok/omp)只接受 `idle`、`working` 与 `exit`。在这些模式上显式索要 `stop` 会得到 `400`;不传 `until` 则永远安全。⚠️ `shell` 会话的 `idle` 只在启动时触发**一次**,此后再也不会,所以在那里用「发送并等待」只能等到超时:没有 hook 的会话请用 `wait-output` 标记来同步。 +7. **只有 `claude` 与 `deepseek` 会话会发出 `stop`;`codex` 还会发出 `blocked`。** 它们来自 hook(Claude Code 自己的,以及 DeepSeek Harness 的状态桥接),codex 的 `blocked` 除外:批准、提问或信任对话框出现时,Codeman 从它的屏幕上读出这个信号(请在终端里回答)。`shell` 与其他外部 CLI(opencode/gemini/antigravity/pi/grok/omp)只接受 `idle`、`working` 与 `exit`,codex 另外接受 `blocked`。在这些模式上显式索要 `stop` 会得到 `400`;不传 `until` 则永远安全。⚠️ `shell` 会话的 `idle` 只在启动时触发**一次**,此后再也不会,所以在那里用「发送并等待」只能等到超时:没有 hook 的会话请用 `wait-output` 标记来同步。 8. **没有任何东西会报告「就绪」,得自己显式等。** 新会话在 PID 出现之前一律回答 `{"signal":"exit","immediate":true}`(意思是*还没启动*,不是*崩了*),而全新 case 里的 `claude` 工作会话接着会停在 CLI 的信任对话框上。此时给它发提示,等待会在约 2 秒后因 `idle` 解除,看上去和一个跑完的回合一模一样,而文本其实卡在对话框里。下面的配方 2b 就是避开它的顺序。 ### 常用配方 diff --git a/plugins/codeman/skills/codeman/reference/recipes.md b/plugins/codeman/skills/codeman/reference/recipes.md index 352d4e00..b518d93e 100644 --- a/plugins/codeman/skills/codeman/reference/recipes.md +++ b/plugins/codeman/skills/codeman/reference/recipes.md @@ -391,10 +391,10 @@ the worker remembering to print a token. ## Flow 5: watch for a worker stuck on a prompt -Claude workers can block on a permission dialog. `blocked` is a wait signal -(claude-mode only, and it needs Codeman's hooks in the worker's directory: see Flow 7 -step 4), so watch for it and surface the question to the user instead of guessing an -answer. Expect it routinely on a server whose `claudeMode` is not the default bypass +Claude workers can block on a permission dialog. `blocked` is a wait signal (a claude +worker needs Codeman's hooks in its directory for it: see Flow 7 step 4; a codex worker +gets it from its screen, see below), so watch for it and surface the question to the user +instead of guessing an answer. Expect it routinely on a server whose `claudeMode` is not the default bypass one (the same setting that decides whether the readiness marker in Flow 1 ever appears): @@ -409,10 +409,13 @@ if [ "$(jq -r '.data.wait.signal' <<<"$R")" = blocked ]; then fi ``` -Where the worker has no hooks, `blocked` never fires and a stuck worker looks exactly -like a slow one: your marker wait burns its whole bound. The fallback is the same -terminal tail, taken when a bound runs out, and the same rule about not answering it -yourself. +Codex workers are the one exception without hooks: Codeman reads their approval, +question and trust dialogs off the screen, so the same watch works with +`until=blocked,exit` (codex has no `stop`, a `400`), and the dialog is answered in the +terminal, never through the Approvals Inbox. Anywhere else without hooks, `blocked` never +fires and a stuck worker looks exactly like a slow one: your marker wait burns its whole +bound. The fallback is the same terminal tail, taken when a bound runs out, and the same +rule about not answering it yourself. ## Flow 6: claude fan-out over messaging diff --git a/skills/codeman/reference/recipes.md b/skills/codeman/reference/recipes.md index 352d4e00..b518d93e 100644 --- a/skills/codeman/reference/recipes.md +++ b/skills/codeman/reference/recipes.md @@ -391,10 +391,10 @@ the worker remembering to print a token. ## Flow 5: watch for a worker stuck on a prompt -Claude workers can block on a permission dialog. `blocked` is a wait signal -(claude-mode only, and it needs Codeman's hooks in the worker's directory: see Flow 7 -step 4), so watch for it and surface the question to the user instead of guessing an -answer. Expect it routinely on a server whose `claudeMode` is not the default bypass +Claude workers can block on a permission dialog. `blocked` is a wait signal (a claude +worker needs Codeman's hooks in its directory for it: see Flow 7 step 4; a codex worker +gets it from its screen, see below), so watch for it and surface the question to the user +instead of guessing an answer. Expect it routinely on a server whose `claudeMode` is not the default bypass one (the same setting that decides whether the readiness marker in Flow 1 ever appears): @@ -409,10 +409,13 @@ if [ "$(jq -r '.data.wait.signal' <<<"$R")" = blocked ]; then fi ``` -Where the worker has no hooks, `blocked` never fires and a stuck worker looks exactly -like a slow one: your marker wait burns its whole bound. The fallback is the same -terminal tail, taken when a bound runs out, and the same rule about not answering it -yourself. +Codex workers are the one exception without hooks: Codeman reads their approval, +question and trust dialogs off the screen, so the same watch works with +`until=blocked,exit` (codex has no `stop`, a `400`), and the dialog is answered in the +terminal, never through the Approvals Inbox. Anywhere else without hooks, `blocked` never +fires and a stuck worker looks exactly like a slow one: your marker wait burns its whole +bound. The fallback is the same terminal tail, taken when a bound runs out, and the same +rule about not answering it yourself. ## Flow 6: claude fan-out over messaging