From 5175c69b66f736fea19117e7f984fc2e959c216b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 2 Nov 2026 23:36:04 +0000 Subject: [PATCH] fix(mcp): steer a soft doctor smoke at solidify A read-only swarm_doctor call while a run is unfinished and the report is soft-continue now sets next_action to swarm_solidify. gate_soft_continue and session_not_failed stay absent, and the call still does not settle the run or write a Parent baseline. Co-authored-by: Steper Lin --- AGENTS.md | 4 +- CHANGELOG.md | 1 + DEBUG.md | 8 ++ README.md | 2 +- README.zh.md | 2 +- examples/swarm-quickstart/README.md | 2 +- src/evolver/mcp_server.py | 7 +- src/evolver/swarm.py | 40 +++++++- .../test_mcp_host_usability_pending_smoke.py | 98 +++++++++++++++++++ 9 files changed, 158 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 58cbe9c..bfb9e17 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -402,7 +402,9 @@ boot 自动 ack 本 agent 的 `swarm.hello`。安装或拉代码后须重启 MCP 已暂停时 `next_action=await_supervisor_resume`。有待固化 run 时 `next_action` 仍是 `swarm_solidify`(`hint` 写明先固化;软缺口留在 `warning`,不盖掉这句),并带 `readonly_smoke`:只读冒烟用 `swarm_doctor` / `swarm_status`,不结算、不放宽门、不写 -Parent。此时 `boot_once` 为空。忽略 `next_action` 再调 `swarm_tick` 时默认不启新周期。 +Parent。软缺口(`soft_continue=true`)下 `swarm_doctor` 同样给出 +`next_action=swarm_solidify` 与 preserve 三元组,不写 `gate_soft_continue`、不写 +`session_not_failed`;硬阻断的 doctor 仍是 `ok=false`,不另给这个动作。此时 `boot_once` 为空。忽略 `next_action` 再调 `swarm_tick` 时默认不启新周期。 第一次 `ok=true`、`severity=soft`、`cycle_started=false`、`progress=false`、 `redirect_count=1`,`next_action` 仍是 `swarm_solidify`,不改 `last_run`。 同一条 run 再 tick 返回 `ok=false`、`loop_fuse=pending_redirect_loop`、 diff --git a/CHANGELOG.md b/CHANGELOG.md index 59a3b67..b18d17c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased ### Fixed +- **MCP 宿主可用性:未完成 run 的软缺口 doctor 指向固化**:`readonly_smoke` 点名的 `swarm_doctor` 在 `soft_continue=true` 且有未完成 run 时带 `next_action=swarm_solidify`、`pending_solidify` 与 preserve 三元组。`hint` 先写现在固化,软缺口仍是建议。不写 `gate_soft_continue`,不写 `session_not_failed`,不结算这条 run,不写 Parent baseline,不执行 `--fix`。没有未完成 run,或 doctor 本身是硬阻断(`ok=false`)时,不另给这个动作。 - **MCP 宿主可用性:未完成 run 的第一次 tick 重定向也写 `retryable=false`**:同一条未完成 run 的两次默认 `swarm_tick` 都带 `retryable=false`。缺席不再被读成「可以再 tick」。第一次仍是 `ok=true`、没有 `error`、`gate_soft_continue` 仍缺席(缺席不是 false,不把严格 false 当成整段会话失败)。保险丝仍是 `ok=false` 与 `loop_fuse=pending_redirect_loop`。不写 Parent baseline,不放宽固化门。 - **2000 字现场切片留住未跟踪新文件(DEBUG #57 续)**:失败 episode 与成功事件不再对 `capture_diff_snapshot` 的结果做 `[:2000]`。两臂都传入 `max_chars=2000`,截断在 helper 内完成。已跟踪 diff 会占满预算时,先裁跟踪前缀,固定留 480 字(不超过预算的四分之一)给未跟踪新文件块;没有合格未跟踪文件时,这截尾部还给跟踪 diff。返回长度不超过预算。`.venv` / `node_modules` / `__pycache__` / `.git` / 受保护文件 / `memory/`、`.evolver/` 等运行态目录 / 含 NUL 的二进制仍不进入补充。不改固化门,不写 Parent baseline,不开 val 密封。 - **失败现场 diff 包含未跟踪新文件(DEBUG #57)**:`capture_diff_snapshot` 在 `git diff HEAD` 之后追加未跟踪新文件的 unified diff。失败侧 `_failure_diff` 与成功侧共用这一 helper。依赖树、缓存、运行态目录、受保护路径和含 NUL 的二进制不进入这份补充。不改固化门,不写 Parent baseline,不开 val 密封。 diff --git a/DEBUG.md b/DEBUG.md index 14caf77..13661a8 100644 --- a/DEBUG.md +++ b/DEBUG.md @@ -1224,3 +1224,11 @@ - **根因**:保险丝写了 `retryable=false`,第一次重定向没写。缺席不是 false。`gate_soft_continue` 不能借来当停 tick 的 false,那个名字在不读旁注的宿主那里就是会话失败。 - **修复**:未完成 run 的两次默认 tick(有软缺口与无软缺口)都写 `retryable=false`。第一次仍是 `ok=true`、没有 `error`、没有 `loop_fuse`,`gate_soft_continue` 在软缺口上仍然缺席。`session_not_failed=true` 与 preserve 三元组不动。保险丝仍是 `ok=false`。不写 Parent baseline,不放宽固化门。目录缓存(DEBUG #61)未做假修复。 - **经验**:**停 tick 的严格 false 要写在本来就表示「要不要再试」的字段上。** `gate_soft_continue=false` 和第一次就翻 `ok=false` 都会被另一类宿主读成整段失败。`retryable` 缺席必须当成「未说可以再 tick」,写上 false 才盖住把缺席默认成继续的那一型。只认 `gate_soft_continue` 的宿主这次仍覆盖不到。 + +### 70. 只读冒烟走到 `swarm_doctor` 后丢掉「去固化」(MCP 易用性,已修) + +- **症状**:#69 之后,未完成 run 的 `readonly_smoke.tools` 仍是 `swarm_doctor` 与 `swarm_status`。status 带 `next_action=swarm_solidify`。doctor 在真实 git 仓库、冻结包未装时是 `ok=true`、`soft_continue=true`、`loop_ready=false`,没有 `next_action`,也没有 `pending_solidify`。hint 写软缺口不阻断循环。按冒烟去调 doctor、再服从 `next_action` 的宿主找不到动作;把缺席的动作加上 `soft_continue=true` 读成「循环没被挡住」的宿主会再 tick。doctor 自己不写 Parent baseline,但 `fixes` 里仍有 `evolver doctor --fix`(人执行时可能去量基线)。 +- **根因**:doctor 只摘要开箱检查,不读未完成 run。冒烟清单把两个工具写成等价的只读入口,返回却不等价。 +- **修复**:仅当未完成 run 且 `soft_continue=true`、没有硬 `blockers` 时,doctor 补上 `pending_solidify`、`next_action=swarm_solidify`、`readonly_smoke` 与 preserve 三元组。hint 先写现在调用 `swarm_solidify`,不要 tick,不要在固化前执行 `fixes`,本调用不结算、不写 Parent、不放宽固化门。不写 `gate_soft_continue`(严格 false 会重开 DEBUG #67)。不写 `session_not_failed`(那是 tick 重定向的旗标,不是 doctor 的健康位)。硬阻断(例如不是 git 仓库,`ok=false`)不另给 `next_action`。没有未完成 run 时 doctor 形状不变。不执行 `--fix`。目录缓存(DEBUG #61)未做假修复;工具描述与返回体同一口径,旧会话目录仍可能看不到新句子。 +- **经验**:**冒烟清单里的两个工具必须给出同一个下一步。** 只读不等于可以丢掉 `next_action`。`soft_continue=true` 表示缺口不是硬停,不是再 tick 的许可。 +- **仍在**:只读 `soft_continue`、忽略 `next_action` 的宿主仍可能再 tick。把 `soft_continue` 写成 false 会和 `gate_soft_continue=false` 一样,被不读旁注的宿主当成整段停,所以没有写。`fixes` 仍列出 `evolver doctor --fix`;本工具不执行它。hint 写明固化前不要执行。只认 `gate_soft_continue` 的 tick 重定向(DEBUG #69 余项 1)、把保险丝 `ok=false` 当成整段失败的宿主(余项 2)、以及目录缓存(DEBUG #61)这次都不动。 diff --git a/README.md b/README.md index ca986ed..67c4932 100644 --- a/README.md +++ b/README.md @@ -241,7 +241,7 @@ Live `tools/list` already publishes `swarm_tick` parameters `prompt_mode` (`full If a previous run is unfinished, `swarm_boot` keeps `next_action=swarm_solidify`, sets top-level `pending_solidify`, and adds `readonly_smoke` (`tools`: `swarm_doctor` and `swarm_status`, `settles_run`: false). `hint` says to solidify first. A soft gap (`no_baseline` / `pack_absent` / `unmeasured`) still attaches `warning` and `next_steps`, and it does not replace that hint or weaken the gate. A read-only smoke can call `swarm_doctor` or `swarm_status`; neither settles the run nor invents a Parent baseline. A `swarm_tick` in that state does not start a cycle. The first call stays soft (`ok` true, `severity` soft, `cycle_started` false, `progress` false, `redirect_count` 1, `retryable` false, `next_action` still `swarm_solidify`, `last_run` unchanged). An omitted `retryable` is not a license to tick again. The same call again on that run returns `ok` false, `loop_fuse=pending_redirect_loop`, `redirect_reason=pending_redirect_loop`, `severity` soft, `retryable` false, and no `error` field. It still does not start a cycle. `loop_fuse` and that `redirect_reason` are the tick-loop fuse. The code is not an `error` and not a `next_action`. `next_action` stays `swarm_solidify`. `dispatch_reason` stays `pending_solidify`. The first redirect keeps `redirect_reason=pending_solidify` and does not set `loop_fuse`. Connect-time instructions name `loop_fuse=pending_redirect_loop` the same way. The fuse is not a gate failure and not an abandon signal; a soft gap stays on `warning` and `next_steps`. Both returns set `preserve_pending` true, `abandon_run` false, and `action_required` to `swarm_solidify` (boot and status do too while solidify is still next). Do not drop the unfinished run. When a soft gap is present, `gate_soft_continue` is omitted on the first redirect and on the fuse (`tick_again` is false). Omitted is not false: the first redirect keeps `ok` true and sets no `error`, so a host that treats only a strict false as session death stays in the session and does not tick again. Both tick returns set `session_not_failed` true. Read that field before other flags: true means the session is not failed, and `loop_fuse` does not abandon the run when the preserve flags say to call `swarm_solidify`. `next_steps` starts with `swarm_solidify`. Boot and status keep `gate_soft_continue` true while a run is still unfinished, and they do not set `session_not_failed`. Pass `supersede_pending=true` to replace that run. Pause and the compaction checkpoint still refuse the cycle. -A cold `swarm_status` (this process has not called `swarm_boot`) returns `next_action=swarm_boot` and a short hint. After boot, status keeps `agent_name`, `source_revision`, and any soft `gap` / warnings. `tool_asset_search`, `tool_mailbox_poll`, `tool_cycle_timeline`, and `swarm_approvals` always return `{ok, items, hint}` — an empty match is not a blank body. `swarm_approvals` also keeps `pending` (the same rows as `items`) and `recent`. Read-only `swarm_doctor` mirrors `evolver doctor` without `--fix` (`ok`, soft warnings, command hints in `fixes`). `no_baseline` / `pack_absent` / `unmeasured` stay soft-continue. +A cold `swarm_status` (this process has not called `swarm_boot`) returns `next_action=swarm_boot` and a short hint. After boot, status keeps `agent_name`, `source_revision`, and any soft `gap` / warnings. `tool_asset_search`, `tool_mailbox_poll`, `tool_cycle_timeline`, and `swarm_approvals` always return `{ok, items, hint}` — an empty match is not a blank body. `swarm_approvals` also keeps `pending` (the same rows as `items`) and `recent`. Read-only `swarm_doctor` mirrors `evolver doctor` without `--fix` (`ok`, soft warnings, command hints in `fixes`). `no_baseline` / `pack_absent` / `unmeasured` stay soft-continue. When a run is unfinished and that report is soft-continue, doctor also sets `next_action=swarm_solidify`, `pending_solidify`, and the preserve triad (`preserve_pending`, `abandon_run=false`, `action_required=swarm_solidify`). It still does not settle the run or write a Parent baseline. `gate_soft_continue` and `session_not_failed` stay absent. A hard blocker keeps `ok` false and does not add that action. `swarm_boot(project=...)` binds a directory only when that path exists. `bound_paths.repo_root` is the code root (the git root walked from that directory, or the directory itself). `bound_paths.workspace_root` is the mutation directory. When they differ, or when `project` is a free-text label rather than a directory, the same object carries `warning` and `next_steps`. That is a soft warning: `ok` stays true and the loop still continues. A label is not turned into a new workspace. diff --git a/README.zh.md b/README.zh.md index c2649e4..8a5b324 100644 --- a/README.zh.md +++ b/README.zh.md @@ -242,7 +242,7 @@ uv run evolver migrate-state 若上一轮 run 还没固化,`swarm_boot` 的 `next_action` 仍是 `swarm_solidify`,顶层带 `pending_solidify`,并多一个 `readonly_smoke`(`tools` 为 `swarm_doctor` 与 `swarm_status`,`settles_run` 为 false)。`hint` 写明先固化。软缺口(`no_baseline` / `pack_absent` / `unmeasured`)仍附 `warning` 与 `next_steps`,但不盖掉这句 hint,也不放宽固化门。只读冒烟可以调 `swarm_doctor` 或 `swarm_status`:它们不结算这条 run,也不伪造 Parent baseline。 -本进程尚未 `swarm_boot` 时,`swarm_status` 返回 `next_action=swarm_boot` 和一句 hint。boot 之后 status 仍带 `agent_name`、`source_revision`,以及软缺口的 `gap` / warnings。`tool_asset_search`、`tool_mailbox_poll`、`tool_cycle_timeline`、`swarm_approvals` 一律返回 `{ok, items, hint}`,没有命中也不是空正文。`swarm_approvals` 另外保留 `pending`(与 `items` 同一队列)和 `recent`。只读 `swarm_doctor` 等同 `evolver doctor` 且不执行 `--fix`(`ok`、软警告、`fixes` 里的命令提示)。`no_baseline` / `pack_absent` / `unmeasured` 仍是 soft-continue。 +本进程尚未 `swarm_boot` 时,`swarm_status` 返回 `next_action=swarm_boot` 和一句 hint。boot 之后 status 仍带 `agent_name`、`source_revision`,以及软缺口的 `gap` / warnings。`tool_asset_search`、`tool_mailbox_poll`、`tool_cycle_timeline`、`swarm_approvals` 一律返回 `{ok, items, hint}`,没有命中也不是空正文。`swarm_approvals` 另外保留 `pending`(与 `items` 同一队列)和 `recent`。只读 `swarm_doctor` 等同 `evolver doctor` 且不执行 `--fix`(`ok`、软警告、`fixes` 里的命令提示)。`no_baseline` / `pack_absent` / `unmeasured` 仍是 soft-continue。有未完成 run 且这份报告是 soft-continue 时,doctor 也给出 `next_action=swarm_solidify`、`pending_solidify` 和 preserve 三元组(`preserve_pending`、`abandon_run=false`、`action_required=swarm_solidify`)。它仍不结算这条 run,也不写 Parent baseline。`gate_soft_continue` 与 `session_not_failed` 缺席。硬阻断保持 `ok=false`,不另给这个动作。 `swarm_boot(project=...)` 只在路径是已存在目录时绑定。`bound_paths.repo_root` 是代码根(从该目录向上找到的 git 根,否则就是该目录本身)。`bound_paths.workspace_root` 是变异所用目录。两者不一致,或 `project` 只是一段自由文本而不是目录时,同一对象带 `warning` 和 `next_steps`。这是软警告:`ok` 仍为 true,循环继续。自由文本不会被当成新的工作区。 diff --git a/examples/swarm-quickstart/README.md b/examples/swarm-quickstart/README.md index 51e4b0d..f66080c 100644 --- a/examples/swarm-quickstart/README.md +++ b/examples/swarm-quickstart/README.md @@ -50,7 +50,7 @@ swarm_boot ─▶ swarm_status ─▶ swarm_hook_event(信号采集) | `claude-code.mcp.json` | Claude Code | 项目根 `.mcp.json` | | `cursor-mcp.json` | Cursor | `.cursor/mcp.json` | -连上之后,本条消息已有别的任务就做那件事。没有别的任务时宿主调用 `swarm_boot`,再用一句话说明实际状态。若只调了 `swarm_status` 且本进程还没 boot,`next_action` 是 `swarm_boot`。空的 `tool_asset_search` / `tool_mailbox_poll` / `tool_cycle_timeline` / `swarm_approvals` 返回 `{ok, items, hint}`(`swarm_approvals` 另含 `pending` 与 `recent`)。`swarm_tick` 的 `prompt_mode` 默认 `full`;短载荷须显式 `prompt_mode=short` 或 `checklist_only=true`,此时 `engine_log` 不再内联 GEP 全文。只读 `swarm_doctor` 等同 `evolver doctor`(不执行 `--fix`)。宿主工具目录若仍看不到 `prompt_mode` / `checklist_only` 或 `swarm_doctor`,那是客户端对 `tools/list` 的缓存:重启 MCP 进程后新开一次会话才会重读。有未完成 run 时 `swarm_boot` 的 `next_action` 仍是 `swarm_solidify`,`hint` 写明先固化,并带 `readonly_smoke`(`swarm_doctor` / `swarm_status` 不结算、不放宽门);软缺口留在 `warning`。此时直接 `swarm_tick` 不启新周期(第一次 `cycle_started=false`、`ok=true`、`progress=false`,不改 `last_run`;同一条 run 再 tick 得到 `ok=false`、`loop_fuse=pending_redirect_loop`、`redirect_reason=pending_redirect_loop`,没有 `error` 字段,`next_action` 仍是 `swarm_solidify`(保险丝码不是 `next_action`;`dispatch_reason` 仍是 `pending_solidify`;第一次的 `redirect_reason` 仍是 `pending_solidify`),仍不启周期,不是门禁失败,也不是放弃;两次都带 `preserve_pending=true`、`abandon_run=false`,不要丢掉这条 run。有软缺口时第一次 tick 与保险丝都不带 `gate_soft_continue`(缺席不是 false;`ok` 第一次仍为 true,没有 `error`;`tick_again=false` 与 `retryable=false` 都表示不要再 tick,第一次也写 `retryable=false`;两次都带 `session_not_failed=true`,先读它,会话没有失败,`loop_fuse` 不放弃这条 run;`next_steps` 第一条是 `swarm_solidify`)。boot / status 的 `gate_soft_continue` 仍为 true,且不带 `session_not_failed`)。要替换才传 `supersede_pending=true`。`boot_once` 只登记会话,不在开机时同步技能。冻结包未装或没有基线时 boot / `swarm_tick` **soft-continue**(带 warnings + next_steps,可进入循环);Accept/publish 可 soft-accept(不伪造 Parent baseline、不打开 val 密封材料)。已暂停时仍返回 `await_supervisor_resume`。用户说「停」,宿主调用 `swarm_supervise` action=pause;说「继续」,宿主转达 resume。也可以对它说「启动蜂群进化」。返回的 instrument 按步执行 `swarm_tick → 执行 → swarm_distill → swarm_hypothesis → swarm_solidify → swarm_feedback`,直到终止条件。`swarm_hypothesis` 可带 `expected_outcome` 写预计通过的检查,结算时引擎对照实测写 `prediction_delta`;上一轮输出被截断时按问题调用 `episode_inspect` 读回原文;收到压缩信号或连续 4 次固化失败时先调 `swarm_checkpoint_working` 写下 `WORKING_SESSION.md`。`dispatch_prompt` 标 **PROPOSAL REQUIRED** 时改走 `swarm_propose`,不得自由编辑。`next_action=await_human_approval` 停住:`swarm_approvals` 读给人,人决定后才 `swarm_approval_resolve`。 +连上之后,本条消息已有别的任务就做那件事。没有别的任务时宿主调用 `swarm_boot`,再用一句话说明实际状态。若只调了 `swarm_status` 且本进程还没 boot,`next_action` 是 `swarm_boot`。空的 `tool_asset_search` / `tool_mailbox_poll` / `tool_cycle_timeline` / `swarm_approvals` 返回 `{ok, items, hint}`(`swarm_approvals` 另含 `pending` 与 `recent`)。`swarm_tick` 的 `prompt_mode` 默认 `full`;短载荷须显式 `prompt_mode=short` 或 `checklist_only=true`,此时 `engine_log` 不再内联 GEP 全文。只读 `swarm_doctor` 等同 `evolver doctor`(不执行 `--fix`)。有未完成 run 且 doctor 为 soft-continue 时,它的 `next_action` 也是 `swarm_solidify`(不写 `gate_soft_continue` / `session_not_failed`,不结算,不写 Parent)。宿主工具目录若仍看不到 `prompt_mode` / `checklist_only` 或 `swarm_doctor`,那是客户端对 `tools/list` 的缓存:重启 MCP 进程后新开一次会话才会重读。有未完成 run 时 `swarm_boot` 的 `next_action` 仍是 `swarm_solidify`,`hint` 写明先固化,并带 `readonly_smoke`(`swarm_doctor` / `swarm_status` 不结算、不放宽门);软缺口留在 `warning`。此时直接 `swarm_tick` 不启新周期(第一次 `cycle_started=false`、`ok=true`、`progress=false`,不改 `last_run`;同一条 run 再 tick 得到 `ok=false`、`loop_fuse=pending_redirect_loop`、`redirect_reason=pending_redirect_loop`,没有 `error` 字段,`next_action` 仍是 `swarm_solidify`(保险丝码不是 `next_action`;`dispatch_reason` 仍是 `pending_solidify`;第一次的 `redirect_reason` 仍是 `pending_solidify`),仍不启周期,不是门禁失败,也不是放弃;两次都带 `preserve_pending=true`、`abandon_run=false`,不要丢掉这条 run。有软缺口时第一次 tick 与保险丝都不带 `gate_soft_continue`(缺席不是 false;`ok` 第一次仍为 true,没有 `error`;`tick_again=false` 与 `retryable=false` 都表示不要再 tick,第一次也写 `retryable=false`;两次都带 `session_not_failed=true`,先读它,会话没有失败,`loop_fuse` 不放弃这条 run;`next_steps` 第一条是 `swarm_solidify`)。boot / status 的 `gate_soft_continue` 仍为 true,且不带 `session_not_failed`)。要替换才传 `supersede_pending=true`。`boot_once` 只登记会话,不在开机时同步技能。冻结包未装或没有基线时 boot / `swarm_tick` **soft-continue**(带 warnings + next_steps,可进入循环);Accept/publish 可 soft-accept(不伪造 Parent baseline、不打开 val 密封材料)。已暂停时仍返回 `await_supervisor_resume`。用户说「停」,宿主调用 `swarm_supervise` action=pause;说「继续」,宿主转达 resume。也可以对它说「启动蜂群进化」。返回的 instrument 按步执行 `swarm_tick → 执行 → swarm_distill → swarm_hypothesis → swarm_solidify → swarm_feedback`,直到终止条件。`swarm_hypothesis` 可带 `expected_outcome` 写预计通过的检查,结算时引擎对照实测写 `prediction_delta`;上一轮输出被截断时按问题调用 `episode_inspect` 读回原文;收到压缩信号或连续 4 次固化失败时先调 `swarm_checkpoint_working` 写下 `WORKING_SESSION.md`。`dispatch_prompt` 标 **PROPOSAL REQUIRED** 时改走 `swarm_propose`,不得自由编辑。`next_action=await_human_approval` 停住:`swarm_approvals` 读给人,人决定后才 `swarm_approval_resolve`。 ## 开箱 / Open box(首次准备的一条命令) diff --git a/src/evolver/mcp_server.py b/src/evolver/mcp_server.py index 075a986..3ec0b88 100644 --- a/src/evolver/mcp_server.py +++ b/src/evolver/mcp_server.py @@ -649,7 +649,12 @@ def tool_swarm_status() -> dict[str, Any]: return swarm_status() def tool_swarm_doctor() -> dict[str, Any]: - """Read-only. Open-box summary (same checks as evolver doctor, never --fix).""" + """Read-only. Open-box summary (same checks as evolver doctor, never --fix). + + While a run is unfinished and the report is soft-continue, next_action + is swarm_solidify. This call does not settle the run or write a Parent + baseline. gate_soft_continue and session_not_failed stay absent. + """ from evolver.swarm import swarm_doctor return swarm_doctor() diff --git a/src/evolver/swarm.py b/src/evolver/swarm.py index 2e8e27a..d7c7fe6 100644 --- a/src/evolver/swarm.py +++ b/src/evolver/swarm.py @@ -794,12 +794,49 @@ def swarm_status() -> dict[str, Any]: return _surface_bound_paths(_attach_host_session(body), bound) +def _attach_unfinished_run_to_doctor(report: dict[str, Any]) -> dict[str, Any]: + """Steer a soft doctor smoke at solidify while a run is unfinished. + + ``readonly_smoke`` names this tool next to ``swarm_status``. Status already + sets ``next_action``. A soft-continue doctor that omits it looks like + "the loop is not blocked", so the host ticks again. Hard blockers keep + ``ok`` false and do not gain that action. + + ``gate_soft_continue`` stays absent: a strict false is session death for + hosts that do not read ``session_not_failed``. That flag stays absent too. + It belongs on the tick redirect, not on a doctor health bit. This does not + run ``--fix`` and does not write a Parent baseline. + """ + if not _pending_solidify_state(): + return report + if report.get("soft_continue") is not True or report.get("blockers"): + return report + out = dict(report) + out["pending_solidify"] = True + out["next_action"] = "swarm_solidify" + out["readonly_smoke"] = _readonly_smoke_block() + _stamp_preserve_pending(out) + run_id = str(_pending_solidify_meta().get("run_id") or "").strip() + who = f"run_id={run_id}" if run_id else "the unfinished run" + lead = ( + f"Call swarm_solidify now for {who}. " + "Do not call swarm_tick. " + "This doctor call does not settle the run, does not write a Parent " + "baseline, and does not relax the solidify gate. " + "Soft gaps stay advisory. Do not apply fixes before swarm_solidify. " + ) + out["hint"] = lead + str(out.get("hint") or "") + return out + + def swarm_doctor() -> dict[str, Any]: """Read-only open-box summary. Does not install a pack or write a baseline. Same checks as ``evolver doctor`` without ``--fix``. ``no_baseline`` / ``pack_absent`` / ``unmeasured`` stay soft warnings. ``fixes`` are command hints for the host to show a person; this function never runs them. + A soft-continue report with an unfinished run also sets + ``next_action=swarm_solidify``. A hard blocker does not. """ from evolver.ops.open_box import SOFT_GAP_ERRORS, doctor @@ -849,7 +886,7 @@ def swarm_doctor() -> dict[str, Any]: "severity": severity, } ) - return { + body = { "ok": bool(report.get("ok")), "soft_continue": bool(report.get("soft_continue")), "loop_ready": bool(report.get("loop_ready")), @@ -865,6 +902,7 @@ def swarm_doctor() -> dict[str, Any]: "repo_root": report.get("repo_root"), "workspace_id": report.get("workspace_id"), } + return _attach_unfinished_run_to_doctor(body) def _working_snapshot() -> dict[str, Any]: diff --git a/tests/test_mcp_host_usability_pending_smoke.py b/tests/test_mcp_host_usability_pending_smoke.py index fee736d..9e1ac02 100644 --- a/tests/test_mcp_host_usability_pending_smoke.py +++ b/tests/test_mcp_host_usability_pending_smoke.py @@ -13,6 +13,7 @@ import asyncio import json +import subprocess from pathlib import Path from typing import Any @@ -183,6 +184,22 @@ def _assert_session_not_failed(payload: dict[str, Any]) -> None: assert "session_not_failed" in str(payload.get("note") or "") +def _host_smoke_decides_without_next_action(payload: dict[str, Any]) -> str: + """What a smoke host does after ``swarm_doctor``. + + ``next_action`` wins. With no action, ``soft_continue`` or ``ok`` true + means the loop is not blocked, so the host ticks. An omitted + ``gate_soft_continue`` is not a stop. ``session_not_failed`` is ignored: + doctor must not need that tick-redirect flag. + """ + action = str(payload.get("next_action") or "") + if action: + return action + if payload.get("soft_continue") is True or payload.get("ok") is True: + return "swarm_tick" + return "stop" + + def _host_next_call(payload: dict[str, Any]) -> str: """Follow ``next_action``. A soft gap is not a hard stop.""" if payload.get("severity") == "hard" or payload.get("error") in _SOFT_GAPS: @@ -324,6 +341,10 @@ def test_prompt_mode_and_doctor_are_listed_with_descriptions(self) -> None: assert doctor.annotations is not None assert doctor.annotations.read_only_hint is True assert "fix" not in (_schema(doctor).get("properties") or {}) + description = " ".join((doctor.description or "").split()) + assert "swarm_solidify" in description + assert "Parent baseline" in description + assert "session_not_failed" in description class TestPendingBootSmokeHint: @@ -410,6 +431,83 @@ def test_checkpoint_outranks_the_smoke_block(self, isolated_swarm_env: Path) -> assert isinstance(state, dict) assert "readonly_smoke" not in state + def test_pending_doctor_on_a_soft_gap_names_solidify( + self, isolated_swarm_env: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + """A read-only smoke must steer to solidify, not back into tick. + + ``readonly_smoke`` names ``swarm_doctor`` next to ``swarm_status``. + Status already sets ``next_action=swarm_solidify``. Doctor used to + return only ``soft_continue`` and a hint that the loop is not blocked, + so a host that smokes and then follows ``next_action`` (or ticks when + that key is missing and ``soft_continue`` is true) never solidifies. + """ + from evolver.bench.frozen_gate import baseline_path, frozen_pack_path + from evolver.swarm import swarm_doctor + + monkeypatch.delenv("EVOLVER_NO_PARENT_GIT", raising=False) + subprocess.run(["git", "init"], cwd=isolated_swarm_env, check=True, capture_output=True) + + idle = swarm_doctor() + assert idle["ok"] is True + assert idle["soft_continue"] is True + assert "next_action" not in idle + assert "pending_solidify" not in idle + assert "preserve_pending" not in idle + assert "session_not_failed" not in idle + assert "gate_soft_continue" not in idle + + _write_pending("run_doctor_soft") + report = swarm_doctor() + + assert report["ok"] is True + assert report["soft_continue"] is True + assert report["loop_ready"] is False + assert report["read_only"] is True + assert report["blockers"] == [] + assert report["pending_solidify"] is True + assert report["next_action"] == "swarm_solidify" + assert report["readonly_smoke"]["settles_run"] is False + assert report["readonly_smoke"]["tools"] == ["swarm_doctor", "swarm_status"] + _assert_preserve_pending(report) + assert "session_not_failed" not in report + assert "gate_soft_continue" not in report + assert report.get("error") not in _SOFT_GAPS + assert _host_dies_on_soft_continue_false_ignoring_new_flags(report) is False + assert _host_smoke_decides_without_next_action(report) == "swarm_solidify" + hint = str(report.get("hint") or "") + assert hint.startswith("Call swarm_solidify") + assert "Do not call swarm_tick" in hint + assert "Parent baseline" in hint + assert "Do not apply fixes before swarm_solidify" in hint + assert "not installed" in hint.lower() or "do not block the loop" in hint.lower() + assert not baseline_path().exists() + assert not frozen_pack_path().exists() + assert report["fixes"] + + def test_pending_doctor_hard_blocker_does_not_invent_solidify( + self, isolated_swarm_env: Path + ) -> None: + """A hard doctor failure stays a hard stop. No solidify action is added. + + The isolated tree is not a git repo, so ``ok`` is false. That must + not grow ``next_action``, ``gate_soft_continue``, or + ``session_not_failed``. + """ + from evolver.swarm import swarm_doctor + + _write_pending("run_doctor_hard") + report = swarm_doctor() + assert report["ok"] is False + assert report["soft_continue"] is False + assert report["read_only"] is True + assert "next_action" not in report + assert "pending_solidify" not in report + assert "session_not_failed" not in report + assert "gate_soft_continue" not in report + assert _host_smoke_decides_without_next_action(report) == "stop" + _ = isolated_swarm_env + def test_instrument_names_the_read_only_alternative_only_while_pending(self) -> None: from evolver.swarm import build_instrument_prompt