hilos-agent 0.9.4 → 0.9.5

package/README.md

@@ -53,7 +53,9 @@ Running from elsewhere, or want to map several repos explicitly? Use a config:
   "defaultBranch": "main",
   "gate": false,               // default: open a PR directly. true = approve-before-push
   "heartbeatMs": 180000,       // long runs post one "still working…" thread reply this often (0 = off, min 15s)
-  "chatTimeoutMs": 90000       // cap a chat reply / plan-ack so a stalled model can't go silent
+  "chatTimeoutMs": 90000,      // cap a chat reply / plan-ack so a stalled model can't go silent
+  "longPollMs": 20000,         // ask the server to HOLD the mention poll and answer the moment work lands (0 = plain 5s polling; older servers fall back automatically)
+  "catchupMs": 86400000        // how far back a restart replays mentions from the persisted cursor (default 24h; 0 = restart at "now", the pre-0866 behavior)
 }
 ```
 
@@ -68,7 +70,11 @@ to a short "done" line. A run that **times out or errors** says so honestly (wit
 a stderr tail) instead of claiming "no changes". Chat replies use the faster
 `chatCmd` (when unset, derived from `codingCmd`'s tool — a Claude daemon chats
 with Haiku, a Codex daemon with `codex exec`, and so on) bounded by
-`chatTimeoutMs`. The responsive surface needs a hilos server new enough to expose
+`chatTimeoutMs`. The chat-vs-code pass only classifies; the separate chat
+responder keeps the CLI's normal tools. Generated Codex chat and code commands
+explicitly enable its built-in web search (an explicit operator override still
+wins), while other vendors keep their own tool configuration. The responsive
+surface needs a hilos server new enough to expose
 `edit_message`; older servers just skip the live edits.
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions in channels and threads, makes the change, and opens a PR for review — your code and credentials never leave your machine. (Approve-before-push is available via gate:true.)",
   "type": "module",
   "bin": {

package/src/codex-mcp-session.mjs

@@ -461,6 +461,10 @@ export async function runCodexMcpSession({
             cwd,
             "approval-policy": approvalPolicy,
             sandbox,
+            // The gated transport cannot inherit `codex exec` argv. Carry the
+            // same public web-search capability through the MCP tool's config;
+            // permission policy and sandboxing remain unchanged.
+            config: { tools: { web_search: true } },
             ...(model ? { model } : {}),
           },
         };

package/src/config.mjs

@@ -121,6 +121,17 @@ const DEFAULTS = {
   gate: false,
   maxRounds: 3,
   pollMs: 5000,
+  // Long-poll (0866): when the server supports it, list_mentions is asked to
+  // HOLD this many ms and answer the moment a mention lands — pickup latency
+  // stops being pollMs. 0 disables and falls back to plain pollMs polling.
+  // The server caps a hold at 25s regardless of what is asked for here.
+  longPollMs: 20000,
+  // How far back a restart may replay missed mentions from the persisted
+  // cursor (0866). A daemon that was off for a week should not open a week of
+  // stale branches; a day covers the overnight-laptop case the cursor exists
+  // for. 0 disables catch-up entirely (restart starts at "now", the old
+  // behavior).
+  catchupMs: 24 * 60 * 60 * 1000,
   // On a long code run, post ONE thread progress reply at the first beat then
   // edit it on later beats, so a human sees the agent is alive without thread
   // spam. 0 disables. Clamped to >=15s so a misconfig can't spam realtime
@@ -224,6 +235,8 @@ const LIVE_FIELDS = [
   "gate",
   "maxRounds",
   "pollMs",
+  "longPollMs",
+  "catchupMs",
   "runTimeoutMs",
   "decisionTimeoutMs",
   "decisionPollMs",

package/src/cursor-store.mjs

@@ -0,0 +1,76 @@
+// Durable mention cursor (0866).
+//
+// The poll loop's cursor and dedupe set lived only in memory, so a daemon
+// restart began at "now" and every mention that arrived while it was down was
+// silently skipped (backfill:false, the default). This file is the fix's whole
+// mechanism: the cursor is persisted per agent after each delivery, and a
+// restart resumes from it — bounded by `catchupMs`, because replaying a week of
+// stale asks after a vacation would be worse than skipping them.
+//
+// Telegram semantics, deliberately: persisting the cursor acknowledges
+// DELIVERY into the daemon's queue, not completion of the work. A crash after
+// enqueue can still lose an in-flight task (exactly as today); what can no
+// longer happen is a mention arriving into a dead daemon and never being seen.
+//
+// Dependency-free and injectable-dir like hook.mjs's state store, so tests run
+// against a temp dir and never touch a real ~/.hilos.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Same parent as ~/.hilos/agent.json (config.mjs) and state.json (resume.mjs). */
+export const CURSOR_STATE_DIR = join(homedir(), ".hilos", "mention-cursors");
+
+/** One file per agent — two agents on one machine must never share a cursor. */
+export function cursorPath(agentId, dir = CURSOR_STATE_DIR) {
+  return join(dir, `${String(agentId).replace(/[^a-zA-Z0-9-]/g, "")}.json`);
+}
+
+/**
+ * The cursor a restart should resume from, or null when there is nothing
+ * usable — no file, unreadable JSON, a malformed timestamp, or a cursor older
+ * than `catchupMs` allows (clamped to the window's edge rather than dropped,
+ * so a long-dead daemon still catches the most recent day, not nothing).
+ *
+ * @param {string} agentId
+ * @param {{ catchupMs?: number, dir?: string, now?: () => number }} [opts]
+ * @returns {string|null} ISO timestamp
+ */
+export function loadMentionCursor(agentId, { catchupMs = 0, dir = CURSOR_STATE_DIR, now = Date.now } = {}) {
+  if (!agentId || !(catchupMs > 0)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(cursorPath(agentId, dir), "utf8"));
+  } catch {
+    return null;
+  }
+  const value = parsed && typeof parsed.mentionCursor === "string" ? parsed.mentionCursor : null;
+  if (!value) return null;
+  const at = new Date(value).getTime();
+  if (Number.isNaN(at)) return null;
+  const floor = now() - catchupMs;
+  return at < floor ? new Date(floor).toISOString() : value;
+}
+
+/**
+ * Persist the cursor after a delivery. Best-effort by design: a full disk or
+ * read-only home must never take the poll loop down — the daemon just degrades
+ * to today's restart-at-now behavior.
+ *
+ * @param {string} agentId
+ * @param {string} isoTimestamp
+ * @param {{ dir?: string, log?: { error?: (m: string) => void } }} [opts]
+ * @returns {boolean} whether the write landed
+ */
+export function saveMentionCursor(agentId, isoTimestamp, { dir = CURSOR_STATE_DIR, log } = {}) {
+  if (!agentId || typeof isoTimestamp !== "string" || !isoTimestamp) return false;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(cursorPath(agentId, dir), JSON.stringify({ mentionCursor: isoTimestamp }));
+    return true;
+  } catch (e) {
+    log?.error?.(`mention cursor not persisted: ${e?.message || e}`);
+    return false;
+  }
+}

package/src/daemon.mjs

@@ -1,6 +1,13 @@
 // Pure daemon helpers — no I/O. (Mirror of the app's scripts/lib/daemon.mjs so
 // the package stands alone; keep them equivalent.)
 
+import {
+  agentCoauthorTrailer,
+  agentCommitBody,
+  githubArtifactBody,
+  selectGithubArtifactTitle,
+} from "./github-artifacts.mjs";
+
 /** Branch name from a task: `hilos/<kebab-first-words>-<suffix>`. */
 export function branchSlug(text, suffix) {
   const base =
@@ -121,18 +128,33 @@ export function decisionKind(report) {
 }
 
 /** Commit message for an approved proposal. */
-export function commitMessage(task) {
-  const first = String(task || "").split("\n")[0].slice(0, 72) || "hilos change";
-  return `${first}\n\nProposed via hilos and approved by a human reviewer.`;
+/** @param {unknown} task @param {Record<string, any>} [provenance] */
+export function commitMessage(task, provenance = {}) {
+  const title = selectGithubArtifactTitle({
+    summary: provenance.summary,
+    originalTask: task,
+    fallback: "hilos change",
+  });
+  const trailer = agentCoauthorTrailer(provenance.agentName, provenance.agentId);
+  // The agent's own account of the change becomes the commit body, so the log
+  // says what shipped and not only that a person approved it.
+  const body = agentCommitBody(provenance.summary);
+  return [title, body, "Proposed via hilos and approved by a person.", trailer]
+    .filter(Boolean)
+    .join("\n\n");
 }
 
-/** PR title + body for an approved proposal. */
-export function prTitleBody(task, branch) {
-  const title = String(task || "").split("\n")[0].slice(0, 72) || branch;
-  const body =
-    "Proposed by a hilos agent from a channel request, approved by a human reviewer.\n\n" +
-    `Task: ${String(task || "").trim()}`;
-  return { title, body };
+/** PR title + body for an approved proposal. The body carries the agent's own
+ *  description of the change (from `provenance.summary`) above the provenance
+ *  block, so a reviewer on GitHub reads what shipped before who proposed it. */
+/** @param {unknown} task @param {string} branch @param {Record<string, any>} [provenance] */
+export function prTitleBody(task, branch, provenance = {}) {
+  const title = selectGithubArtifactTitle({
+    summary: provenance.summary,
+    originalTask: task,
+    fallback: branch,
+  });
+  return { title, body: githubArtifactBody(provenance) };
 }
 
 /** Build the post_report payload that serves as the approval card. */

package/src/github-artifacts.mjs

@@ -0,0 +1,253 @@
+const TITLE_MAX = 72;
+// A pull-request description is a reviewer's first read, not an essay: enough
+// room for the agent's own account of the change, bounded so a runaway summary
+// can never become the PR body. The commit log gets a shorter form still.
+const DESCRIPTION_MAX = 1400;
+const COMMIT_BODY_MAX = 600;
+
+const REJECTED_TITLE_LINES = [
+  /^(?:sure|okay|ok|yes|got it|sounds good|absolutely|certainly|done|working on it)\b/i,
+  /^(?:i(?:'ll| will| have|’ll)|let me|here(?:'s| is))\b/i,
+  /^(?:address|apply|handle|incorporate|respond to|update)\b.{0,36}\b(?:feedback|review|comments?|pr)\b/i,
+  /^@\S+/,
+  /https?:\/\//i,
+  /^```/,
+  /^visual_?preview\s*:/i,
+];
+
+function oneLine(value, max = 160) {
+  return String(value ?? "")
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, max);
+}
+
+function cleanTitleLine(value) {
+  return oneLine(value)
+    .replace(/^#{1,6}\s+/, "")
+    .replace(/^[-*+]\s+/, "")
+    .replace(/^\d+[.)]\s+/, "")
+    .replace(/^(?:(?:pr|pull request|commit)\s+)?title\s*[:\-–—]\s*/i, "")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/[*_~]/g, "")
+    .replace(/^@[a-z0-9][a-z0-9-]*\s*[:,–—-]?\s*/i, "")
+    .replace(/[.\s]+$/, "")
+    .trim();
+}
+
+function candidateLines(value) {
+  return String(value ?? "")
+    .split(/\r?\n/)
+    .map(cleanTitleLine)
+    .filter(Boolean);
+}
+
+function usableTitle(line) {
+  if (line.length < 4) return false;
+  return !REJECTED_TITLE_LINES.some((pattern) => pattern.test(line));
+}
+
+function truncateTitle(title) {
+  if (title.length <= TITLE_MAX) return title;
+  return `${title.slice(0, TITLE_MAX - 1).trimEnd()}…`;
+}
+
+/**
+ * The title the agent wrote for its OWN change, or null when its summary never
+ * offered a usable one. Callers that must always end up with something use
+ * `selectGithubArtifactTitle` (which falls back to the request text); callers
+ * that need to know whether the agent actually authored a headline — an
+ * iteration commit deciding between the agent's words and a canned subject —
+ * use this.
+ */
+/** @param {unknown} summary */
+export function agentAuthoredTitle(summary) {
+  const line = candidateLines(summary).find(usableTitle);
+  return line ? truncateTitle(line) : null;
+}
+
+/**
+ * One title selector for hosted and local-daemon GitHub output. Agent summaries
+ * win only when they actually describe a change; acknowledgements, mentions,
+ * Markdown wrappers, links, and review-process chatter are rejected. Iteration
+ * callers keep their existing PR title and use this only for the new commit.
+ */
+/** @param {{ summary?: unknown, originalTask?: unknown, fallback?: string }} [input] */
+export function selectGithubArtifactTitle({ summary, originalTask, fallback = "Update" } = {}) {
+  const summaryTitle = agentAuthoredTitle(summary);
+  const taskTitle = candidateLines(originalTask)
+    .map((line) => line.replace(/@[a-z0-9][a-z0-9-]*/gi, "").trim())
+    .find(usableTitle);
+  return truncateTitle(summaryTitle || taskTitle || cleanTitleLine(fallback) || "Update");
+}
+
+/**
+ * Neutralize the two things in agent prose that would ACT on GitHub instead of
+ * describing the change: HTML comment delimiters (which could otherwise forge
+ * or break the provenance marker this body ends with) and @handles (which ping
+ * whatever unrelated GitHub account happens to own that name). Everything else
+ * — including code fences — is the agent's writing and survives intact.
+ */
+function defuseMarkup(line) {
+  return line
+    .replace(/<!--+/g, "")
+    .replace(/--+>/g, "")
+    .replace(/(^|[\s(\[])@([a-z0-9][a-z0-9-]{0,38})/gi, "$1$2");
+}
+
+/** Drop fenced code blocks — a commit log is not the place for a snippet. */
+function stripFences(text) {
+  return String(text ?? "").replace(/^\s*```[\s\S]*?^\s*```\s*$/gm, "");
+}
+
+/** Trim leading/trailing blank lines and collapse blank runs to one. */
+function tidyLines(lines) {
+  const out = [];
+  for (const line of lines) {
+    const value = line.replace(/\s+$/, "");
+    if (!value.trim() && (!out.length || !out[out.length - 1].trim())) continue;
+    out.push(value);
+  }
+  while (out.length && !out[out.length - 1].trim()) out.pop();
+  return out;
+}
+
+/** Keep whole lines up to `max` characters, marking a cut rather than hiding it. */
+function clampLines(lines, max) {
+  const kept = [];
+  let used = 0;
+  for (const line of lines) {
+    const next = used + line.length + 1;
+    if (next > max) {
+      kept.push("…");
+      break;
+    }
+    kept.push(line);
+    used = next;
+  }
+  return tidyLines(kept).join("\n").trim();
+}
+
+/**
+ * The agent's own account of the change, ready to be a pull-request
+ * description: its summary MINUS the headline it leads with (that becomes the
+ * title, and a PR should not open by repeating its own title) and minus the
+ * machine directives it ends with (`VISUAL_PREVIEW:`), sanitized and bounded on
+ * whole lines.
+ *
+ * Returns "" when the agent wrote nothing past a title — the caller then ships
+ * provenance alone rather than inventing prose it cannot stand behind.
+ */
+/** @param {unknown} summary @param {{ max?: number }} [options] */
+export function agentChangeDescription(summary, { max = DESCRIPTION_MAX } = {}) {
+  const lines = String(summary ?? "")
+    .replace(/\r\n?/g, "\n")
+    .split("\n");
+  const headline = lines.findIndex((line) => usableTitle(cleanTitleLine(line)));
+  const body = (headline === -1 ? lines : lines.slice(headline + 1))
+    .filter((line) => !/^\s*visual_?preview\s*:/i.test(line))
+    .map(defuseMarkup);
+  return clampLines(tidyLines(body), max);
+}
+
+/** The same account of the change, shortened and de-fenced for a commit body. */
+/** @param {unknown} summary */
+export function agentCommitBody(summary) {
+  return agentChangeDescription(stripFences(summary), { max: COMMIT_BODY_MAX });
+}
+
+function safeLabel(value, fallback) {
+  const label = oneLine(value, 80)
+    .replace(/[<>`[\]{}*_]/g, "")
+    .replace(/https?:\/\/\S+/gi, "")
+    .trim();
+  return label || fallback;
+}
+
+function safeId(value) {
+  const id = oneLine(value, 100);
+  return /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,99}$/.test(id) ? id : null;
+}
+
+function safeHilosUrl(value) {
+  try {
+    const url = new URL(String(value ?? ""));
+    if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+    url.username = "";
+    url.password = "";
+    // Room and message links use their query/hash to identify the exact place
+    // a request came from. Keep that stable context after removing credentials.
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+function linkLine(label, url, fallback) {
+  return url ? `- ${label}: [Open in hilos](${url})` : `- ${label}: ${fallback}`;
+}
+
+/**
+ * A bounded PR body: the agent's own description of the change on top, then the
+ * provenance block. It still deliberately never accepts task text — the raw
+ * chat message is not a description of what shipped — but it does accept the
+ * agent's `summary`, which is the one piece of writing on this path that was
+ * actually authored about the diff.
+ */
+/**
+ * @param {{ agentName?: unknown, personName?: unknown, roomName?: unknown,
+ * roomUrl?: unknown, messageId?: unknown, messageUrl?: unknown, runId?: unknown,
+ * reportId?: unknown, partial?: boolean, summary?: unknown }} [input]
+ */
+export function githubArtifactBody(input = {}) {
+  const agent = safeLabel(input.agentName, "hilos agent");
+  const person = safeLabel(input.personName, "a team member");
+  const room = safeLabel(input.roomName, "project room");
+  const roomUrl = safeHilosUrl(input.roomUrl);
+  const messageUrl = safeHilosUrl(input.messageUrl);
+  const runId = safeId(input.runId);
+  const reportId = safeId(input.reportId);
+  const partial = input.partial === true;
+  const machine = {
+    version: 1,
+    agent,
+    person,
+    room,
+    messageId: safeId(input.messageId),
+    runId,
+    reportId,
+  };
+  const partialNote = partial
+    ? "\nThis is a partial run. Mention the agent in the room to continue."
+    : "";
+
+  // The agent's account of the change leads, because that is what a reviewer
+  // opens the pull request to read. Provenance follows it under a rule.
+  const description = agentChangeDescription(input.summary);
+
+  return [
+    ...(description ? [description, "", "---", ""] : []),
+    `Proposed by **${agent}** for **${person}** in **${room}**. A person remains the creator of record and decides whether to merge.`,
+    "",
+    linkLine("Room", roomUrl, room),
+    linkLine("Request", messageUrl, machine.messageId ? `message \`${machine.messageId}\`` : "room request"),
+    `- Run: ${runId ? `\`${runId}\`` : "not recorded"}`,
+    `- Report: ${reportId ? `\`${reportId}\`` : "posted in the room after this pull request opens"}`,
+    partialNote,
+    "",
+    `<!-- hilos-provenance ${JSON.stringify(machine).replace(/--/g, "—")} -->`,
+  ]
+    .filter((line, index, all) => line !== "" || index === 1 || all[index - 1] !== "")
+    .join("\n")
+    .trim();
+}
+
+/** A stable Git co-author trailer for the named agent, without user input. */
+/** @param {unknown} agentName @param {unknown} agentId */
+export function agentCoauthorTrailer(agentName, agentId) {
+  const name = safeLabel(agentName, "hilos agent");
+  const id = safeId(agentId)?.replace(/[^a-zA-Z0-9]/g, "").slice(0, 48) || "agent";
+  return `Co-authored-by: ${name} <agent+${id}@hilos.sh>`;
+}

package/src/handler.mjs

@@ -41,6 +41,7 @@ import { makeStreamParser, createUsageFold } from "./agent-events.mjs";
 import {
   detectVendor,
   codeStreamArgs,
+  codeWebArgs,
   codeDirArgs,
   codeImageArgs,
   codeProjectKey,
@@ -306,6 +307,11 @@ function openCodePermissionCallbacks({
   threadRoot,
   runId = null,
   provider = "opencode",
+  // 0866 — when the server's get_permission_decision supports a long-poll
+  // hold, each read blocks up to this many ms and answers the moment a human
+  // decides, instead of the gate discovering the decision on its next 1s poll.
+  // 0 (older servers) keeps the plain immediate read.
+  decisionWaitMs = 0,
 }) {
   return {
     requestPermission: async (request) => {
@@ -352,6 +358,8 @@ function openCodePermissionCallbacks({
         vendorSessionId: request.sessionId,
         vendorRequestId: request.vendorRequestId,
         ...(failClosed ? { failClosed: true } : {}),
+        // Never on a failClosed settlement — that call exists to act NOW.
+        ...(decisionWaitMs > 0 && !failClosed ? { waitMs: decisionWaitMs } : {}),
       });
     },
   };
@@ -768,7 +776,37 @@ async function linkPrFromUrl({ tool, channelId, url }) {
   await tool("link_pr", { channelId, repoFullName: m[1], prNumber: Number(m[2]) }).catch(() => {});
 }
 
-async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, existingPrUrl, settleId, runId, usageArgs = {} }) {
+function githubProvenance({ cfg, me, message, channelId, runId, summary }) {
+  let siteUrl = "https://hilos.sh";
+  try {
+    const parsed = new URL(cfg.url);
+    parsed.pathname = parsed.pathname.replace(/\/api\/mcp\/?$/, "");
+    parsed.search = "";
+    parsed.hash = "";
+    siteUrl = parsed.toString().replace(/\/$/, "");
+  } catch {
+    /* the body helper will keep links absent if configuration is malformed */
+  }
+  const roomUrl = `${siteUrl}/w/${me?.workspaceId}/c/${channelId}`;
+  const messageUrl = message?.id
+    ? message.parentId
+      ? `${roomUrl}?thread=${message.parentId}&reply=${message.id}`
+      : `${roomUrl}#m-${message.id}`
+    : undefined;
+  return {
+    agentName: me?.agentName,
+    agentId: me?.agentId,
+    personName: message?.author,
+    roomName: message?.channel || "project room",
+    roomUrl,
+    messageId: message?.id,
+    messageUrl,
+    runId,
+    summary,
+  };
+}
+
+async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, existingPrUrl, settleId, runId, provenance = {}, usageArgs = {} }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
   // `parentId` here is the run's thread root. Terminal outcomes ask the server
@@ -785,7 +823,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       });
       return { status: "nothing-staged", branch };
     }
-    const commit = deps.git(repoPath, ["commit", "-m", commitMessage(task)]);
+    const commit = deps.git(repoPath, ["commit", "-m", commitMessage(task, provenance)]);
     if (commit.status !== 0) {
       await tool("post_message", {
         channelId,
@@ -805,7 +843,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       });
       return { status: "push-failed", branch };
     }
-    const { title, body } = prTitleBody(task, branch);
+    const { title, body } = prTitleBody(task, branch, provenance);
     // Continuing an existing PR (request-changes rework): the push already
     // updated it — reuse its URL instead of opening a duplicate. Otherwise open
     // a fresh PR.
@@ -897,7 +935,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
  * switched to `main` would otherwise make `gh` try to open main → main. Used
  * only when NOT gated (bias-to-action).
  */
-async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, settleId, runId, usageArgs = {} }) {
+async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, settleId, runId, provenance = {}, usageArgs = {} }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
   const currentBranch =
@@ -907,7 +945,7 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
   let prUrl = deps.findPR ? deps.findPR(repoPath, ship.headBranch) : null;
   let prAttempt = null;
   if (!prUrl && push.status === 0) {
-    const { title, body } = prTitleBody(task, ship.headBranch);
+    const { title, body } = prTitleBody(task, ship.headBranch, provenance);
     prAttempt = deps.openPR(repoPath, {
       title,
       body,
@@ -916,7 +954,7 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
     });
     prUrl = prAttempt.ok && prAttempt.url ? prAttempt.url : null;
   }
-  const { title } = prTitleBody(task, ship.headBranch);
+  const { title } = prTitleBody(task, ship.headBranch, provenance);
   const recoveredNote = ship.recoveredFrom
     ? ` The child had switched to \`${ship.recoveredFrom}\`; hilos recovered its HEAD onto \`${ship.headBranch}\`.`
     : "";
@@ -991,6 +1029,7 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
 // Sentinel the router model emits when the latest message is a request to change
 // code. Unusual on purpose so it can't be confused with a real chat reply.
 const CODE_SIGNAL = "__CODE__";
+const CHAT_SIGNAL = "__CHAT__";
 
 // 0860 — the quiet option, offered ONLY on untagged DM wakes (message.implicit
 // === "dm"). In a DM every message reaches the agent without a tag, so some of
@@ -1046,8 +1085,8 @@ export function dmJudgmentBlock(implicitDm) {
 
 /**
  * Decide — with the LLM, not a word list — whether the latest message wants a
- * code change or a conversational reply, and produce the payload in the SAME
- * call. The model reads the whole conversation, so it judges by intent and
+ * code change or a conversational reply. The model reads the whole
+ * conversation, so it judges by intent and
  * context, in any language: "just code it", "dale, hazlo", "yeah go for it" after
  * a request → code; "how does this work?", "thoughts?", "thanks" → chat.
  *
@@ -1059,12 +1098,12 @@ export function dmJudgmentBlock(implicitDm) {
  * Returns one of:
  *   { aborted: true }
  *   { code: true, task }           → run the coding flow with `task` as the spec
- *   { code: false, reply, error }  → post `reply` as a chat message
+ *   { code: false, error }         → run the separate conversational responder
  *
  * `error` is set when the model produced nothing (so the caller can be honest
  * about a timeout vs a missing binary instead of inventing a reply).
  */
-async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cfg, signal, hasActiveRun = false, runCliFn, implicitDm = false }) {
+export async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cfg, signal, hasActiveRun = false, runCliFn, implicitDm = false }) {
   const doRun = runCliFn || runCli; // folder mode injects deps.runCli; repo flow uses the import
   const cmd = chatCmdFor(cfg);
   const parts = cmd.split(" ").filter(Boolean);
@@ -1093,12 +1132,12 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
     `using the conversation. Example:\n${CODE_SIGNAL}\nAdd a hover popover to message reactions ` +
     `that lists who reacted with each emoji.\n\n` +
     `Otherwise — a question, a greeting, general discussion, or they explicitly don't want code ` +
-    `yet — just reply to them concisely and directly as a single chat message (no preamble, no ` +
-    `headings). When unsure, stay conversational; implementation and PR flow are for clear ` +
-    `action language.` +
+    `yet — output ONLY the token ${CHAT_SIGNAL}. When unsure, choose ${CHAT_SIGNAL}; ` +
+    `implementation and PR flow are for clear action language.` +
     `${followupBlock}\n\n` +
-    `You are only routing here — output ONLY your text response. Do NOT use any tools, do NOT ` +
-    `edit files, do NOT run commands; a separate step does the actual coding.` +
+    `You are only routing here — output ONLY the routing token (plus the imperative spec for ` +
+    `${CODE_SIGNAL}). Do NOT use any tools, edit files, or run commands; separate tool-capable ` +
+    `steps write the conversational answer or do the coding.` +
     `${dmJudgmentBlock(implicitDm)}\n\n` +
     `${memoryPreamble(workspaceMemory)}Conversation so far:\n${transcript}`;
   const run = await doRun({
@@ -1134,7 +1173,10 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
     const quiet = parseNoReply(out);
     if (quiet.noReply) return { code: false, noReply: true, emoji: quiet.emoji, followupSignal };
   }
-  return { code: false, reply: out, followupSignal };
+  // A classifier never authors the final answer. Even if a model ignores the
+  // token contract and emits prose, discard it and let the normal responder —
+  // with the vendor's real tools — answer the room.
+  return { code: false, reply: null, followupSignal };
 }
 
 /**
@@ -2048,8 +2090,10 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
     // 0779: [] for every vendor without a verified image flag — their argv is
     // byte-identical to before, and the prompt note still names the files.
     const imageArgs = codeImageArgs(vendor, localImages);
+    const webArgs = codeWebArgs(vendor, parts.slice(1));
     const codeArgs = [
       ...parts.slice(1),
+      ...webArgs,
       ...modelArgs,
       ...dirArgs,
       ...imageArgs,
@@ -2141,6 +2185,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
             tool,
             channelId,
             threadRoot,
+            decisionWaitMs: caps.decisionWaitMs,
             provider: vendor,
           }),
         });
@@ -2158,6 +2203,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
             tool,
             channelId,
             threadRoot,
+            decisionWaitMs: caps.decisionWaitMs,
           }),
         });
       } else if (gateCodexPermissions) {
@@ -2177,6 +2223,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
             tool,
             channelId,
             threadRoot,
+            decisionWaitMs: caps.decisionWaitMs,
             provider: vendor,
           }),
         });
@@ -2196,6 +2243,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
             tool,
             channelId,
             threadRoot,
+            decisionWaitMs: caps.decisionWaitMs,
             provider: vendor,
           }),
         });
@@ -2715,12 +2763,8 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           onStopRequested,
         });
       }
-      // Not a coding task → post the router's reply if it produced one, else fall
-      // through to a normal conversational reply.
-      if (routed.reply) {
-        await tool("post_message", { channelId, parentId, body: routed.reply });
-        return { status: "chat" };
-      }
+      // Not a coding task → the classifier is finished. The separate responder
+      // below owns the answer and keeps its normal tools.
     }
     await respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps });
     return { status: "chat" };
@@ -2780,14 +2824,19 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       await reactQuietly({ tool, caps, message, emoji: routed.emoji });
       return { status: "quiet" };
     }
-    let body = routed.reply;
-    if (!body) {
-      body =
-        routed.error?.code === "ENOENT"
-          ? `(my chat command \`${chatCmdFor(cfg)}\` isn't installed or on PATH.)`
-          : `Still thinking on this — it's taking longer than usual. I'll follow up shortly.`;
-    }
-    await tool("post_message", { channelId, parentId, body });
+    await respondConversationally({
+      message,
+      channelId,
+      tool,
+      me,
+      cfg,
+      repoLink,
+      parentId,
+      workspaceMemory,
+      signal,
+      context,
+      caps,
+    });
     return { status: "chat" };
   }
   // routed.code → fall through to the coding flow below.
@@ -3300,6 +3349,11 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     let drainProgress = async () => {};
     // 0782 — the silent-work stop poll, torn down in the same finally as the run.
     let stopPoller = null;
+    // Structured transports expose the final assistant summary as an event;
+    // argv transports fold it into the progress emitter. Keep one local value
+    // so GitHub title/provenance selection never reaches for an out-of-scope
+    // parser variable (0884).
+    let resultText = "";
     if (streamOn) {
       if (!progressId) {
         try {
@@ -3377,9 +3431,10 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // `exec`, so it has to sit ahead of it. [] for every vendor without a
     // verified flag, leaving their argv byte-identical to before.
     const imageArgs = codeImageArgs(vendor, localImages);
+    const webArgs = codeWebArgs(vendor, parts.slice(1));
     const codeArgs = streamOn
-      ? [...parts.slice(1), ...modelArgs, ...dirArgs, ...imageArgs, ...resumeArgs, ...streamArgs]
-      : [...parts.slice(1), ...modelArgs, ...dirArgs, ...imageArgs, ...resumeArgs];
+      ? [...parts.slice(1), ...webArgs, ...modelArgs, ...dirArgs, ...imageArgs, ...resumeArgs, ...streamArgs]
+      : [...parts.slice(1), ...webArgs, ...modelArgs, ...dirArgs, ...imageArgs, ...resumeArgs];
     const handleCliData = (c) => {
       // Keep tracking lastLine as a fallback (legacy heartbeat / honesty).
       const lines = String(c).split("\n").map((s) => s.trim()).filter(Boolean);
@@ -3420,6 +3475,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       } catch {
         /* a progress fold must never break the run */
       }
+      if (ev?.t === "result" && typeof ev.summary === "string") {
+        resultText = ev.summary;
+      }
     };
     let run;
     try {
@@ -3481,6 +3539,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
             tool,
             channelId,
             threadRoot,
+            decisionWaitMs: caps.decisionWaitMs,
             runId,
             provider: vendor,
           }),
@@ -3502,6 +3561,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
             tool,
             channelId,
             threadRoot,
+            decisionWaitMs: caps.decisionWaitMs,
             runId,
           }),
         });
@@ -3525,6 +3585,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
             tool,
             channelId,
             threadRoot,
+            decisionWaitMs: caps.decisionWaitMs,
             runId,
             provider: vendor,
           }),
@@ -3548,6 +3609,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
             tool,
             channelId,
             threadRoot,
+            decisionWaitMs: caps.decisionWaitMs,
             runId,
             provider: vendor,
           }),
@@ -3630,6 +3692,13 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         }
       }
     }
+    if (!resultText && emitter) {
+      try {
+        resultText = emitter.snapshot()?.lastLine || "";
+      } catch {
+        /* title fallback still has the routed task */
+      }
+    }
     if (run.aborted || signal?.aborted) {
       console.log("  code → cancelled");
       return { aborted: true };
@@ -3661,15 +3730,33 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         Number((git(repoPath, ["rev-list", "--count", `${baseRef}..HEAD`]).stdout || "0").trim()) || 0;
       if (ahead > 0) {
         console.log(`  code → agent self-committed (${ahead} commit(s) ahead); reconciling`);
-        return { empty: true, failed: false, ahead };
+        return {
+          empty: true,
+          failed: false,
+          ahead,
+          summary: (resultText || (streamArgs.length ? "" : run.stdout) || "").trim(),
+        };
       }
       console.log("  code → no changes produced");
-      return { empty: true, failed: false, ahead: 0 };
+      return {
+        empty: true,
+        failed: false,
+        ahead: 0,
+        summary: (resultText || (streamArgs.length ? "" : run.stdout) || "").trim(),
+      };
     }
     console.log("  code → diff captured");
     const stat = parseShortstat(git(repoPath, ["diff", "--cached", "--shortstat"]).stdout);
     const { text: diffText, truncated, omittedLines } = truncateDiff(diff);
-    return { empty: false, diffText, truncated, omittedLines, stat, runFailed: run.status !== 0 };
+    return {
+      empty: false,
+      diffText,
+      truncated,
+      omittedLines,
+      stat,
+      runFailed: run.status !== 0,
+      summary: (resultText || (streamArgs.length ? "" : run.stdout) || "").trim(),
+    };
   };
 
   // Persist the run's coding-agent session (0282) so a LATER iterate can resume it.
@@ -3886,6 +3973,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       parentId: threadRoot,
       settleId: selfSettleId,
       runId,
+      provenance: githubProvenance({ cfg, me, message, channelId, runId, summary: staged.summary }),
       usageArgs: reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),
     });
     await recordSession(selfResult.prUrl);
@@ -3962,6 +4050,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       existingPrUrl: continuingPrUrl,
       settleId,
       runId,
+      provenance: githubProvenance({ cfg, me, message, channelId, runId, summary: staged.summary }),
       usageArgs: reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),
     });
     // The settle already flipped the card to the report (body + metadata); editing
@@ -4024,6 +4113,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     parentId: threadRoot,
     existingPrUrl: continuingPrUrl,
     runId,
+    provenance: githubProvenance({ cfg, me, message, channelId, runId, summary: staged.summary }),
     // Normally {} — a gated run already reported its spend on the proposal card
     // it is now shipping. Anything the CLI spent after that still comes home.
     usageArgs: reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),

package/src/mcp.mjs

@@ -48,13 +48,20 @@ export function makeClient({ url, token }) {
     }
   }
 
-  async function listToolNames() {
+  // Full tool objects, schemas included — capability sniffing reads these
+  // (0866: an ARG-level addition like waitMs shows up in a tool's inputSchema,
+  // not in the tool list's names).
+  async function listTools() {
     try {
-      return ((await rpc("tools/list"))?.tools ?? []).map((t) => t.name);
+      return (await rpc("tools/list"))?.tools ?? [];
     } catch {
       return [];
     }
   }
 
-  return { rpc, tool, listToolNames };
+  async function listToolNames() {
+    return (await listTools()).map((t) => t.name);
+  }
+
+  return { rpc, tool, listTools, listToolNames };
 }

package/src/progress-emitter.mjs

@@ -57,7 +57,8 @@ export function detectVendor(codingCmd) {
  * Code installed just to answer chat (0521). Every command is the vendor's
  * verified non-interactive print mode; the daemon appends the prompt as the last
  * arg. codex carries --skip-git-repo-check because chat (and the read-only
- * review sandbox) can run outside a git checkout. cursor carries
+ * review sandbox) can run outside a git checkout, plus the explicit web-search
+ * config because `codex exec` otherwise leaves that tool off. cursor carries
  * --output-format text (explicit, so a CLI default change can never post raw
  * JSONL into the channel) and --trust (its Jan-2026 workspace-trust gate fails
  * headless runs at spawn in untrusted directories — 0572; pre-2026 CLIs reject
@@ -70,7 +71,9 @@ export function detectVendor(codingCmd) {
  */
 export function fastChatCmd(vendor) {
   if (vendor === "claude_code") return "claude -p --model haiku";
-  if (vendor === "codex") return "codex exec --skip-git-repo-check";
+  if (vendor === "codex") {
+    return "codex exec --skip-git-repo-check -c tools.web_search=true";
+  }
   if (vendor === "cursor") return "cursor-agent -p --output-format text --trust";
   if (vendor === "opencode") return "opencode run";
   if (vendor === "antigravity") return "agy -p";
@@ -107,6 +110,31 @@ export function codeStreamArgs(vendor) {
   return [];
 }
 
+/**
+ * Make Codex's built-in public web search available to code runs. This is a
+ * capability flag, not an instruction to browse; Codex decides whether the
+ * task needs it. An operator's explicit true/false override wins unchanged.
+ * Other vendors already expose their own web tools and receive no guessed
+ * flags.
+ * @param {'claude_code'|'codex'|'cursor'|'opencode'|'antigravity'|'hermes'|'unknown'} vendor
+ * @param {string[]} baseArgs
+ * @returns {string[]}
+ */
+export function codeWebArgs(vendor, baseArgs = []) {
+  if (vendor !== "codex") return [];
+  const hasOverride = baseArgs.some((arg, index) => {
+    if (/^tools\.web_search=/.test(arg)) return true;
+    if (
+      (baseArgs[index - 1] === "-c" || baseArgs[index - 1] === "--config") &&
+      /^tools\.web_search=/.test(arg)
+    ) {
+      return true;
+    }
+    return /^--config=tools\.web_search=/.test(arg);
+  });
+  return hasOverride ? [] : ["-c", "tools.web_search=true"];
+}
+
 /**
  * Extra args that hand the code run an IMAGE, appended to the code run's argv
  * (0779). Verified against the installed binaries, per the 0521 rule — never

package/src/run.mjs

@@ -5,6 +5,7 @@
 import { hostname } from "node:os";
 import { basename } from "node:path";
 import { makeClient } from "./mcp.mjs";
+import { loadMentionCursor, saveMentionCursor } from "./cursor-store.mjs";
 import { mentionHandle } from "./daemon.mjs";
 import { handleTask } from "./handler.mjs";
 import { createQueue, looksLikeCancel, dedupeKey } from "./queue.mjs";
@@ -59,7 +60,7 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     return;
   }
 
-  const { tool, listToolNames } = makeClient({ url: cfg.url, token: cfg.token });
+  const { tool, listTools, listToolNames } = makeClient({ url: cfg.url, token: cfg.token });
 
   const who = await tool("whoami");
   const me = { ...who, handle: mentionHandle(who.agentName) };
@@ -72,8 +73,23 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   log.log(`repos: ${Object.keys(cfg.repos).join(", ") || "(none configured)"}`);
 
   const since = cfg.backfill ? 0 : Date.now();
-  const toolNames = await listToolNames();
+  // listTools (schemas included) is the primary read; a client exposing only
+  // listToolNames (an embedder's minimal mock, or an older embedded client)
+  // still names the tools — it just never advertises arg-level capabilities.
+  const toolList = typeof listTools === "function" ? await listTools() : [];
+  const toolNames = toolList.length
+    ? toolList.map((t) => t.name)
+    : typeof listToolNames === "function"
+      ? await listToolNames()
+      : [];
   const useMentions = toolNames.includes("list_mentions");
+  // Arg-level capability sniffing (0866): a long-poll-capable server declares
+  // `waitMs` in the tool's inputSchema. Absent (older server) → the daemon
+  // falls back to plain interval polling, exactly as before.
+  const toolArgProps = (name) =>
+    toolList.find((t) => t.name === name)?.inputSchema?.properties ?? {};
+  const serverMentionWait = "waitMs" in toolArgProps("list_mentions");
+  const serverDecisionWait = "waitMs" in toolArgProps("get_permission_decision");
   // Capabilities of THIS server, so the handler degrades gracefully on older
   // deploys (e.g. no edit_message → no live heartbeat, rather than erroring).
   const caps = {
@@ -112,6 +128,10 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     // that needs no words. Absent on older servers → the agent stays quiet
     // instead, exactly as if it had no hand to wave.
     react: toolNames.includes("add_reaction"),
+    // Long-poll hold for the permission gate (0866): each decision read blocks
+    // server-side until a human decides, so an Allow reaches the paused tool in
+    // under a second instead of on the gate's next poll. 0 on older servers.
+    decisionWaitMs: serverDecisionWait ? 20000 : 0,
   };
 
   // The wake doorbell (0824): capability-checked like every optional surface.
@@ -190,7 +210,16 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   emit({ type: "status", text: useMentions ? "watching @-mentions" : `watching ${channelIds.length} channel(s)` });
 
   const seen = new Set();
-  const cursor = { value: since ? new Date(since).toISOString() : null };
+  // Resume from the persisted cursor (0866) so mentions that arrived while the
+  // daemon was down are delivered on restart instead of silently skipped —
+  // bounded by catchupMs. `backfill` still means "from the beginning" and wins.
+  const persistedCursor = cfg.backfill
+    ? null
+    : loadMentionCursor(me.agentId, { catchupMs: cfg.catchupMs });
+  if (persistedCursor) log.log(`resuming mention cursor from ${persistedCursor}`);
+  const cursor = {
+    value: persistedCursor ?? (since ? new Date(since).toISOString() : null),
+  };
   // 0860 — a DM message inside its settle window: the server withheld it and
   // said when it matures. One shortened sleep picks it up right then, instead
   // of the person waiting out the full poll interval mid-conversation.
@@ -343,10 +372,18 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     }
   }
 
+  // Long-poll (0866): ask a capable server to HOLD the request and answer the
+  // moment a mention lands — pickup latency stops being pollMs. The server
+  // caps a hold at 25s; asking for more just gets 25s.
+  const mentionWaitMs = () =>
+    serverMentionWait && liveCfg.longPollMs > 0 ? Math.floor(liveCfg.longPollMs) : 0;
+
   async function passViaMentions() {
+    const waitMs = mentionWaitMs();
     const mentionArgs = {
       ...(cursor.value ? { since: cursor.value } : {}),
       ...(cfg.channelId ? { channelId: cfg.channelId } : {}),
+      ...(waitMs ? { waitMs } : {}),
     };
     const out = await tool("list_mentions", mentionArgs);
     // Floor the server's settle hint so a clock skew can never hot-loop the poll.
@@ -355,6 +392,7 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
         ? Math.max(500, out.retryAfterMs)
         : null;
     const mentions = (out?.mentions ?? []).slice().reverse();
+    let advanced = false;
     for (const m of mentions) {
       if (seen.has(m.id)) continue;
       seen.add(m.id);
@@ -365,6 +403,7 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
       if (m.parentId && boundThreadRoots.has(m.parentId)) {
         if (!cursor.value || new Date(m.created_at).getTime() > new Date(cursor.value).getTime()) {
           cursor.value = m.created_at;
+          advanced = true;
         }
         continue;
       }
@@ -373,8 +412,17 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
       // so a lexicographic string compare can fail to advance the cursor.
       if (!cursor.value || new Date(m.created_at).getTime() > new Date(cursor.value).getTime()) {
         cursor.value = m.created_at;
+        advanced = true;
       }
     }
+    // Persist on advance only — an idle pass has nothing new to remember —
+    // and only while catch-up is enabled: with catchupMs 0 the file would
+    // never be read back, so writing it would be pure disk noise (this is
+    // also what keeps embedded/mocked runs from touching a real ~/.hilos).
+    // Best-effort: a failed write degrades to restart-at-now, never a crash.
+    if (advanced && cursor.value && liveCfg.catchupMs > 0) {
+      saveMentionCursor(me.agentId, cursor.value, { log });
+    }
   }
 
   async function passViaReplyBridge() {
@@ -432,11 +480,13 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     } catch (e) {
       log.error(`config reload error (keeping previous): ${e.message}`);
     }
+    let passFailed = false;
     try {
       await passViaReplyBridge();
       if (useMentions) await passViaMentions();
       else await passViaScan();
     } catch (e) {
+      passFailed = true;
       log.error(`poll error: ${e.message}`);
     }
     // --once is for cron-style single passes: drain the queued work before exit.
@@ -446,11 +496,15 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     }
     if (signal?.aborted) break;
     // Interruptible so an abort during the sleep returns promptly instead of
-    // waiting out the full poll interval. A settling DM (0860) shortens one
-    // sleep to the server's hint; the doorbell still cuts either short.
-    await interruptibleSleep(
-      pollAgainMs != null ? Math.min(liveCfg.pollMs, pollAgainMs) : liveCfg.pollMs,
-    );
+    // waiting out the full poll interval, and the doorbell (0824) still cuts
+    // any sleep short. A long-polled pass (0866) already spent its waiting
+    // inside the held request, so only a short breather follows it — unless
+    // the pass FAILED, where re-holding immediately would hammer a hiccuping
+    // server; an error always backs off by the full pollMs. A settling DM
+    // (0860) shortens one sleep to the server's hint in either mode.
+    const held = useMentions && mentionWaitMs() > 0 && !passFailed;
+    const base = held ? 250 : liveCfg.pollMs;
+    await interruptibleSleep(pollAgainMs != null ? Math.min(base, pollAgainMs) : base);
   } while (!signal?.aborted);
 
   // Clean stop: close the doorbell socket, make sure any active job is cancelled