tianshu-mcp 0.3.1 → 0.3.2

package/CHANGELOG.en.md

@@ -16,6 +16,62 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 - TraeWork executable discovery and native-dialog driving on macOS (currently fail-closed).
 - Optional project-level skill seeding (by default nothing is written into target repos).
 - macOS hardware verification for the Codex GUI adapter (built-in status remains `research`).
+- Best-effort stop of a GUI-side pending session (via a temporary CDP connection) when cancelling
+  a task in the `needs_user` state.
+
+---
+
+## [0.3.2] — 2026-09-12
+
+Fixes for issues #5 / #6: **the MCP task model was disconnected from the state of the turn inside
+the Codex GUI**. The former is the completion-detection deadlock that kept reporting `running`
+while Codex waited for user confirmation; the latter is `cancel_task` only aborting the MCP-side
+wait loop, never stopping the in-GUI run, with a misleading description. Both share the same root
+cause and are resolved together.
+
+### Fixed
+
+- **Waiting-for-user detection (issue #5)**:
+  - `judgeCodexPoll` gains a stall fallback: while the stop button stays visible and the
+    conversation hash is unchanged for `gui.stallTimeoutMs` (default 5 minutes), the task
+    transitions to `needs_user` (`needsUserKind=user_confirmation`) instead of deadlocking in
+    `running` until the overall timeout; the stall timer resets as soon as content changes again.
+  - New configurable UI detection `gui.selectors.userGate` (e.g. the embedded-checkout page or
+    approval cards): when configured and matched, transitions to `needs_user` immediately.
+    Unset by default (disabled) — no unverified selectors are built in.
+  - Tightened the `stopButton` selector: removed the `aria-label*="取消"` over-match (the Cancel
+    button on waiting-for-user screens used to be mistaken for a running signal).
+- **Recovery path (issue #5 fallout)**: `continue_task` now supports codex —
+  - `user_confirmation`: after the user completes the action in the Codex window, resume by
+    re-attaching as an observer of the in-GUI run (no message is sent); if the turn already
+    finished before resuming, the task is still judged `succeeded` correctly;
+  - `login_required`: after login, re-checks the environment and re-dispatches the task brief
+    (fresh session + project binding + full initial prompt);
+  - zcode recovery behaviour is unchanged; other agents are rejected explicitly.
+- **Cancel actually stops the GUI (issue #6)**:
+  - `cancel_task` no longer succeeds on request alone for GUI agents: it first best-effort clicks
+    the in-app stop button over CDP, then waits (bounded by `gui.cancelWaitMs`, default 15s) for
+    the GUI to become idle before settling `cancelled`; if the stop could not be confirmed the
+    terminal message states "GUI 内运行未确认停止…" (the in-GUI run may still be going);
+  - process-tree termination for CLI agents is unchanged;
+  - cancelling from `needs_user` now notes that a pending session may remain in the GUI
+    (no CDP connection exists at that point — documented limitation).
+- **Re-dispatch anti-overlap guard (issue #6 chain risk)**: when dispatching, if the managed
+  instance still has an unstopped run, MCP first tries to stop it; if it cannot, the dispatch
+  fails hard with `instance_busy`, preventing old and new turns from overlapping inside the same
+  app (observed in the wild when re-dispatching right after a cancel).
+- The startup log no longer hardcodes the tool count as `8`; it reports the actual registry size
+  (`TOOL_DEFS.length`, currently 9).
+
+### Changed
+
+- Tool descriptions match actual semantics: `cancel_task` distinguishes CLI (kill process tree)
+  from GUI (best-effort stop click + bounded wait); `continue_task` no longer claims to be
+  ZCode-only.
+- `GuiProfile` gains two configurable options, `stallTimeoutMs` (default 300000) and
+  `cancelWaitMs` (default 15000), both overridable via agent-profiles.json.
+- Skill docs (SKILL.md §4/§5, usage-examples.md §7) document the codex `user_confirmation` /
+  `login_required` recovery flows, GUI cancel semantics and the new options.
 
 ---
 
@@ -438,7 +494,8 @@ project → pick model and reasoning level → send instructions → run detecti
 
 ---
 
-[Unreleased]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.10...v0.2.0

package/CHANGELOG.md

@@ -15,6 +15,51 @@
 - TraeWork 在 macOS 下的可执行探测与原生对话框驱动（当前 macOS 分支 fail-closed）。
 - 可选的项目级技能播种（默认不写入目标项目仓库）。
 - Codex GUI 的 macOS 真机验证（当前内置状态为 `research`）。
+- needs_user 状态下取消任务时经临时 CDP 连接尽力停止 GUI 内等待中的会话。
+
+---
+
+## [0.3.2] — 2026-09-12
+
+修复 issue #5 / #6：**MCP 任务模型与 Codex GUI 内 turn 的状态脱节**。
+前者是"等用户确认时恒报 running"的完成判定死锁，后者是 `cancel_task` 只停 MCP 侧等待、
+不停 GUI 内运行且描述失实。同根问题一并收敛。
+
+### 修复
+
+- **等待用户检测（issue #5）**：
+  - `judgeCodexPoll` 新增 stall 兜底：停止按钮持续可见且对话哈希 `gui.stallTimeoutMs`
+    （默认 5 分钟）不变 → 判定等待用户，任务转 `needs_user`（`needsUserKind=user_confirmation`），
+    不再死锁在 `running` 直到总超时；对话内容恢复变化会重置 stall 计时。
+  - 新增可配置界面检测 `gui.selectors.userGate`（如结账页 `embedded-checkout`、确认卡）：
+    命中即快速转 `needs_user`；默认未配置 = 禁用，不内置未真机验证的选择器。
+  - 收紧 `stopButton` 选择器：移除 `aria-label*="取消"` 过匹配（等待用户界面的"取消"
+    按钮曾被误判为运行信号）。
+- **恢复通道（issue #5 牵连）**：`continue_task` 扩展支持 codex——
+  - `user_confirmation`：用户在 Codex 窗口处理完后恢复，MCP 仅重新接入观察 GUI 内运行
+    （不发送消息）；恢复前 turn 已完成也能正确判 `succeeded`；
+  - `login_required`：复检环境后重新派发任务书（新会话 + 项目绑定 + 完整初始指令）；
+  - zcode 原有恢复行为不变；其他 agent 明确拒绝。
+- **取消真停 GUI（issue #6）**：
+  - `cancel_task` 对 GUI agent 不再"请求即成功"：先经 CDP 尽力点击界面停止按钮，
+    并在 `gui.cancelWaitMs`（默认 15 秒）内有界等待 GUI 真正空闲后落 `cancelled`；
+    未确认停止时终态文案明示"GUI 内运行未确认停止，Codex 窗口中的任务可能仍在继续"；
+  - CLI agent 的进程树终止语义不变；
+  - `needs_user` 状态取消的文案提示"GUI 内可能仍有等待中的会话"（此时 MCP 侧无 CDP 连接，
+    列为已知边界）。
+- **重派防交叠护栏（issue #6 连锁）**：派发前发现受管实例上仍有未停止的运行时，
+  先尽力停止；仍不空闲则以 `instance_busy` 硬失败拒绝派发，杜绝新旧 turn 在同一
+  应用内交叠（取消后立刻重派曾实测踩中）。
+- 启动日志的工具数由硬编码 `8` 改为按注册表实际数量（`TOOL_DEFS.length`，当前为 9）输出。
+
+### 变更
+
+- 工具描述对齐实际语义：`cancel_task` 区分 CLI（kill 进程树）与 GUI（尽力点击停止 +
+  有界等待）；`continue_task` 去掉"只用于 ZCode"限定。
+- `GuiProfile` 新增 `stallTimeoutMs`（默认 300000）与 `cancelWaitMs`（默认 15000）配置项，
+  均可由 agent-profiles.json 覆盖。
+- 技能文档（SKILL.md §4/§5、usage-examples.md §7）补齐 codex `user_confirmation` /
+  `login_required` 恢复方式、GUI 取消语义与相关配置示例。
 
 ---
 
@@ -386,7 +431,8 @@ Codex 桌面端改为 **GUI 驱动**：新增 `codex-gui` adapter，通过 MSIX
 
 ---
 
-[未发布]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.1...HEAD
+[未发布]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.10...v0.2.0

package/dist/agents/adapter.d.ts

@@ -47,6 +47,11 @@ export interface TaskContext {
         kind: "continue" | "rework";
         message?: string;
         sendMessage: boolean;
+        /**
+         * 重新接入观察（不发送任何消息）：codex user_confirmation 恢复专用。
+         * 用户在 GUI 处理完等待项后 turn 自行继续，MCP 只需重连 CDP 观察到终态。
+         */
+        reobserve?: boolean;
         sessionId?: string;
         sessionTitle?: string;
         boundProjectPath?: string;
@@ -75,8 +80,17 @@ export interface AgentRunResult {
     endReason?: string;
     /** GUI 实例是否因任务未真正完成而被保留 */
     keptInstance?: boolean;
-    needsUserKind?: "agent_question" | "close_existing_instance" | "login_required" | "system_permission";
+    needsUserKind?: "agent_question" | "close_existing_instance" | "login_required" | "system_permission" | "user_confirmation";
     pendingQuestion?: string;
+    /**
+     * 取消路径的 GUI 侧停止结果（GUI agent 专用）：
+     * clicked=是否点击了界面停止按钮；idle=等待窗口内 GUI 是否真正空闲。
+     * idle=false 时编排方必须在终态文案中明示「GUI 内运行未停止」。
+     */
+    guiStop?: {
+        clicked: boolean;
+        idle: boolean;
+    };
     session?: {
         id?: string;
         title?: string;

package/dist/agents/builtin.js

@@ -37,6 +37,8 @@ export const BUILTIN_PROFILES = {
             pollIntervalMs: 3_000,
             stableRounds: 4,
             idleTimeoutMs: 10 * 60_000,
+            stallTimeoutMs: 5 * 60_000,
+            cancelWaitMs: 15_000,
             cdpSendTimeoutMs: 15_000,
             progressIntervalMs: 30_000,
             modelSwitch: true,
@@ -94,6 +96,8 @@ export const BUILTIN_PROFILES = {
             pollIntervalMs: 3_000,
             stableRounds: 4,
             idleTimeoutMs: 10 * 60_000,
+            stallTimeoutMs: 5 * 60_000,
+            cancelWaitMs: 15_000,
             cdpSendTimeoutMs: 15_000,
             progressIntervalMs: 30_000,
             modelSwitch: true,
@@ -150,6 +154,8 @@ export const BUILTIN_PROFILES = {
             pollIntervalMs: 3_000,
             stableRounds: 12,
             idleTimeoutMs: 10 * 60_000,
+            stallTimeoutMs: 5 * 60_000,
+            cancelWaitMs: 15_000,
             cdpSendTimeoutMs: 15_000,
             progressIntervalMs: 30_000,
             modelSwitch: true,

package/dist/agents/codex/cdp.d.ts

@@ -26,6 +26,8 @@ export interface CodexPoll {
     conversationText: string;
     /** 登录/引导页可见 */
     loginVisible: boolean;
+    /** 「等待用户」界面检测命中（gui.selectors.userGate 配置后启用） */
+    userGateVisible: boolean;
 }
 export declare class CodexCdpClient {
     private readonly selectors;

package/dist/agents/codex/cdp.js

@@ -258,11 +258,16 @@ export class CodexCdpClient {
          const els=__codexResolve(${specArgs("modelMenuItem", this.selectors)}).filter(vis);
          const available=els.map((e)=>(e.innerText||'').replace(/\\s+/g,' ').trim()).filter(Boolean);
          const hits=els.filter((e)=>norm(e.innerText)===target);
-         if(hits.length===1){const e=hits[0];const r=e.getBoundingClientRect();return {count:1,available,point:{x:Math.round(r.left+r.width/2),y:Math.round(r.top+r.height/2)}}}
+         if(hits.length===1){
+           // 真机实测（26.903.9818.0）：模型 radio 对 trusted 鼠标点击只收起菜单、不切换选中态，
+           // DOM .click() 才会真正生效（aria-checked 翻转）且菜单保持打开（后续调滑块依赖它）。
+           // 与「项目选择触发器需要 trusted 才能展开」相反——菜单项选择用 DOM click。
+           hits[0].click();
+           return {count:1,available,clicked:true};
+         }
          return {count:hits.length,available};`));
-        if (!found.point)
+        if (!found.clicked)
             return { clicked: false, count: found.count, available: found.available };
-        await this.clickAt(found.point.x, found.point.y);
         return { clicked: true, count: found.count, available: found.available };
     }
     /** 读取当前模型/思考等级触发器文本（限定输入框作用域，排除菜单栏与模式切换器） */
@@ -336,6 +341,7 @@ export class CodexCdpClient {
             sendButton: specArgs("sendButton", this.selectors),
             chatInput: specArgs("chatInput", this.selectors),
             loginIndicator: specArgs("loginIndicator", this.selectors),
+            userGate: specArgs("userGate", this.selectors),
             messageArea: specArgs("messageArea", this.selectors),
         })};${this.visibleFilter}
         const resolve=(k)=>__codexResolve(JSON.parse(sels[k]));
@@ -346,7 +352,8 @@ export class CodexCdpClient {
           sendVisible:visAny('sendButton'),
           composerText:(textOf('chatInput')||'').trim(),
           conversationText:(textOf('messageArea')||'').trim().slice(0,20000),
-          loginVisible:visAny('loginIndicator')
+          loginVisible:visAny('loginIndicator'),
+          userGateVisible:visAny('userGate')
         };`));
     }
 }

package/dist/agents/codex/liveness.d.ts

@@ -9,6 +9,8 @@ export interface CodexPoll {
     loginVisible: boolean;
     /** 发送按钮当前是否可见（输入非空时） */
     sendVisible?: boolean;
+    /** 「等待用户」界面检测命中（gui.selectors.userGate 配置后启用） */
+    userGateVisible?: boolean;
 }
 export interface CodexPollState {
     hash: string;
@@ -16,12 +18,16 @@ export interface CodexPollState {
     idleSince: number;
     /** 本轮是否曾观测到权威运行信号 */
     sawRunning: boolean;
+    /** 停止按钮可见且对话哈希不变的起始时刻（0 = 未在计时） */
+    stallSince: number;
 }
 export type CodexVerdict = {
-    kind: "running" | "pending" | "finished" | "needs_login" | "idle_timeout";
+    kind: "running" | "pending" | "finished" | "needs_login" | "needs_user" | "idle_timeout";
     state: CodexPollState;
     evidence: string;
 };
+/** 与 GuiProfileSchema.stallTimeoutMs 默认一致；仅供直调兜底，生产路径由 codexGuiOf 传入 */
+export declare const DEFAULT_STALL_TIMEOUT_MS = 300000;
 export declare function hashText(text: string): string;
 export declare const initialCodexState: () => CodexPollState;
-export declare function judgeCodexPoll(poll: CodexPoll, previous: CodexPollState, stableRounds: number, idleTimeoutMs: number, now?: number): CodexVerdict;
+export declare function judgeCodexPoll(poll: CodexPoll, previous: CodexPollState, stableRounds: number, idleTimeoutMs: number, now?: number, stallTimeoutMs?: number): CodexVerdict;

package/dist/agents/codex/liveness.js

@@ -1,5 +1,5 @@
 /**
- * Codex 任务运行判定（开发计划决策 7/8）。
+ * Codex 任务运行判定（开发计划决策 7/8；issue #5 修复后含 stall 判定）。
  *
  * 设计（吸取 TraeWork 误判完成的教训）：
  * 1. 停止按钮为**权威运行信号**：出现即 running，绝不在此时判完成。
@@ -7,8 +7,17 @@
  *    把「其实还在生成、只是 DOM 恰好静止」误判为完成。
  * 3. 若始终未观测到运行信号（选择器未命中）→ 不判完成，转入空闲计时，最终 idle_timeout：
  *    结束本轮但**不终止实例**（失败开放，不比现状更糟）。
+ * 4. 等待用户判定（issue #5）：「方案确认卡/订阅结账页」等场景下 turn 是暂停而非结束，
+ *    停止按钮恒可见 → 上面的规则会死锁。两条出路：
+ *    - userGateVisible：profile.gui.selectors.userGate 配置的界面检测（快速路径）；
+ *    - stall 兜底：停止按钮持续可见且对话哈希 stallTimeoutMs 不变 → needs_user。
+ *      它无法区分「等用户确认」与「长时间静默的合法长命令」，误判后果是转
+ *      needs_user（非终态、可 continue 恢复），远好于死等总超时；长命令任务
+ *      应调大 gui.stallTimeoutMs。
  */
 import { createHash } from "node:crypto";
+/** 与 GuiProfileSchema.stallTimeoutMs 默认一致；仅供直调兜底，生产路径由 codexGuiOf 传入 */
+export const DEFAULT_STALL_TIMEOUT_MS = 300_000;
 export function hashText(text) {
     return createHash("sha256").update(text).digest("hex").slice(0, 12);
 }
@@ -17,29 +26,55 @@ export const initialCodexState = () => ({
     stable: 0,
     idleSince: 0,
     sawRunning: false,
+    stallSince: 0,
 });
-export function judgeCodexPoll(poll, previous, stableRounds, idleTimeoutMs, now = Date.now()) {
+export function judgeCodexPoll(poll, previous, stableRounds, idleTimeoutMs, now = Date.now(), stallTimeoutMs = DEFAULT_STALL_TIMEOUT_MS) {
     const hash = hashText(poll.conversationText);
     if (poll.loginVisible)
         return {
             kind: "needs_login",
-            state: { hash, stable: 0, idleSince: 0, sawRunning: previous.sawRunning },
+            state: { hash, stable: 0, idleSince: 0, sawRunning: previous.sawRunning, stallSince: 0 },
             evidence: "login_indicator",
         };
-    if (poll.stopVisible)
+    // 等待用户快速路径：界面检测命中（如结账页/确认卡，选择器可配置）
+    if (poll.userGateVisible)
+        return {
+            kind: "needs_user",
+            state: { hash, stable: 0, idleSince: 0, sawRunning: previous.sawRunning, stallSince: 0 },
+            evidence: "user_gate",
+        };
+    if (poll.stopVisible) {
+        // stall 兜底（issue #5）：停止按钮恒可见时对话哈希长时间不变 → 判定等待用户。
+        const hashUnchanged = hash === previous.hash;
+        const stallSince = hashUnchanged ? previous.stallSince || now : now;
+        if (hashUnchanged && previous.stallSince && now - previous.stallSince >= stallTimeoutMs)
+            return {
+                kind: "needs_user",
+                state: { hash, stable: 0, idleSince: 0, sawRunning: true, stallSince },
+                evidence: "stop_button+stall",
+            };
         return {
             kind: "running",
-            state: { hash, stable: 0, idleSince: 0, sawRunning: true },
+            state: { hash, stable: 0, idleSince: 0, sawRunning: true, stallSince },
             evidence: "stop_button",
         };
+    }
     const sawRunning = previous.sawRunning;
     const stable = hash === previous.hash && poll.conversationText.trim() ? previous.stable + 1 : 0;
     const idleSince = stable >= stableRounds ? previous.idleSince || now : 0;
     // 权威完成：曾运行 → 停止钮消失 → 文本稳定
     if (sawRunning && stable >= stableRounds && poll.conversationText.trim())
-        return { kind: "finished", state: { hash, stable, idleSince, sawRunning }, evidence: "stop_button_gone+text_stable" };
+        return {
+            kind: "finished",
+            state: { hash, stable, idleSince, sawRunning, stallSince: 0 },
+            evidence: "stop_button_gone+text_stable",
+        };
     // 失败开放：始终无运行信号 → 空闲超时（结束本轮、保留实例）
     if (idleSince && now - idleSince >= idleTimeoutMs)
-        return { kind: "idle_timeout", state: { hash, stable, idleSince, sawRunning }, evidence: "no_running_signal+idle" };
-    return { kind: "pending", state: { hash, stable, idleSince, sawRunning }, evidence: "none" };
+        return {
+            kind: "idle_timeout",
+            state: { hash, stable, idleSince, sawRunning, stallSince: 0 },
+            evidence: "no_running_signal+idle",
+        };
+    return { kind: "pending", state: { hash, stable, idleSince, sawRunning, stallSince: 0 }, evidence: "none" };
 }

package/dist/agents/codex/run.js

@@ -51,6 +51,8 @@ export function codexGuiOf(resolved) {
         pollIntervalMs: g?.pollIntervalMs ?? 3_000,
         stableRounds: g?.stableRounds ?? 4,
         idleTimeoutMs: g?.idleTimeoutMs ?? 10 * 60_000,
+        stallTimeoutMs: g?.stallTimeoutMs ?? 5 * 60_000,
+        cancelWaitMs: g?.cancelWaitMs ?? 15_000,
         cdpSendTimeoutMs: g?.cdpSendTimeoutMs ?? 15_000,
         progressIntervalMs: g?.progressIntervalMs ?? 30_000,
         modelSwitch: g?.modelSwitch ?? true,
@@ -189,8 +191,28 @@ export async function runCodexTask(args) {
                 session: { boundProjectPath: ctx.projectPath, model: spec.model, permissionMode: gui.defaultPermissionMode },
             });
         await cdp.dismissMenus();
-        const resuming = Boolean(ctx.resume && (ctx.resume.sessionId || ctx.resume.kind !== undefined));
-        const isContinueConfirm = ctx.resume?.kind === "continue" && !ctx.resume.sendMessage;
+        const resumeKind = ctx.resume?.kind;
+        // 重观察恢复（user_confirmation）：用户在 GUI 处理完等待项后 turn 自行继续，
+        // 本轮不发送任何消息，只重连 CDP 观察 GUI 内运行至终态。
+        const isReobserve = resumeKind === "continue" && ctx.resume?.reobserve === true;
+        const isContinueConfirm = resumeKind === "continue" && !ctx.resume?.sendMessage;
+        // continue-confirm 仅出现在 login_required 恢复：登录前任务尚未发送、项目尚未绑定，
+        // 须走全新派发（新会话 + 绑定项目 + 发送初始任务书）；其余恢复轮复用当前会话。
+        const resuming = isReobserve || (resumeKind !== undefined && !isContinueConfirm);
+        // 重派护栏（issue #6 连锁风险）：受管实例上仍有未停止的运行时先尽力停止；
+        // 仍不空闲则拒绝派发——宁可 fail-closed，也不让新旧 turn 在同一应用内交叠。
+        // 重观察轮例外：停止按钮可见正是被观察 turn 暂停的表现。
+        if (!isReobserve) {
+            const busyStop = await stopGuiTurn(cdp, gui, deps, logger);
+            if (busyStop.clicked)
+                logger.warn("[codex] 派发前发现实例仍有运行，已点击停止并恢复空闲");
+            if (!busyStop.idle)
+                return result({
+                    hardFailure: true,
+                    endReason: "instance_busy",
+                    error: "受管 Codex 实例上存在未停止的运行（已尝试点击停止未果）；请在 Codex 窗口人工处理后重试，避免新旧任务交叠",
+                });
+        }
         // ---- 步骤 3：创建会话 + 绑定/新建项目 ----
         if (!resuming) {
             if (gui.freshSession && !(await cdp.click("newChat")))
@@ -245,66 +267,80 @@ export async function runCodexTask(args) {
         const permOk = await ensurePermission(cdp, gui, deps, logger);
         if (!permOk.ok)
             return result({ hardFailure: true, error: permOk.error, endReason: "permission_unknown" });
-        // ---- 步骤 4/5：输入指令 + 发送 ----
-        if (isContinueConfirm)
-            logger.info("[codex] 用户确认文本不发送给模型；环境复检通过后发送原始任务书");
-        // 返修轮：ctx.feedback 即 fix-loop 生成的修复指令（引用 codex-fix-r<N>.md）；
-        // 续答轮：ctx.resume.message 是用户答复。两者都不应退回重发原始任务书。
-        const message = resuming
-            ? ctx.resume?.sendMessage
-                ? (ctx.resume.message?.trim() || ctx.feedback?.trim() || ctx.task)
-                : ctx.task
-            : buildInitialPrompt({
-                task: ctx.task,
-                context: ctx.context,
-                planDoc: ctx.planDoc,
-                designSystem: ctx.designSystem,
-                refs: safeRefs(ctx),
-            });
-        const attempt = ctx.resume?.kind === "continue"
-            ? `continue:${createHash("sha256").update(ctx.resume.message ?? "confirmed").digest("hex").slice(0, 8)}`
-            : (ctx.resume?.kind ?? "initial");
-        const marker = `【tianshu:${ctx.taskId}:r${ctx.round}:${attempt}】`;
-        const beforeText = (await cdp.poll()).conversationText;
-        await cdp.typeText(marker + message);
-        const typed = await cdp.inputText();
-        if (!typed.includes(marker))
-            return result({ hardFailure: true, error: "Codex 输入框回读不一致，未发送", endReason: "input_mismatch" });
-        await cdp.sendMessage();
-        // 发送确认：任一直接证据成立即认定已提交——
-        //   a) 输入框不再含标记（文本已离开输入框）
-        //   b) 对话区出现标记
-        //   c) 出现运行信号（停止按钮）
-        // 注意：无论确认与否都**不会重发**（重发风险高于误判），故宁可放宽确认条件；
-        // 真机教训：对话区选择器曾命中空壳 main，导致明明发送成功却报 send_unknown。
-        let seenMessage = beforeText.includes(marker);
-        let seenCleared = false;
-        let seenRunning = false;
-        const confirmAttempts = Math.ceil(Math.min(60_000, Math.max(5_000, ctx.taskTimeoutMs)) / 250);
-        const confirmed = () => seenCleared || seenMessage || seenRunning;
-        for (let i = 0; i < confirmAttempts && !confirmed(); i++) {
-            // eslint-disable-next-line no-await-in-loop
-            await deps.sleep(250);
-            // eslint-disable-next-line no-await-in-loop
-            const [poll, input] = await Promise.all([cdp.poll(), cdp.inputText()]);
-            seenMessage ||= poll.conversationText.includes(marker);
-            seenCleared ||= !input.includes(marker);
-            seenRunning ||= poll.stopVisible;
+        // ---- 步骤 4/5：输入指令 + 发送（重观察轮跳过：不发送任何消息）----
+        if (isReobserve) {
+            logger.info("[codex] 重观察恢复（user_confirmation）：跳过输入与发送，直接观察 GUI 内运行至终态");
+        }
+        else {
+            if (isContinueConfirm)
+                logger.info("[codex] 用户确认文本不发送给模型；环境复检通过后发送原始任务书");
+            // 返修轮：ctx.feedback 即 fix-loop 生成的修复指令（引用 codex-fix-r<N>.md）；
+            // 续答轮：ctx.resume.message 是用户答复。两者都不应退回重发原始任务书。
+            const message = resuming
+                ? ctx.resume?.sendMessage
+                    ? (ctx.resume.message?.trim() || ctx.feedback?.trim() || ctx.task)
+                    : ctx.task
+                : buildInitialPrompt({
+                    task: ctx.task,
+                    context: ctx.context,
+                    planDoc: ctx.planDoc,
+                    designSystem: ctx.designSystem,
+                    refs: safeRefs(ctx),
+                });
+            const attempt = ctx.resume?.kind === "continue"
+                ? `continue:${createHash("sha256").update(ctx.resume.message ?? "confirmed").digest("hex").slice(0, 8)}`
+                : (ctx.resume?.kind ?? "initial");
+            const marker = `【tianshu:${ctx.taskId}:r${ctx.round}:${attempt}】`;
+            const beforeText = (await cdp.poll()).conversationText;
+            await cdp.typeText(marker + message);
+            const typed = await cdp.inputText();
+            if (!typed.includes(marker))
+                return result({ hardFailure: true, error: "Codex 输入框回读不一致，未发送", endReason: "input_mismatch" });
+            await cdp.sendMessage();
+            // 发送确认：任一直接证据成立即认定已提交——
+            //   a) 输入框不再含标记（文本已离开输入框）
+            //   b) 对话区出现标记
+            //   c) 出现运行信号（停止按钮）
+            // 注意：无论确认与否都**不会重发**（重发风险高于误判），故宁可放宽确认条件；
+            // 真机教训：对话区选择器曾命中空壳 main，导致明明发送成功却报 send_unknown。
+            let seenMessage = beforeText.includes(marker);
+            let seenCleared = false;
+            let seenRunning = false;
+            const confirmAttempts = Math.ceil(Math.min(60_000, Math.max(5_000, ctx.taskTimeoutMs)) / 250);
+            const confirmed = () => seenCleared || seenMessage || seenRunning;
+            for (let i = 0; i < confirmAttempts && !confirmed(); i++) {
+                // eslint-disable-next-line no-await-in-loop
+                await deps.sleep(250);
+                // eslint-disable-next-line no-await-in-loop
+                const [poll, input] = await Promise.all([cdp.poll(), cdp.inputText()]);
+                seenMessage ||= poll.conversationText.includes(marker);
+                seenCleared ||= !input.includes(marker);
+                seenRunning ||= poll.stopVisible;
+            }
+            if (!confirmed())
+                return result({
+                    hardFailure: true,
+                    error: `Codex 发送结果无法确认（用户消息=${seenMessage}，输入清空=${seenCleared}，运行信号=${seenRunning}）；不重复发送`,
+                    endReason: "send_unknown",
+                });
+            logger.info(`[codex] 指令已确认发送（对话区=${seenMessage}，输入清空=${seenCleared}，运行信号=${seenRunning}）`);
         }
-        if (!confirmed())
-            return result({
-                hardFailure: true,
-                error: `Codex 发送结果无法确认（用户消息=${seenMessage}，输入清空=${seenCleared}，运行信号=${seenRunning}）；不重复发送`,
-                endReason: "send_unknown",
-            });
-        logger.info(`[codex] 指令已确认发送（对话区=${seenMessage}，输入清空=${seenCleared}，运行信号=${seenRunning}）`);
         // ---- 步骤 6：运行检测 ----
         const deadline = started + ctx.taskTimeoutMs;
         let state = initialCodexState();
+        if (isReobserve) {
+            // 重观察轮：被观察的 turn 此前已确认在运行。种子 sawRunning 规避
+            // 「turn 在恢复前已完成 → 从未见运行信号 → 判不了 finished → 误落 idle_timeout」。
+            state.sawRunning = true;
+        }
         let lastProgress = 0;
         for (;;) {
-            if (opts.signal?.aborted)
-                return result({ killed: true, endReason: "aborted" });
+            // 取消（issue #6）：不止退出 MCP 等待循环，还要尽力点击 GUI 停止按钮并等待空闲，
+            // 结果经 guiStop 上报，由编排方在终态文案中如实反映。
+            if (opts.signal?.aborted) {
+                const guiStop = await stopGuiTurn(cdp, gui, deps, logger);
+                return result({ killed: true, endReason: "aborted", guiStop });
+            }
             if (Date.now() >= deadline)
                 return result({
                     timeout: true,
@@ -315,7 +351,7 @@ export async function runCodexTask(args) {
             await deps.sleep(gui.pollIntervalMs);
             // eslint-disable-next-line no-await-in-loop
             const poll = await cdp.poll();
-            const verdict = judgeCodexPoll(poll, state, gui.stableRounds, gui.idleTimeoutMs);
+            const verdict = judgeCodexPoll(poll, state, gui.stableRounds, gui.idleTimeoutMs, Date.now(), gui.stallTimeoutMs);
             state = verdict.state;
             if (Date.now() - lastProgress >= gui.progressIntervalMs) {
                 const note = `Codex 进度：${verdict.kind}；运行证据=${verdict.evidence}；对话哈希=${state.hash}；稳定轮=${state.stable}`;
@@ -330,6 +366,13 @@ export async function runCodexTask(args) {
                     pendingQuestion: "Codex 需要登录，请在窗口中完成登录后调用 continue_task 确认。",
                     session: { boundProjectPath: ctx.projectPath, model: spec.model, permissionMode: gui.defaultPermissionMode },
                 });
+            if (verdict.kind === "needs_user")
+                return result({
+                    endReason: "needs_user",
+                    needsUserKind: "user_confirmation",
+                    pendingQuestion: "Codex 停止按钮持续可见且对话内容长时间未变化，疑似在等待用户确认（方案确认/订阅确认等）。请在 Codex 窗口完成处理后调用 continue_task(taskId, message=已处理说明) 恢复；恢复后仅重新接入观察，不会发送消息。",
+                    session: { boundProjectPath: ctx.projectPath, model: spec.model, permissionMode: gui.defaultPermissionMode },
+                });
             if (verdict.kind === "idle_timeout")
                 return result({ endReason: "idle_timeout", error: "Codex 空闲超时；已停止 MCP 等待并保留现场" });
             if (verdict.kind === "finished")
@@ -368,6 +411,34 @@ function safeRefs(ctx) {
         return [];
     }
 }
+/**
+ * 尽力停止 GUI 内正在运行的 turn（issue #6）：
+ * 点击界面停止按钮（trusted 点击），并在 cancelWaitMs 内轮询确认停止按钮消失（GUI 空闲）。
+ * 不抛异常：CDP 不可用等情况下返回 clicked=false/idle=false，由调用方如实落文案。
+ * idle=false 时 GUI 内运行可能仍在继续——终态文案必须明示，不得谎报已停止。
+ */
+async function stopGuiTurn(cdp, gui, deps, logger) {
+    try {
+        const first = await cdp.poll();
+        if (!first.stopVisible)
+            return { clicked: false, idle: true };
+        const clicked = await cdp.click("stopButton");
+        logger.info(`[codex] 取消：${clicked ? "已点击" : "未能点击"} GUI 停止按钮，等待界面空闲（≤${gui.cancelWaitMs}ms）`);
+        const deadline = Date.now() + gui.cancelWaitMs;
+        for (;;) {
+            await deps.sleep(500);
+            if (Date.now() >= deadline)
+                return { clicked, idle: false };
+            const poll = await cdp.poll();
+            if (!poll.stopVisible)
+                return { clicked, idle: true };
+        }
+    }
+    catch (e) {
+        logger.warn(`[codex] 取消时停止 GUI 运行失败：${e instanceof Error ? e.message : String(e)}`);
+        return { clicked: false, idle: false };
+    }
+}
 /**
  * 新建项目流程（截图 2→5）：
  * 打开项目选择层 → 新建项目 → 点源文件夹中心空白区 → 原生对话框键盘填路径 →

package/dist/agents/codex/selectors.d.ts

@@ -32,7 +32,7 @@ export interface CodexSelectorSpec {
     verifiedVersion: string;
     note: string;
 }
-export type CodexSelectorKey = "chatInput" | "sendButton" | "stopButton" | "newChat" | "projectSection" | "projectPickerTrigger" | "addProject" | "projectItem" | "newProjectMenuItem" | "sourceFolderArea" | "createProjectButton" | "modelTrigger" | "reasoningSlider" | "modelMenuItem" | "menuItem" | "permissionTrigger" | "permissionOption" | "loginIndicator" | "messageArea";
+export type CodexSelectorKey = "chatInput" | "sendButton" | "stopButton" | "newChat" | "projectSection" | "projectPickerTrigger" | "addProject" | "projectItem" | "newProjectMenuItem" | "sourceFolderArea" | "createProjectButton" | "modelTrigger" | "reasoningSlider" | "modelMenuItem" | "menuItem" | "permissionTrigger" | "permissionOption" | "loginIndicator" | "userGate" | "messageArea";
 export declare const CODEX_SELECTORS: Record<CodexSelectorKey, CodexSelectorSpec>;
 /** 合并 profile 覆盖后的 CSS 候选（去重，覆盖优先） */
 export declare function cssCandidates(key: CodexSelectorKey, overrides?: Record<string, string>): string[];

package/dist/agents/codex/selectors.js

@@ -25,10 +25,25 @@ export const CODEX_SELECTORS = {
     },
     stopButton: {
         primary: 'button[aria-label*="停止"]',
-        fallbacks: ['button[aria-label*="Stop" i]', 'button[aria-label*="取消"]'],
+        fallbacks: ['button[aria-label*="Stop" i]'],
         ariaLabels: ["停止", "Stop"],
         verifiedVersion: "26.903.x",
-        note: "权威运行信号；生成期间替代发送按钮（待真机运行确认）",
+        // issue #5 实测教训：fallback 曾含 button[aria-label*="取消"]，但「等待用户确认」
+        // （方案确认卡/订阅结账页）界面自带「取消」按钮，会把 turn 暂停误判为运行中，
+        // 造成完成判定死锁——已移除该过匹配。若某版本停止按钮文案漂移，用
+        // gui.selectors.stopButton 热修复。
+        note: "权威运行信号；生成期间替代发送按钮。不要加入「取消」等宽泛文案（等待用户界面会误命中）",
+    },
+    userGate: {
+        // issue #5：等待用户界面检测（结账页/方案确认卡等）。默认候选为空 = 禁用；
+        // 仅当 agent-profiles.json 配置 gui.selectors.userGate 后启用（覆盖优先）。
+        // 参考值（2026-09 实测版式，未内置）：[class*="embedded-checkout"]、
+        // [class*="approval"]、[role="dialog"][class*="confirm"]——配置前请真机核对，
+        // 误配会把正常运行误判为 needs_user（可恢复，非终态）。
+        primary: "",
+        fallbacks: [],
+        verifiedVersion: "未内置（按配置启用）",
+        note: "「等待用户」界面检测；默认禁用，配置 gui.selectors.userGate 后 poll().userGateVisible 才可能为真",
     },
     newChat: {
         primary: 'button.sidebar-item',