@fideliosai/adapter-hermes-local 0.0.41 → 0.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fideliosai/adapter-hermes-local",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "license": "MIT",
   "description": "Hermes AI agent adapter for FideliOS",
   "homepage": "https://github.com/fideliosai/fidelios",
@@ -23,7 +23,14 @@
     "src"
   ],
   "dependencies": {
-    "@fideliosai/adapter-utils": "0.0.41",
+    "@fideliosai/adapter-utils": "0.0.43",
+    "ollama": "^0.6.3",
     "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "test": "vitest run"
   }
 }

package/src/server/execute.js

@@ -17,6 +17,9 @@
  */
 import { runChildProcess, buildFideliOSEnv, renderTemplate, ensureAbsoluteDirectory, } from "@fideliosai/adapter-utils/server-utils";
 import { HERMES_CLI, DEFAULT_TIMEOUT_SEC, DEFAULT_GRACE_SEC, VALID_PROVIDERS, } from "../shared/constants.js";
+import { triageToolsets } from "./triage.js";
+import { HERMES_TOOLSET_REGISTRY } from "./toolset-registry.js";
+import { isHeadlessEnv, filterHeadlessCsv } from "./headless.js";
 // ---------------------------------------------------------------------------
 // Config helpers
 // ---------------------------------------------------------------------------
@@ -74,6 +77,18 @@ Someone commented. Read it:
 Address the comment, POST a reply if needed, then continue working.
 {{/commentId}}
 
+{{#taskId}}
+## If you need clarification
+
+You are running unattended — there is no human at the terminal, so do NOT use \`clarify\` (it has been stripped from your toolset for this reason). If the task is genuinely ambiguous and you cannot proceed safely, escalate via the FideliOS API:
+
+1. Post the question as a comment:
+   \`curl -s -X POST "{{fideliosApiUrl}}/issues/{{taskId}}/comments" -H "Content-Type: application/json" -d '{"body":"❓ Question: <your question>"}'\`
+2. Mark the issue blocked:
+   \`curl -s -X PATCH "{{fideliosApiUrl}}/issues/{{taskId}}" -H "Content-Type: application/json" -d '{"status":"blocked"}'\`
+3. Stop. The Board will answer in a comment; FideliOS will wake you on the next heartbeat with the reply attached. Prefer this over making large irreversible decisions on shaky assumptions.
+{{/taskId}}
+
 {{#noTask}}
 ## Heartbeat Wake — Check for Work
 
@@ -248,13 +263,56 @@ export async function execute(ctx) {
     const provider = cfgString(config.provider);
     const timeoutSec = cfgNumber(config.timeoutSec) || DEFAULT_TIMEOUT_SEC;
     const graceSec = cfgNumber(config.graceSec) || DEFAULT_GRACE_SEC;
-    const toolsets = cfgString(config.toolsets) || cfgStringArray(config.enabledToolsets)?.join(",");
+    const explicitToolsets = cfgString(config.toolsets) || cfgStringArray(config.enabledToolsets)?.join(",");
+    let toolsets = explicitToolsets;
+    let triageMeta = null;
     const extraArgs = cfgStringArray(config.extraArgs);
     const persistSession = cfgBoolean(config.persistSession) !== false;
     const worktreeMode = cfgBoolean(config.worktreeMode) === true;
     const checkpoints = cfgBoolean(config.checkpoints) === true;
     // ── Build prompt ───────────────────────────────────────────────────────
     const prompt = buildPrompt(ctx, config);
+    // ── Triage toolsets (FID-48) ───────────────────────────────────────────
+    // If the operator pinned toolsets explicitly, respect that whitelist
+    // (backwards compat). Otherwise ask the configured local model to pick a
+    // relevant subset for this prompt out of all available Hermes toolsets.
+    const triageEnabled = cfgBoolean(config.triageEnabled) !== false; // default on
+    if (!explicitToolsets && triageEnabled) {
+        const triageModel = cfgString(config.triageModel) || model;
+        const triageTimeoutMs = cfgNumber(config.triageTimeoutMs);
+        const triageHost = cfgString(config.triageHost) || cfgString(config.ollamaHost);
+        triageMeta = await triageToolsets({
+            prompt,
+            model: triageModel,
+            host: triageHost,
+            timeoutMs: triageTimeoutMs,
+        });
+        if (triageMeta.toolsets.length > 0) {
+            toolsets = triageMeta.toolsets.join(",");
+        }
+        const total = HERMES_TOOLSET_REGISTRY.length;
+        await ctx.onLog("stdout", `[hermes-triage] selected: ${triageMeta.toolsets.join(",") || "(none)"} (${triageMeta.toolsets.length} of ${total}, ${triageMeta.durationMs}ms${triageMeta.usedFallback ? `, fallback: ${triageMeta.error}` : ""})\n`);
+    }
+    // ── Headless I/O contract (FID-52) ─────────────────────────────────────
+    // Strip toolsets that block on stdin (e.g. `clarify`) when running
+    // unattended. Without this, hermes hangs ~120 s per clarify call up to
+    // the adapter's hard timeout (FID-47). The model is instead expected to
+    // escalate via the FideliOS API — the prompt template carries that
+    // guidance.
+    let headlessMeta = null;
+    if (isHeadlessEnv(process.env, { stdinIsTTY: process.stdin?.isTTY })) {
+        const { csv, stripped } = filterHeadlessCsv(toolsets);
+        headlessMeta = {
+            headless: true,
+            stripped,
+            explicitOverride: !!explicitToolsets && stripped.length > 0,
+        };
+        if (stripped.length > 0) {
+            const noun = stripped.length === 1 ? "toolset" : "toolsets";
+            await ctx.onLog("stdout", `[hermes-headless] stripped interactive ${noun}: ${stripped.join(",")} (escalate via FideliOS API instead)\n`);
+            toolsets = csv || undefined;
+        }
+    }
     // ── Build command args ─────────────────────────────────────────────────
     // Use -Q (quiet) to get clean output: just response + session_id line
     const useQuiet = cfgBoolean(config.quiet) !== false; // default true
@@ -400,6 +458,21 @@ export async function execute(ctx) {
         session_id: parsed.sessionId || null,
         usage: parsed.usage || null,
         cost_usd: parsed.costUsd ?? null,
+        triage: triageMeta
+            ? {
+                toolsets: triageMeta.toolsets,
+                used_fallback: triageMeta.usedFallback,
+                error: triageMeta.error ?? null,
+                duration_ms: triageMeta.durationMs,
+            }
+            : null,
+        headless: headlessMeta
+            ? {
+                headless: headlessMeta.headless,
+                stripped: headlessMeta.stripped,
+                explicit_override: headlessMeta.explicitOverride,
+            }
+            : null,
     };
     // Store session ID for next run
     if (persistSession && parsed.sessionId) {

package/src/server/execute.test.js

@@ -0,0 +1,324 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Module mocks must be declared before importing the SUT.
+const runChildProcessMock = vi.fn();
+const triageToolsetsMock = vi.fn();
+
+vi.mock("@fideliosai/adapter-utils/server-utils", async () => {
+  const actual = await vi.importActual(
+    "@fideliosai/adapter-utils/server-utils"
+  );
+  return {
+    ...actual,
+    runChildProcess: (...args) => runChildProcessMock(...args),
+    ensureAbsoluteDirectory: vi.fn(async () => undefined),
+  };
+});
+
+vi.mock("./triage.js", () => ({
+  triageToolsets: (...args) => triageToolsetsMock(...args),
+}));
+
+const { execute } = await import("./execute.js");
+
+function makeCtx(overrides = {}) {
+  const logs = [];
+  const ctx = {
+    runId: "run-1",
+    authToken: "tok",
+    agent: {
+      id: "agent-1",
+      companyId: "co-1",
+      name: "TestAgent",
+      adapterConfig: {
+        hermesCommand: "echo", // anything; we mock runChildProcess
+        model: "qwen3:4b",
+        ...overrides.adapterConfig,
+      },
+    },
+    config: {
+      ...overrides.config,
+    },
+    runtime: {},
+    onLog: async (stream, chunk) => {
+      logs.push({ stream, chunk });
+    },
+  };
+  return { ctx, logs };
+}
+
+beforeEach(() => {
+  runChildProcessMock.mockReset();
+  triageToolsetsMock.mockReset();
+  runChildProcessMock.mockResolvedValue({
+    stdout: "ok\n\nsession_id: sess-1\n",
+    stderr: "",
+    exitCode: 0,
+    signal: null,
+    timedOut: false,
+  });
+});
+
+function getArgs() {
+  expect(runChildProcessMock).toHaveBeenCalledTimes(1);
+  // (runId, cmd, args, opts)
+  return runChildProcessMock.mock.calls[0][2];
+}
+
+function findToolsetsArg(args) {
+  const idx = args.indexOf("-t");
+  return idx === -1 ? null : args[idx + 1];
+}
+
+describe("execute: explicit toolsets bypass triage (backwards-compat)", () => {
+  it("respects adapterConfig.toolsets and never calls triage", async () => {
+    const { ctx } = makeCtx({
+      adapterConfig: { toolsets: "file,terminal" },
+    });
+
+    await execute(ctx);
+
+    expect(triageToolsetsMock).not.toHaveBeenCalled();
+    expect(findToolsetsArg(getArgs())).toBe("file,terminal");
+  });
+
+  it("respects adapterConfig.enabledToolsets array form", async () => {
+    const { ctx } = makeCtx({
+      adapterConfig: { enabledToolsets: ["file", "web"] },
+    });
+
+    await execute(ctx);
+
+    expect(triageToolsetsMock).not.toHaveBeenCalled();
+    expect(findToolsetsArg(getArgs())).toBe("file,web");
+  });
+
+  it("does not invoke triage when triageEnabled === false", async () => {
+    const { ctx } = makeCtx({
+      adapterConfig: { triageEnabled: false },
+    });
+
+    await execute(ctx);
+
+    expect(triageToolsetsMock).not.toHaveBeenCalled();
+    // No -t flag — Hermes will use its default enabled set.
+    expect(findToolsetsArg(getArgs())).toBeNull();
+  });
+});
+
+describe("execute: auto-triage path", () => {
+  it("calls triage with the configured model when toolsets is unset", async () => {
+    triageToolsetsMock.mockResolvedValue({
+      toolsets: ["file", "terminal"],
+      usedFallback: false,
+      durationMs: 42,
+    });
+
+    const { ctx } = makeCtx();
+
+    await execute(ctx);
+
+    expect(triageToolsetsMock).toHaveBeenCalledTimes(1);
+    const triageArgs = triageToolsetsMock.mock.calls[0][0];
+    expect(triageArgs.model).toBe("qwen3:4b");
+    expect(typeof triageArgs.prompt).toBe("string");
+    expect(triageArgs.prompt.length).toBeGreaterThan(0);
+
+    expect(findToolsetsArg(getArgs())).toBe("file,terminal");
+  });
+
+  it("uses adapterConfig.triageModel override when set", async () => {
+    triageToolsetsMock.mockResolvedValue({
+      toolsets: ["file"],
+      usedFallback: false,
+      durationMs: 10,
+    });
+
+    const { ctx } = makeCtx({
+      adapterConfig: { triageModel: "qwen3:0.6b" },
+    });
+
+    await execute(ctx);
+
+    expect(triageToolsetsMock.mock.calls[0][0].model).toBe("qwen3:0.6b");
+  });
+
+  it("forwards triageHost / ollamaHost / triageTimeoutMs into triage opts", async () => {
+    triageToolsetsMock.mockResolvedValue({
+      toolsets: ["file"],
+      usedFallback: false,
+      durationMs: 5,
+    });
+
+    const { ctx } = makeCtx({
+      adapterConfig: {
+        ollamaHost: "http://localhost:11434",
+        triageTimeoutMs: 5000,
+      },
+    });
+
+    await execute(ctx);
+
+    const opts = triageToolsetsMock.mock.calls[0][0];
+    expect(opts.host).toBe("http://localhost:11434");
+    expect(opts.timeoutMs).toBe(5000);
+  });
+
+  it("emits a banner log including the selected subset and total registry size", async () => {
+    triageToolsetsMock.mockResolvedValue({
+      toolsets: ["file", "web"],
+      usedFallback: false,
+      durationMs: 17,
+    });
+
+    const { ctx, logs } = makeCtx();
+    await execute(ctx);
+
+    const banner = logs.find((l) =>
+      l.chunk.startsWith("[hermes-triage] selected: file,web")
+    );
+    expect(banner).toBeTruthy();
+    // total registry size of 22 (current Hermes v0.12)
+    expect(banner.chunk).toMatch(/\(2 of \d+,/);
+    expect(banner.chunk).toMatch(/17ms/);
+  });
+
+  it("surfaces triage metadata in resultJson.triage", async () => {
+    triageToolsetsMock.mockResolvedValue({
+      toolsets: ["file"],
+      usedFallback: false,
+      durationMs: 9,
+    });
+
+    const { ctx } = makeCtx();
+    const result = await execute(ctx);
+
+    expect(result.resultJson?.triage).toEqual({
+      toolsets: ["file"],
+      used_fallback: false,
+      error: null,
+      duration_ms: 9,
+    });
+  });
+
+  it("when triage returns an empty list, omits -t and surfaces fallback metadata", async () => {
+    triageToolsetsMock.mockResolvedValue({
+      toolsets: [],
+      usedFallback: true,
+      error: "triage call failed",
+      durationMs: 4,
+    });
+
+    const { ctx } = makeCtx();
+    const result = await execute(ctx);
+
+    expect(findToolsetsArg(getArgs())).toBeNull();
+    expect(result.resultJson?.triage?.used_fallback).toBe(true);
+    expect(result.resultJson?.triage?.error).toBe("triage call failed");
+  });
+});
+
+describe("execute: triage off when no toolsets and triageEnabled disabled", () => {
+  it("resultJson.triage is null when triage is skipped", async () => {
+    const { ctx } = makeCtx({
+      adapterConfig: { toolsets: "file" },
+    });
+    const result = await execute(ctx);
+    expect(result.resultJson?.triage).toBeNull();
+  });
+});
+
+describe("execute: headless I/O contract (FID-52)", () => {
+  // FideliOS spawns always set FIDELIOS_RUN_ID — vitest's process.env may or
+  // may not have it depending on parent invocation. We force the desired
+  // state per test via FIDELIOS_HEADLESS to avoid leaking between cases.
+  const ORIG_HEADLESS = process.env.FIDELIOS_HEADLESS;
+  const ORIG_RUN_ID = process.env.FIDELIOS_RUN_ID;
+
+  beforeEach(() => {
+    delete process.env.FIDELIOS_HEADLESS;
+    delete process.env.FIDELIOS_RUN_ID;
+  });
+
+  it("strips clarify from a triage selection when headless", async () => {
+    process.env.FIDELIOS_HEADLESS = "1";
+    triageToolsetsMock.mockResolvedValue({
+      toolsets: ["file", "clarify", "web"],
+      usedFallback: false,
+      durationMs: 7,
+    });
+
+    const { ctx, logs } = makeCtx();
+    const result = await execute(ctx);
+
+    expect(findToolsetsArg(getArgs())).toBe("file,web");
+    expect(result.resultJson?.headless).toEqual({
+      headless: true,
+      stripped: ["clarify"],
+      explicit_override: false,
+    });
+    const banner = logs.find((l) => l.chunk.includes("[hermes-headless] stripped"));
+    expect(banner).toBeTruthy();
+    expect(banner.chunk).toMatch(/clarify/);
+  });
+
+  it("strips clarify from an explicitly-pinned toolset whitelist when headless", async () => {
+    process.env.FIDELIOS_HEADLESS = "1";
+
+    const { ctx } = makeCtx({
+      adapterConfig: { toolsets: "clarify,file" },
+    });
+    const result = await execute(ctx);
+
+    expect(triageToolsetsMock).not.toHaveBeenCalled();
+    expect(findToolsetsArg(getArgs())).toBe("file");
+    expect(result.resultJson?.headless?.stripped).toEqual(["clarify"]);
+    expect(result.resultJson?.headless?.explicit_override).toBe(true);
+  });
+
+  it("omits -t entirely when stripping leaves nothing", async () => {
+    process.env.FIDELIOS_HEADLESS = "1";
+
+    const { ctx } = makeCtx({
+      adapterConfig: { toolsets: "clarify" },
+    });
+    await execute(ctx);
+
+    expect(findToolsetsArg(getArgs())).toBeNull();
+  });
+
+  it("does not strip clarify in interactive mode (no FideliOS markers, default TTY)", async () => {
+    // No FIDELIOS_HEADLESS, no FIDELIOS_RUN_ID. The detector falls back to
+    // the stdin TTY hint; in vitest stdin is typically not a TTY but we
+    // bypass that here by explicitly setting FIDELIOS_HEADLESS=0.
+    process.env.FIDELIOS_HEADLESS = "0";
+
+    const { ctx } = makeCtx({
+      adapterConfig: { toolsets: "clarify,file" },
+    });
+    const result = await execute(ctx);
+
+    expect(findToolsetsArg(getArgs())).toBe("clarify,file");
+    expect(result.resultJson?.headless).toBeNull();
+  });
+
+  it("resultJson.headless is null in interactive mode even with no toolsets", async () => {
+    process.env.FIDELIOS_HEADLESS = "0";
+
+    triageToolsetsMock.mockResolvedValue({
+      toolsets: ["file"],
+      usedFallback: false,
+      durationMs: 2,
+    });
+
+    const { ctx } = makeCtx();
+    const result = await execute(ctx);
+
+    expect(result.resultJson?.headless).toBeNull();
+
+    // Restore for subsequent suites
+    if (ORIG_HEADLESS !== undefined) process.env.FIDELIOS_HEADLESS = ORIG_HEADLESS;
+    else delete process.env.FIDELIOS_HEADLESS;
+    if (ORIG_RUN_ID !== undefined) process.env.FIDELIOS_RUN_ID = ORIG_RUN_ID;
+  });
+});

package/src/server/headless.js

@@ -0,0 +1,185 @@
+/**
+ * Headless I/O contract for hermes-local (FID-52).
+ *
+ * Hermes ships interactive toolsets — most notably `clarify` — that block on
+ * `stdin.read()` waiting for a human answer. When FideliOS spawns Hermes
+ * unattended, no human is at the terminal and the agent stalls until Hermes'
+ * own per-clarify timeout (120 s) elapses, multiplied by the number of
+ * clarify calls in a session. FID-47 surfaced this as the 600 s adapter
+ * timeout being hit.
+ *
+ * This module enforces a contract for headless runs:
+ *   1. Detect headless mode (FideliOS spawn vs. interactive `hermes chat`).
+ *   2. Strip toolsets flagged `headlessSafe: false` in the registry from the
+ *      final `-t` whitelist, regardless of whether they were chosen by triage
+ *      or pinned by the operator. Telemetry records what was stripped.
+ *   3. Provide a small escalation helper used by both the prompt template
+ *      (which teaches the model to escalate via curl) and an optional
+ *      adapter-side safety-net.
+ *
+ * Resume flow is handled by FideliOS: when the Board comments on the issue,
+ * the next heartbeat fires with `FIDELIOS_WAKE_COMMENT_ID` set, which the
+ * existing prompt template surfaces to the model.
+ */
+
+import {
+    HERMES_TOOLSET_REGISTRY,
+    isHeadlessSafeToolset,
+} from "./toolset-registry.js";
+
+/**
+ * @typedef {Object} HeadlessFilterResult
+ * @property {string[]} kept       Toolset names that survived the filter.
+ * @property {string[]} stripped   Toolset names that were removed (unknown to
+ *                                 caller as either unsafe or unrecognised).
+ */
+
+/**
+ * @typedef {Object} HeadlessTelemetry
+ * @property {boolean} headless          True when running unattended.
+ * @property {string[]} stripped         Toolsets removed because flagged
+ *                                       `headlessSafe: false` in the registry.
+ * @property {boolean} explicitOverride  True when the operator pinned toolsets
+ *                                       and the strip removed at least one.
+ */
+
+/**
+ * Heuristic: are we running unattended?
+ *
+ * FideliOS spawns always inject `FIDELIOS_RUN_ID`. An explicit override
+ * (`FIDELIOS_HEADLESS=1`) is also honoured for tests / SaaS deployments where
+ * the spawn is wrapped further. Otherwise fall back to TTY detection.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @param {{stdinIsTTY?: boolean}} [opts]
+ * @returns {boolean}
+ */
+export function isHeadlessEnv(env, opts = {}) {
+    if (env && env.FIDELIOS_HEADLESS === "0") return false;
+    if (env && (env.FIDELIOS_HEADLESS === "1" || env.FIDELIOS_HEADLESS === "true")) return true;
+    if (env && typeof env.FIDELIOS_RUN_ID === "string" && env.FIDELIOS_RUN_ID.length > 0) return true;
+    // Fall back to stdin TTY hint if provided. Default: assume interactive
+    // when no FideliOS markers are present so local `hermes chat` keeps working.
+    if (typeof opts.stdinIsTTY === "boolean") return !opts.stdinIsTTY;
+    return false;
+}
+
+/**
+ * Filter a toolset list, dropping anything flagged `headlessSafe: false` in
+ * the canonical registry. Unknown names pass through untouched (the triage
+ * filter and Hermes itself will flag them).
+ *
+ * @param {string[]} toolsets
+ * @param {Array<{name: string, headlessSafe?: boolean}>} [registry]
+ * @returns {HeadlessFilterResult}
+ */
+export function filterHeadlessUnsafe(toolsets, registry) {
+    const kept = [];
+    const stripped = [];
+    const reg = registry ?? HERMES_TOOLSET_REGISTRY;
+    const byName = new Map(reg.map((e) => [e.name, e]));
+    for (const name of toolsets) {
+        const entry = byName.get(name);
+        if (entry && entry.headlessSafe === false) {
+            stripped.push(name);
+        } else {
+            kept.push(name);
+        }
+    }
+    return { kept, stripped };
+}
+
+/**
+ * Convenience: parse a comma-separated `-t` value, run the filter, and return
+ * both the new comma-string and the stripped list. Empty input → empty output.
+ *
+ * @param {string|undefined} csv
+ * @param {Array<{name: string, headlessSafe?: boolean}>} [registry]
+ * @returns {{csv: string|undefined, stripped: string[]}}
+ */
+export function filterHeadlessCsv(csv, registry) {
+    if (!csv || typeof csv !== "string") return { csv, stripped: [] };
+    const names = csv.split(",").map((s) => s.trim()).filter(Boolean);
+    if (names.length === 0) return { csv, stripped: [] };
+    const result = filterHeadlessUnsafe(names, registry);
+    const newCsv = result.kept.length > 0 ? result.kept.join(",") : "";
+    return { csv: newCsv, stripped: result.stripped };
+}
+
+/**
+ * Escalation helper: post a comment on the FideliOS issue and PATCH it to
+ * `blocked` so the Board sees the question and can answer.
+ *
+ * Designed to be safe to call from the prompt-template guidance path
+ * (model-driven escalation) AND from a future adapter-level intercept.
+ *
+ * @param {Object} args
+ * @param {string} args.question     The clarification question to escalate.
+ * @param {string} args.taskId       The FideliOS issue ID.
+ * @param {string} args.apiUrl       FideliOS API base, e.g. http://127.0.0.1:3100/api.
+ * @param {string} [args.apiKey]     Optional bearer token.
+ * @param {typeof fetch} [args.fetchImpl]
+ * @returns {Promise<{ok: boolean, commentId?: string, error?: string}>}
+ */
+export async function escalateClarify(args) {
+    const fetchImpl = args.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        return { ok: false, error: "fetch not available" };
+    }
+    if (!args.taskId) return { ok: false, error: "taskId required" };
+    if (!args.apiUrl) return { ok: false, error: "apiUrl required" };
+
+    const headers = { "Content-Type": "application/json" };
+    if (args.apiKey) headers["Authorization"] = `Bearer ${args.apiKey}`;
+    const body = `❓ Agent question (escalated, headless): ${args.question}`;
+
+    try {
+        const commentRes = await fetchImpl(
+            `${args.apiUrl.replace(/\/+$/, "")}/issues/${args.taskId}/comments`,
+            { method: "POST", headers, body: JSON.stringify({ body }) },
+        );
+        if (!commentRes.ok) {
+            return { ok: false, error: `comment POST ${commentRes.status}` };
+        }
+        const commentJson = await commentRes.json().catch(() => ({}));
+        const commentId = commentJson?.id;
+
+        const patchRes = await fetchImpl(
+            `${args.apiUrl.replace(/\/+$/, "")}/issues/${args.taskId}`,
+            { method: "PATCH", headers, body: JSON.stringify({ status: "blocked" }) },
+        );
+        if (!patchRes.ok) {
+            return { ok: false, error: `status PATCH ${patchRes.status}`, commentId };
+        }
+        return { ok: true, commentId };
+    } catch (err) {
+        return { ok: false, error: err && err.message ? err.message : String(err) };
+    }
+}
+
+/**
+ * Hermes prints clarify questions to its TUI; in `-q` quiet mode it is not
+ * trivial to extract them. This helper detects the marker line emitted by
+ * Hermes' verbose log when entering clarify, so a future safety-net watcher
+ * can pull the question text. Exposed for test ergonomics.
+ *
+ * Marker format (Hermes v0.12.0): `[tool] clarify { "question": "...", ... }`
+ * or the `❓ Clarifying Questions` banner.
+ *
+ * @param {string} line
+ * @returns {string|null} The question text if the line marks clarify entry.
+ */
+export function parseClarifyMarker(line) {
+    if (!line || typeof line !== "string") return null;
+    // Verbose tool-call line: [tool] clarify {"question":"..."}
+    const toolMatch = line.match(/\[tool\]\s+clarify\s+(\{.*\})/);
+    if (toolMatch) {
+        try {
+            const obj = JSON.parse(toolMatch[1]);
+            if (obj && typeof obj.question === "string") return obj.question;
+        } catch {
+            // Fall through to other markers.
+        }
+    }
+    return null;
+}