@ai-setting/roy-task-plugin 0.7.11 → 0.7.13

package/dist/claude-plugin/agents/roy.md

@@ -62,13 +62,12 @@ the user sees.
 
 4. TRACK
    - Update progress (0-100%) as the work advances
-   - Update status: todo → active → completed
+   - Update status: todo → active
    - Record `current_status` with human-readable progress
 
 5. RECORD — operation records (see Operation Discipline below)
 
-6. COMPLETE — `task_complete` after item-by-item verification
-   (see Complete Discipline below)
+6. COMPLETE — 收尾：用 `task_complete` after item-by-item verification (see Complete Discipline below)
 
 ### Goals 子项拆分规则
 
@@ -158,12 +157,19 @@ Before calling `task_complete`, you MUST:
      `[TASK_COMPLETION_HINT]`.
    - **If you receive a [TASK_COMPLETION_HINT]**, you MUST verify it
      (核实义务): re-read the task via `task_get`, then do exactly one of:
-     (a) 确认未完成 → `task_update(task_id=<id>, status=todo)` to **reopen**
-         the task and continue the work; or
-     (b) 确认已完成 → `task_operation_create` (milestone_type=decision,
-         milestone_title=<一行结论>) **state why** the sub-items are actually
-         met (说明理由).
+     (a) 确认未完成 → **重新委托**（用你的委托工具 + 同一 sub-session 续跑，
+         在指令里写明"目标尚未达成，需要补 X/Y/Z"），由 sub-agent 用
+         `task_update(status=active)` 重开并继续推进；若你**自己就是执行方**
+         （有 `task_update` 权限），则直接 `task_update(status=todo)` 重开；或
+     (b) 确认已完成 → **用你手上有权限的写工具**落一条 `decision` 类操作记录
+         （`task_operation_create`，milestone_type=decision，milestone_title=<一行结论>）
+         说明子项实际已达成（说明理由）。若你没有该工具的权限（验收方场景），
+         就通过你的**委托工具**让 sub-agent 代写这条记录，或在 `task_complete`
+         的 `deliverable_storage_path` / 最终汇报里明确写出核实结论与证据。
      Never ignore it (不允许无视).
+     ⚠️ **核实义务的两条路径都依赖写权限**（`task_update` / `task_operation_create`）。
+     若这些工具对你**不可用**（如验收方不持有执行类工具），必须**改用委托**把动作
+     交回给有权限的 sub-agent 执行 —— 不要试图调用不可用的工具（会被拦掉并浪费一轮迭代）。
    - If the goal and delivery mismatch **without** a hint, either:
      (a) extend the task via `task_update`, or
      (b) record the discrepancy via `task_operation_create`
@@ -221,6 +227,76 @@ if it is not in the task store, it is not tracked.
 - Report the task id and its state whenever you finish a step.
 - If a task is blocked, mark it (`task_update(status="paused")`) and record a
   `problem` milestone explaining the blocker instead of going silent.
+
+## Milestone discipline (Claude runtime)
+
+The task card renders **your** milestones. A run that calls tools but
+records nothing leaves the card empty, and the user sees a failed task with
+no trace of the work. Measured failure: 67 tool calls, 2 automatic hooks,
+0 real milestones, then the run was killed and the card froze in a failed
+state. Read this section as binding.
+
+### Record per stage, immediately
+
+- Every time you finish a **阶段** — a sub-goal, an investigation, a file
+  written, a test that passed, a decision, a blocker — call
+  `task_operation_create` **立即**, in that same turn.
+- Do **not** batch. A milestone written after six tool calls reads as
+  retrospective filler; the point is that the card shows the work *as it
+  happens*.
+- If a single tool call produced a stage-level result, that call is
+  followed by exactly one milestone — no more, no less.
+- Long-running work (> 5 minutes) still records as it goes, exactly as the
+  shared contract requires.
+
+### The shape of a milestone
+
+`milestone_title` — a **短语**, ≤ 20 字, verb-first, naming what was
+locked down. Not a sentence, not a label like "progress".
+
+- ✅ `泄漏源锁定`, `测试全绿`, `缓存层落地`, `回滚路径确认`
+- ❌ `进度更新`, `继续处理`, `做了一些工作`, `阶段完成`
+
+Those ❌ examples are **空壳** milestones: they carry no information about
+what changed, so they are worse than useless — they make the card look
+busy while hiding the work. Never write a title like those.
+
+`milestone_description` — a dense **技术叙述** of the state you reached.
+Name the concrete things, so a reader can reconstruct the work without
+re-running it:
+
+- the **文件路径** you wrote or read
+- the **函数名** / symbol you changed or traced
+- the **命令** you ran and its result
+- the numbers: pass/fail counts, line counts, exit codes, sizes, timings
+
+Example (title + description):
+
+```
+milestone_title: "泄漏源锁定"
+milestone_description: "test_workflow_error_handling 的生成器被放弃 → registry 由 GC 延迟回收；泄漏路径锁定在 WorkflowRegistry.dispose()，packages/core/src/registry.ts:412"
+```
+
+`process_description` (100–500 字符) — how it was reached (**如何达到**):
+the strategy and the tool steps. It must **not** repeat the description —
+the description is the *state*, the process is the *route*. Repeating
+one in the other is a second ❌.
+
+### Tool-call budget
+
+If you have made several **连续的工具调用** without recording a
+milestone, the next action is `task_operation_create` — not another
+tool call. Two, three tool calls in a row is normal exploration; a long
+streak without a milestone is the failure mode measured above. When the
+streak is getting long, write down what you have already established, then
+continue.
+
+### What good looks like
+
+For a task with 3–4 stages you should end up with **3–4 hand-written
+milestones** in the card — not 2 automatic hooks and nothing else. The
+automatic `收到消息` / `Task 完成` hooks are not a substitute for yours.
+
 ## Tool surface on Claude Code
 
 The `task_*` tools are served by the **`roy-task` MCP server** this runtime

package/dist/claude-plugin/mcp/bridge.mjs

@@ -21,7 +21,8 @@ import {
 import { SQLiteTaskStore } from "@ai-setting/roy-agent-core/env/task/storage";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { createNotifyDispatcher } from "./task-notify-hooks.mjs";
+import { createNotifyDispatcher, taskIdFromResult } from "./task-notify-hooks.mjs";
+import { withGoalCheck } from "./goal-check.mjs";
 
 /** Raised when a tool call cannot be served. */
 export class BridgeError extends Error {
@@ -46,8 +47,16 @@ export function defaultTaskDbPath() {
  * call runs inside the injected EnvContext — so `task_create` now opens
  * a card in Feishu, `task_update` patches it, `task_complete` closes it.
  *
+ * Task #5035: the **goal check**. A `TaskStoreBackend` has no hook chain, so
+ * core's `task:after.complete` judgement never ran in this process — an agent
+ * calling its own `task_complete` got no acceptance at all. `task_complete`
+ * now runs the judge right after the completion (see `goal-check.mjs`): a
+ * FAIL appends `[TASK_COMPLETION_HINT]` to the **same** tool result the agent
+ * is already reading, so it can verify and redo in the next turn. Completion
+ * semantics are untouched (advisory only, fail-open).
+ *
  * @param {string} dbPath task store path
- * @param {{ cardNotifier?: object }} deps test seams (fake notifier)
+ * @param {{ cardNotifier?: object, decisionPort?: object, goalCheckTimeoutMs?: number }} deps test seams
  */
 export async function createServer(dbPath = defaultTaskDbPath(), deps = {}) {
   const store = new SQLiteTaskStore(dbPath);
@@ -61,16 +70,26 @@ export async function createServer(dbPath = defaultTaskDbPath(), deps = {}) {
   // Task #4692: fire the task:after.* hooks around every tool call. The
   // wiring lives in task-notify-hooks.mjs; core owns the hook itself.
   const notify = await createNotifyDispatcher({ backend, deps });
-  const callToolWithHooks = async (name, args = {}) => {
-    const result = await server.callTool(name, args);
-    await notify.fire(name, args, result);
-    return result;
-  };
+
+  // Task #5035: after `task_complete` succeeds, run core's goal check and
+  // hand a FAIL back to the agent on the SAME tool result. The rule lives in
+  // goal-check.mjs — this adapter only supplies the seams.
+  const run = withGoalCheck({
+    callTool: async (name, args) => {
+      const result = await server.callTool(name, args);
+      await notify.fire(name, args, result);
+      return result;
+    },
+    backend,
+    taskIdFromResult,
+    deps,
+    sessionId: process.env.ROY_TASK_SESSION_ID || "claude-mcp",
+  });
 
   // The hooks (stop-check) need the *backend*, not the MCP surface: they
   // ask "is there an open task?" — a task-semantics question, answered by
   // core's backend, not by the JSON-RPC layer.
-  return { ...server, backend, store, callTool: callToolWithHooks };
+  return { ...server, backend, store, callTool: run };
 }
 
 /**

package/dist/claude-plugin/mcp/goal-check.mjs

@@ -0,0 +1,452 @@
+/**
+ * Task #5035 — the MCP server's **goal check** wiring.
+ *
+ * ## The hole this closes
+ *
+ * Core's completion judgement (`LayaCompletionPlugin`, the "goal vs.
+ * deliverables" judge) is registered by roy-agent **inside its own process**
+ * (`environment.ts:490` → `registerLayaCompletionTaskHook(taskComponent)`),
+ * on `TaskComponent`'s hook chain (`task:after.complete`).
+ *
+ * The plugin's MCP server has no `TaskComponent`: it binds core's task tools
+ * to a `TaskStoreBackend` (`TaskBackend`). A `TaskBackend` has **no hook
+ * chain**, so `task:after.complete` never fires and the judge never runs.
+ *
+ * Measured consequence: an agent driving the lifecycle over MCP calls **its
+ * own** `task_complete` and gets `Task completed: #N` back with no
+ * acceptance at all.
+ *
+ * ## What this module does (and deliberately does not do)
+ *
+ * The judgement is **not** handed to another actor. The daemon stays out of
+ * acceptance entirely, the agent keeps its own `task_complete` tool, its
+ * prompt and tool set are untouched. The judge is wired onto the tool call
+ * the agent already makes:
+ *
+ * ```
+ *   agent → task_complete (unchanged MCP tool)
+ *            └─ backend.completeTask            (completion semantics: unchanged)
+ *            └─ runGoalCheck()                  (this module)
+ *                 ├─ PASS → result returned as-is
+ *                 └─ FAIL → hint in task.context.completion_hint
+ *                        + "[TASK_COMPLETION_HINT]" appended to the SAME
+ *                          tool result, so the agent sees it in this turn
+ *                          and can redo the work, then complete again
+ * ```
+ *
+ * ## Why an adapter, not a TaskComponent
+ *
+ * The judge calls 4 methods (`listOperations` / `updateTask` /
+ * `createOperation` / `updateTaskContext`). `TaskBackend` has the first three
+ * and **no** `updateTaskContext` — it only has `updateTask({ context })`,
+ * a full-column replace. So the adapter synthesises the missing method by
+ * **read-merge-write**, which keeps `updateTaskContext`'s semantics (merge,
+ * never clobber) and, crucially, avoids the nested-`updateTask` side effects
+ * the judge was written to avoid (see `laya-completion-plugin.ts:684`, Task
+ * #4776 review MINOR-1).
+ *
+ * ## Cross-repo note
+ *
+ * Everything semantic lives in core (`@ai-setting/roy-agent-core/env/task/
+ * plugins`): the plugin class, the hint renderer, the threshold, the anchor
+ * token. This module only adapts shapes and timing — the same discipline as
+ * `task-notify-hooks.mjs` (Task #4692), and for the same reason: the plugin
+ * must not carry a second copy of roy's semantics.
+ */
+
+/** The hint anchor, re-exported from core (single source of truth). */
+export const GOAL_CHECK_HINT_ANCHOR = "TASK_COMPLETION_HINT";
+
+/** How long the judge may take before the tool call stops waiting. */
+const DEFAULT_GOAL_CHECK_TIMEOUT_MS = 15_000;
+
+/**
+ * Is the goal check enabled for this process?
+ *
+ * **On by default.** The whole point of Task #5035 is that an MCP-driven task
+ * gets accepted; an off-by-default referee would reproduce the hole. An
+ * operator can opt out with `ROY_TASK_GOAL_CHECK_ENABLED=0` (tests use it, and
+ * an air-gapped host with no decision endpoint can too — though the judge is
+ * fail-open anyway, so opting out is rarely needed).
+ */
+export function goalCheckEnabled() {
+  const v = process.env.ROY_TASK_GOAL_CHECK_ENABLED;
+  if (v === undefined || v === "") return true;
+  return !(v === "0" || v === "false");
+}
+
+/** The judge deadline (ms). */
+export function goalCheckTimeoutMs() {
+  const raw = process.env.ROY_TASK_GOAL_CHECK_TIMEOUT_MS;
+  const n = raw === undefined ? NaN : Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_GOAL_CHECK_TIMEOUT_MS;
+}
+
+/**
+ * Adapt a `TaskBackend` to the 4-method shape core's judge expects.
+ *
+ * The first three pass straight through. `updateTaskContext` is synthesised
+ * with a read-merge-write, because:
+ *
+ * 1. `TaskBackend` has no such method;
+ * 2. `updateTask({ context })` **replaces** the whole JSON column, so a
+ *    blind write would silently drop `deliverable_storage_path`,
+ *    `project_path`, and every other key the task already carried.
+ *
+ * @param backend core `TaskBackend` (i.e. `TaskStoreBackend`)
+ * @param {{ completedTask?: object }} options
+ *   `completedTask` enables the **operation-chain correction** (see
+ *   `hideAutoCompletedOperation`): the MCP host runs the judge *after*
+ *   `backend.completeTask()` returned, while core's own AFTER_COMPLETE fires
+ *   *inside* the update (before the `completed` operation is written). Core's
+ *   judge was trained on the latter shape, so passing it the former would be
+ *   an out-of-distribution input — measured: the same task scores
+ *   FAIL@0.982 (core shape) vs PASS@0.124 (post-write shape).
+ */
+export function adaptTaskBackendForJudge(backend, options = {}) {
+  const readContext = async (taskId) => {
+    const task = await backend.getTask(taskId);
+    const raw = task && task.context;
+    if (!raw || typeof raw !== "string") return {};
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    } catch {
+      /* a corrupt context must not block the merge — start from {} */
+    }
+    return {};
+  };
+
+  const listOperations = async (opts) => {
+    const ops = await backend.listOperations(opts);
+    return options.completedTask
+      ? hideAutoCompletedOperation(ops, options.completedTask)
+      : ops;
+  };
+
+  return {
+    listOperations,
+    updateTask: (id, input) => backend.updateTask(id, input),
+    createOperation: (input) => backend.createOperation(input),
+
+    /**
+     * Merge the given JSON **into** the task's existing context.
+     *
+     * Mirrors `TaskComponent.updateTaskContext` (merge semantics), implemented
+     * on top of the backend primitive without firing the nested-update side
+     * effects the judge's own comments warn about.
+     *
+     * @param {number|string} taskId
+     * @param {string} contextJson the full next context (what the judge passes)
+     */
+    async updateTaskContext(taskId, contextJson) {
+      const current = await readContext(taskId);
+      let incoming = {};
+      try {
+        const parsed = JSON.parse(contextJson);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) incoming = parsed;
+      } catch {
+        return undefined; // unparseable → do nothing (the judge treats no-op as fine)
+      }
+      const merged = { ...current, ...incoming };
+      return backend.updateTask(taskId, { context: JSON.stringify(merged) });
+    },
+  };
+}
+
+/**
+ * Restore the operation-chain **shape core's judge was trained on**.
+ *
+ * `TaskStoreBackend.completeTask` writes a `completed` operation
+ * (`milestoneTitle: "Completed: <title>"`, description = the deliverable line
+ * or `"Task completed"`) **after** it fires nothing — whereas `TaskComponent`
+ * fires `task:after.complete` *before* writing that same operation (see the
+ * timing note in `laya-completion-plugin.ts`: 「AFTER_COMPLETE 触发时
+ * `completed` operation 尚未写入」).
+ *
+ * This host can only judge after the write, so the auto-generated record is
+ * removed to reproduce the in-core view bit for bit. Measured cost of *not*
+ * doing it: the same task judged FAIL_INCOMPLETE @0.982 (core shape) versus
+ * PASS_COMPLETED @0.124 (post-write shape) — i.e. the trailing `Completed: …`
+ * / `Task completed` pair reads as "done" to the model and poisons the gate.
+ *
+ * Only the **one** record `completeTask` itself produces is removed: a
+ * `completed` operation the *agent* wrote earlier is real evidence and stays.
+ *
+ * @param {Array<object>} operations operations as returned by the backend
+ * @param {{ title?: string }} completedTask the task `completeTask` returned
+ */
+export function hideAutoCompletedOperation(operations, completedTask) {
+  if (!Array.isArray(operations) || operations.length === 0) return operations;
+  const expected = `Completed: ${completedTask?.title ?? ""}`;
+
+  /**
+   * A task can be completed **more than once** (the hint round trip: FAIL →
+   * the agent redoes the work → `task_update(todo)` → `task_complete` again),
+   * and each `completeTask` writes its own record. But only the record from
+   * **this** attempt does not exist from core's point of view — an earlier
+   * attempt's record is genuine history that core *would* have seen.
+   *
+   * So exactly **one** record is hidden: the newest auto record. Measured why
+   * the distinction matters:
+   *
+   * | chain on the retry | verdict |
+   * |---|---|
+   * | prior `Completed:` kept, current hidden | PASS @0.93 |
+   * | **all** `Completed:` records hidden | FAIL @0.22–0.83 (unstable) |
+   *
+   * i.e. hiding history makes the model disbelieve an all-done checklist.
+   *
+   * `TaskBackend.listOperations` may return either direction, so "newest" is
+   * decided by timestamp, not by array position.
+   */
+  const isAuto = (op) => {
+    if (!op) return false;
+    if (String(op.milestoneTitle ?? "") !== expected) return false;
+    const desc = String(op.milestoneDescription ?? "");
+    return (
+      desc === "Task completed" ||
+      desc.startsWith("Deliverable:") ||
+      desc.startsWith("交付物：") ||
+      desc.startsWith("交付物:")
+    );
+  };
+
+  let newestIdx = -1;
+  let newestTs = -Infinity;
+  for (let i = 0; i < operations.length; i += 1) {
+    if (!isAuto(operations[i])) continue;
+    const ts = new Date(operations[i]?.timestamp ?? 0).getTime();
+    const cmp = Number.isFinite(ts) ? ts : -Infinity;
+    if (cmp >= newestTs) {
+      newestTs = cmp;
+      newestIdx = i;
+    }
+  }
+  if (newestIdx < 0) return operations;
+  return operations.filter((_, i) => i !== newestIdx);
+}
+
+/**
+ * Run the goal check for one completed task.
+ *
+ * **Never throws** and never changes completion semantics — the judge is
+ * advisory (core's own contract: AFTER_COMPLETE fires *after* the task is
+ * already `completed`; a hint can only be appended, never a rollback).
+ *
+ * @param {{ decisionPort?: object, timeoutMs?: number, logger?: object }} deps
+ * @param {object} backend core `TaskBackend`
+ * @param {object} completedTask the task returned by `backend.completeTask`
+ * @param {{ sessionId?: string }} options
+ * @returns {Promise<string|undefined>} the hint text when the judge said FAIL
+ */
+export async function runGoalCheck(deps, backend, completedTask, options = {}) {
+  if (!goalCheckEnabled()) return undefined;
+  if (!completedTask || !completedTask.id) return undefined;
+
+  const log = deps.logger ?? silentLogger();
+  let hint;
+
+  try {
+    const pluginsMod = await import("@ai-setting/roy-agent-core/env/task/plugins");
+
+    // ⚠️ The goal-check API is new in core (Task #5035). A plugin installed
+    // against an OLDER published core simply does not have it — that must
+    // degrade to "no judge", not to a crash on every completion.
+    // (`bun run core:sync` pins the version this repo is developed against.)
+    if (typeof pluginsMod.LayaCompletionPlugin !== "function") {
+      log.warn(
+        `[goal-check] core has no LayaCompletionPlugin export (needs roy-agent-core with Task #5035) — skipping`,
+      );
+      return undefined;
+    }
+
+    const adapter = adaptTaskBackendForJudge(backend, { completedTask });
+
+    // ⚠️ Inject the decision port when the host supplied one (tests / a host
+    // that resolves auth itself). Otherwise let core resolve it from
+    // `~/.roy-agent/auth.json` (providers["laya-goal-decision"]) exactly as
+    // roy-agent does in its own process.
+    const plugin = deps.decisionPort
+      ? new pluginsMod.LayaCompletionPlugin({ decisionPort: deps.decisionPort })
+      : new pluginsMod.LayaCompletionPlugin({
+          ...(deps.timeoutMs ? { timeoutMs: deps.timeoutMs } : {}),
+          ...(deps.authPath ? { authPath: deps.authPath } : {}),
+        });
+
+    // The plugin reads the hint it wrote through `ctx.task`; it also needs
+    // `terminalStatus` so its own "only completed" filter passes.
+    const ctx = {
+      task: completedTask,
+      changes: { status: "completed", progress: 100 },
+      terminalStatus: "completed",
+      sessionId: options.sessionId ?? "mcp-goal-check",
+      tagService: undefined,
+    };
+
+    // ⚠️ Read the verdict back by **comparing before/after**, not by
+    // "is a hint present". A task can be completed several times (FAIL →
+    // redo → complete again): the FIRST attempt's hint stays in
+    // `task.context.completion_hint` forever, so a presence test reports a
+    // stale FAIL on every later PASS (measured: the retry ATTACHED AN OLD
+    // HINT even though this round's verdict was PASS_COMPLETED @0.95).
+    const hintBefore = await readCompletionHint(backend, completedTask.id);
+
+    await withDeadline(
+      plugin.execute(ctx, adapter),
+      deps.timeoutMs ?? goalCheckTimeoutMs(),
+    );
+
+    const hintAfter = await readCompletionHint(backend, completedTask.id);
+    if (hintAfter && hintAfter !== hintBefore) hint = hintAfter;
+    if (hint) {
+      log.info(`[goal-check] task #${completedTask.id}: FAIL — hint attached to tool result`);
+    } else {
+      log.debug?.(`[goal-check] task #${completedTask.id}: PASS (no hint)`);
+    }
+  } catch (err) {
+    // fail-open: the judge is advisory, so a broken judge is a silent judge.
+    log.warn(
+      `[goal-check] task #${completedTask?.id} judgement skipped (fail-open): ${
+        err && err.message ? err.message : String(err)
+      }`,
+    );
+    return undefined;
+  }
+
+  return hint;
+}
+
+/**
+ * Wrap a tool caller so `task_complete` also runs the goal check.
+ *
+ * This is the **whole** wiring, kept here rather than in `bridge.mjs` so the
+ * bridge stays the thin transport adapter `claude-bridge-thin.test.ts` pins
+ * (< 140 lines). The bridge contributes one call; every rule about *when* and
+ * *how* the judge runs lives in this module.
+ *
+ * `callTool` is the bare MCP tool executor (already bound to the backend).
+ * The returned function has the same signature and behaviour, plus: on a
+ * successful `task_complete` whose verdict is FAIL, the hint is appended to
+ * the result the agent reads.
+ *
+ * ⚠️ Everything here is advisory and runs **after** the tool succeeded. The
+ * completion is already committed, so any failure inside the check must leave
+ * that result untouched — a referee that cannot read the file must not void
+ * the score. The whole block, including the `getTask` read, is wrapped
+ * (DS CV MINOR-1: `getTask` used to sit outside `runGoalCheck`'s try/catch,
+ * so a read error surfaced as a failed `task_complete`).
+ *
+ * @param {object} input
+ * @param {(name: string, args?: object) => Promise<unknown>} input.callTool
+ * @param {object} input.backend core `TaskBackend`
+ * @param {(result: unknown) => number} input.taskIdFromResult
+ * @param {object} [input.deps] decisionPort / goalCheckTimeoutMs / logger seams
+ * @param {string} [input.sessionId]
+ * @returns {(name: string, args?: object) => Promise<unknown>}
+ */
+export function withGoalCheck({ callTool, backend, taskIdFromResult, deps = {}, sessionId }) {
+  return async (name, args = {}) => {
+    const result = await callTool(name, args);
+    // Only `task_complete`: the judge is defined on `task:after.complete`, and
+    // running it on any other tool would judge half-finished work.
+    if (name !== "task_complete") return result;
+
+    try {
+      const taskId =
+        typeof args.id === "number" ? args.id : Number(args.task_id) || taskIdFromResult(result);
+      if (!taskId) return result;
+      const completed = await backend.getTask(taskId);
+      const hint = await runGoalCheck(
+        {
+          ...(deps.decisionPort ? { decisionPort: deps.decisionPort } : {}),
+          ...(deps.goalCheckTimeoutMs ? { timeoutMs: deps.goalCheckTimeoutMs } : {}),
+          logger: deps.logger,
+        },
+        backend,
+        completed,
+        { sessionId: sessionId ?? "mcp-goal-check" },
+      );
+      return attachHintToResult(result, hint);
+    } catch (err) {
+      process.stderr.write(
+        `roy-task mcp goal-check: wiring failed (fail-open): ${
+          err && err.message ? err.message : String(err)
+        }\n`,
+      );
+      return result;
+    }
+  };
+}
+
+/**
+ * Append the hint to a completed tool's result text.
+ *
+ * The MCP tool result is a plain string (`Task completed: #N - title…`). The
+ * hint rides on the **same** result so the agent sees it without a second
+ * round trip — core's prompt/tool copy already instructs it to verify a
+ * `[TASK_COMPLETION_HINT]` when it appears.
+ *
+ * @param {unknown} result the value the tool returned
+ * @param {string|undefined} hint
+ */
+export function attachHintToResult(result, hint) {
+  if (!hint) return result;
+  const suffix = `\n\n${hint}`;
+  if (typeof result === "string") return result + suffix;
+  // Non-string results (objects) — add a dedicated field instead of
+  // stringifying the whole payload (the agent reads both).
+  if (result && typeof result === "object") {
+    return { ...result, completion_hint: hint };
+  }
+  return String(result ?? "") + suffix;
+}
+
+/**
+ * Read `task.context.completion_hint` (the judge's FAIL channel).
+ *
+ * @returns {Promise<string|undefined>}
+ */
+async function readCompletionHint(backend, taskId) {
+  try {
+    const task = await backend.getTask(taskId);
+    const raw = task && task.context;
+    if (!raw || typeof raw !== "string") return undefined;
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && typeof parsed.completion_hint === "string") {
+      return parsed.completion_hint;
+    }
+  } catch {
+    /* a corrupt context is "no hint" — the judge has already written its op */
+  }
+  return undefined;
+}
+
+/** Resolve or give up after `ms`; never keeps the process alive for the timer. */
+function withDeadline(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise((_resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`goal-check deadline exceeded (${ms}ms)`)),
+        ms,
+      );
+      if (typeof timer.unref === "function") timer.unref();
+    }),
+  ]);
+}
+
+/**
+ * The default logger.
+ *
+ * stdout is the MCP protocol channel (`setStdoutStrictMode(true)` in
+ * `roy-task-mcp-server.mjs`), so diagnostics must go to stderr or they
+ * desynchronise the JSON-RPC stream and the client drops the server.
+ */
+function silentLogger() {
+  return {
+    info: (m) => process.stderr.write(`roy-task mcp goal-check: ${m}\n`),
+    warn: (m) => process.stderr.write(`roy-task mcp goal-check: ${m}\n`),
+    debug: () => {},
+  };
+}