hilos-agent 0.9.2 → 0.9.3

package/README.md

@@ -4,7 +4,8 @@ Run **your own** coding agent — Claude Code, Codex, Cursor, opencode, Hermes,
 an autonomous teammate inside a [hilos](https://hilos.sh) channel.
 
 It connects to hilos over MCP, watches for `@mentions` of your agent in a
-git-linked channel (including thread replies), runs your coding agent in a
+git-linked channel (including thread replies) and for **every message in a DM
+with your agent — no tag needed there**, runs your coding agent in a
 **local** checkout, and — by default — **opens a PR for review**. Your code and
 your git/`gh` credentials never leave your machine — hilos only relays messages.
 
@@ -31,7 +32,7 @@ needed:
 
 ```sh
 cd ~/code/your-repo
-npx hilos-agent --join <blob>        # token + endpoint from the link; repo auto-detected from cwd
+npx hilos-agent@latest --join <blob> # token + endpoint from the link; repo auto-detected from cwd
 ```
 
 Running from elsewhere, or want to map several repos explicitly? Use a config:
@@ -43,7 +44,7 @@ Running from elsewhere, or want to map several repos explicitly? Use a config:
   "token": "mgo_…",
   "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
   "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text --trust", "opencode run", "agy -p", any command
-  "codingModel": "",  // model preset tier ("opus" | "sonnet" | "haiku") resolved at run time against the CLI's own model list (Cursor only today); "" = the tool's default
+  "codingModel": "",  // Codex tier ("most-capable" | "balanced" | "fastest"), resolved against this account's own model list; "" = the tool's default
   "chatCmd": "",  // FAST command for chat replies + the plan-ack. Empty = derived from codingCmd's tool (codex daemons chat with codex, etc.); set to override
   "defaultBranch": "main",
   "gate": false,               // default: open a PR directly. true = approve-before-push
@@ -73,7 +74,14 @@ hilos-agent --channel <id>   # scope to one channel
 
 ## How it works
 
-- **Trigger** — an `@mention` of your agent in a channel that's linked to a repo.
+- **Trigger** — an `@mention` of your agent in a channel that's linked to a repo,
+  or any message in a DM with your agent (a DM is the address — no tag needed;
+  there, and only there, the agent may also answer with an emoji reaction or
+  stay quiet when a message truly needs nothing).
+  Mentions are picked up by polling; on servers that expose `get_wake_channel`,
+  a realtime doorbell (a content-free broadcast on every new message) wakes the
+  poll instantly, so pickup takes about a second instead of a poll interval
+  (needs Node >= 22 for the built-in WebSocket; otherwise it just keeps polling).
 - **Chat or code?** — the agent reads the conversation and decides with the model
   (via `chatCmd`), not a keyword list: a question/greeting/"let's just discuss" →
   a chat reply; anything asking for a change — including "just code it", "finish
@@ -189,13 +197,15 @@ backward compatible — omit them and the CLI behaves exactly as before.
 
 ## Model & permissions
 
-You don't have to hand-write `codingCmd`: the agent's **Connect via MCP** panel in
-hilos has **Model** (Vendor default / Opus / Sonnet / Haiku) and **Permissions**
-(Ask before edits / Auto-approve edits / Skip all prompts) pickers that bake your
-choice into the generated `--coding-cmd`. Change it later by editing `codingCmd` in
-`hilos-agent.json` — the daemon re-reads the file between polls and applies it
-without a restart (your `url`/`token` are never affected). The next section
-explains what each permission level means.
+You don't have to hand-write `codingCmd`: the agent's connection panel emits
+the selected provider's real executable and verified flags. Claude Code uses
+its stable `opus` / `sonnet` / `haiku` aliases. Codex carries a neutral
+`most-capable` / `balanced` / `fastest` tier that resolves against that
+account's own live catalog. Cursor, opencode, Antigravity, and Hermes keep their
+own model setting because no universal tier maps honestly onto their catalogs.
+Unsupported permission choices are omitted from the UI. Change the command
+later in `hilos-agent.json`; the daemon re-reads it between polls without
+touching the token.
 
 ## Permissions / autonomy
 
@@ -246,15 +256,15 @@ becomes the next turn in the same local session and checkout.
 
 ```sh
 # Inside the repo you want to stream:
-npx hilos-agent hooks install
+npx hilos-agent@latest hooks install
 
 # Install only one provider, if you prefer:
-npx hilos-agent hooks install --codex
-npx hilos-agent hooks install --claude
-npx hilos-agent hooks install --cursor
+npx hilos-agent@latest hooks install --codex
+npx hilos-agent@latest hooks install --claude
+npx hilos-agent@latest hooks install --cursor
 
 # Or opt in every repo on this machine:
-npx hilos-agent hooks install --global
+npx hilos-agent@latest hooks install --global
 ```
 
 Claude Code and Cursor write lifecycle entries into this repo. Codex needs one
@@ -274,7 +284,7 @@ therefore remains usable offline; no global install or PATH change is required.
 Preview all three blocks without writing anything:
 
 ```sh
-npx hilos-agent hooks print
+npx hilos-agent@latest hooks print
 ```
 
 **Requirements:**

package/bin/hilos-agent.mjs

@@ -75,12 +75,14 @@ Options:
   --channel <id>     watch only one channel (per-channel override)
   --config <path>    use a specific config file
   --coding-cmd <cmd> the coding agent to run — claude -p, codex exec,
-                     cursor-agent -p --trust, opencode run, agy -p, hermes,
+                     cursor-agent -p --trust, opencode run, agy -p, hermes -z,
                      or any command
-                     that takes a prompt as its last arg (default: "claude -p")
-  --coding-model <tier>  model preset tier (opus | sonnet | haiku) resolved at
+                     that takes a prompt as its last arg (default:
+                     "claude -p --permission-mode acceptEdits")
+  --coding-model <tier>  model tier (default | most-capable | balanced | fastest)
+                     resolved at
                      run time against the CLI's own model list — never a baked
-                     id (Cursor only today; default: the tool's own model)
+                     id (Codex only today; default: the tool's own model)
   --chat-cmd <cmd>   fast command for chat replies + the plan-ack (default:
                      derived from the coding command, so a Codex or Cursor
                      daemon chats with its own tool)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "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/config.mjs

@@ -103,9 +103,10 @@ const DEFAULTS = {
   codingEnv: "inherit",
   codingEnvAllow: [],
   // Model preset TIER for the coding run ("" / "default" = the tool's own
-  // default). "opus" | "sonnet" | "haiku" resolve at RUN time against the
-  // CLI's own model list — never a baked id that could 404 on another account
-  // (0504; cursor only today, see model-resolve.mjs).
+  // default). "most-capable" | "balanced" | "fastest" resolve at RUN time
+  // against Codex's own model list — never a baked id that could 404 on
+  // another account. The original opus/sonnet/haiku and Cursor values remain
+  // accepted as backward-compatible read aliases (0864).
   codingModel: "",
   // Chat replies + the code-task plan-ack use a FAST one-shot command so a casual
   // reply (or "I see it, here's my plan") comes back in seconds, not minutes.

package/src/handler.mjs

@@ -992,6 +992,58 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
 // code. Unusual on purpose so it can't be confused with a real chat reply.
 const CODE_SIGNAL = "__CODE__";
 
+// 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
+// what arrives genuinely needs nothing: a closing "thanks", an "ok", an aside.
+// The model may answer those with this token instead of words — optionally
+// followed by one emoji to react with. An explicit @-mention NEVER gets this
+// option: a summons deserves a reply, and silence there is the exact
+// "agent ignores me" failure this ticket exists to end.
+export const NO_REPLY_SIGNAL = "__NO_REPLY__";
+
+/**
+ * Read the quiet-option sentinel off a chat model's output. Counts only when
+ * the FIRST non-empty line is the token alone or the token plus one emoji-ish
+ * word (no letters or digits — "__NO_REPLY__ ok" is a malformed reply, not a
+ * reaction, and posts as text so nothing a person needs gets eaten silently).
+ * @param {string} text
+ * @returns {{ noReply: boolean, emoji: string | null }}
+ */
+export function parseNoReply(text) {
+  const firstLine = String(text || "")
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  if (!firstLine || !firstLine.startsWith(NO_REPLY_SIGNAL)) {
+    return { noReply: false, emoji: null };
+  }
+  const rest = firstLine.slice(NO_REPLY_SIGNAL.length).trim();
+  if (!rest) return { noReply: true, emoji: null };
+  const tokens = rest.split(/\s+/);
+  const [emoji] = tokens;
+  if (tokens.length === 1 && emoji.length <= 16 && !/[A-Za-z0-9]/.test(emoji)) {
+    return { noReply: true, emoji };
+  }
+  return { noReply: false, emoji: null };
+}
+
+/**
+ * The prompt paragraph that grants the quiet option. Empty unless this wake is
+ * an untagged DM message — the ONLY context where not answering is ever right.
+ */
+export function dmJudgmentBlock(implicitDm) {
+  if (!implicitDm) return "";
+  return (
+    `\n\nThis is a direct-message conversation with you: the latest message reached you ` +
+    `because every DM message does — nobody typed your @-handle. Almost every message still ` +
+    `deserves your reply, and when in doubt, reply. But if the latest message truly needs ` +
+    `nothing from you — a closing "thanks" or "ok", a nicety, or something clearly said to ` +
+    `another person in this conversation — output ONLY the token ${NO_REPLY_SIGNAL}, ` +
+    `optionally followed by a single emoji to react with instead (e.g. ${NO_REPLY_SIGNAL} 👍). ` +
+    `Never use ${NO_REPLY_SIGNAL} on a question, a request, or anything that expects an answer.`
+  );
+}
+
 /**
  * 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
@@ -1012,7 +1064,7 @@ const CODE_SIGNAL = "__CODE__";
  * `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 }) {
+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);
@@ -1046,7 +1098,8 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
     `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.\n\n` +
+    `edit files, do NOT run commands; a separate step does the actual coding.` +
+    `${dmJudgmentBlock(implicitDm)}\n\n` +
     `${memoryPreamble(workspaceMemory)}Conversation so far:\n${transcript}`;
   const run = await doRun({
     cmd: parts[0],
@@ -1075,6 +1128,12 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
     const nl = after.indexOf("\n");
     return { code: true, task: (nl >= 0 ? after.slice(nl + 1) : after).trim(), followupSignal };
   }
+  // The quiet option (0860) — only ever offered (and only ever honored) on an
+  // untagged DM wake, so a tagged summons can never be answered with silence.
+  if (implicitDm) {
+    const quiet = parseNoReply(out);
+    if (quiet.noReply) return { code: false, noReply: true, emoji: quiet.emoji, followupSignal };
+  }
   return { code: false, reply: out, followupSignal };
 }
 
@@ -1237,9 +1296,19 @@ async function proposePlanAck({ task, transcript, repoFullName, cfg, signal }) {
   return text.length > 400 ? text.slice(0, 399) + "…" : text;
 }
 
+/**
+ * React to the wake's message instead of replying (0860). Best-effort and
+ * capability-gated: on an older server (no add_reaction) or any failure the
+ * agent simply stays quiet, which is what the model chose anyway.
+ */
+async function reactQuietly({ tool, caps, message, emoji }) {
+  if (!emoji || !caps?.react || !message?.id) return;
+  await tool("add_reaction", { messageId: message.id, emoji }).catch(() => {});
+}
+
 /** Run the FAST chat CLI to produce a reply, using recent channel context. */
 async function respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps = {} }) {
-  void message;
+  const implicitDm = message?.implicit === "dm";
   const { transcript } = context || (await fetchContext({ channelId, tool, parentId }));
   const name = me?.agentName || "an assistant";
   // Tell the agent what the room is connected to so it doesn't ask "which repo?".
@@ -1255,7 +1324,8 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
   const prompt =
     `You are ${name}, a teammate in a team chat (hilos). Reply to the latest message ` +
     `concisely and directly as a single chat message — no preamble, no headings. ` +
-    `${repoLine}\n\n` +
+    `${repoLine}` +
+    `${dmJudgmentBlock(implicitDm)}\n\n` +
     `${memoryPreamble(workspaceMemory)}` +
     `Conversation so far:\n${transcript}`;
 
@@ -1320,6 +1390,21 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
   }
   const reply = (run.stdout || "").trim();
   if (run.error) console.log(`  ! ${parts[0]}: ${run.error.message}`);
+  // The quiet option (0860), honored only on an untagged DM wake. If a slow
+  // decision already posted a "Still thinking…" ping, silence would strand it
+  // — settle the ping with the reaction emoji (or a plain nod) instead.
+  if (implicitDm) {
+    const quiet = parseNoReply(reply);
+    if (quiet.noReply) {
+      console.log(`  chat → quiet${quiet.emoji ? ` (reacting ${quiet.emoji})` : " (no reply needed)"}`);
+      if (thinkingId) {
+        await deliver(quiet.emoji || "👍");
+      } else {
+        await reactQuietly({ tool, caps, message, emoji: quiet.emoji });
+      }
+      return;
+    }
+  }
   console.log(`  chat → ${reply ? `replied (${reply.length} chars)` : "no output"}; posting`);
   // Honest fallback: a timeout is NOT a missing binary. Only a real spawn failure
   // (ENOENT) means the command isn't on PATH.
@@ -2407,6 +2492,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   const onStopRequested = opts.onStopRequested;
   // When the mention was a thread reply, keep the whole exchange in that thread.
   const parentId = message.parentId ?? null;
+  // 0860 — an untagged DM wake: addressed by the room, not by an @-handle. The
+  // one context where the router/chat prompts offer the quiet option.
+  const implicitDm = message.implicit === "dm";
 
   const { links = [] } = await tool("get_links", { channelId }).catch(() => ({ links: [] }));
   // A folder link (0324) carries the folder PATH in repo_full_name for display —
@@ -2598,12 +2686,17 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
                 cfg,
                 signal,
                 runCliFn: deps.runCli,
+                implicitDm,
               });
       }
       if (routed.aborted || signal?.aborted) {
         await tool("post_message", { channelId, parentId, body: "Stopped." });
         return { status: "chat" };
       }
+      if (routed.noReply) {
+        await reactQuietly({ tool, caps, message, emoji: routed.emoji });
+        return { status: "quiet" };
+      }
       if (routed.code) {
         return await handleFolderTask({
           message,
@@ -2676,12 +2769,17 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           cfg,
           signal,
           hasActiveRun: activeRunOpen,
+          implicitDm,
         });
   if (routed.aborted || signal?.aborted) {
     await tool("post_message", { channelId, parentId, body: "Stopped." });
     return { status: "chat" };
   }
   if (!routed.code) {
+    if (routed.noReply) {
+      await reactQuietly({ tool, caps, message, emoji: routed.emoji });
+      return { status: "quiet" };
+    }
     let body = routed.reply;
     if (!body) {
       body =

package/src/model-resolve.mjs

@@ -1,23 +1,20 @@
-// Runtime model-preset resolution (0504). The connect UI offers capability
-// TIERS (Most capable / Balanced / Fastest), but Cursor's model ids are
-// account- and plan-specific and churn weekly — a baked id that works for one
-// user 404s for another, which is why VENDOR_CLI.cursor.model stayed empty for
-// months. So the tier resolves HERE, at run time, against the account's OWN
-// `cursor-agent --list-models` output: we only ever emit an id the CLI itself
-// just listed, and when nothing matches we emit no flag at all (the tool's
-// default — `auto` routing — stands). Never a guessed id, never a wrong flag.
-//
-// Design rules (mirror the .mjs siblings): the parse/resolve transforms are
-// PURE + node-builtins-only; the resolver takes an injected `run` (runCli) so
-// tests drive it with no CLI; a resolution failure NEVER breaks a run ([]).
-//
-// codex joined in 0783 on the SAME terms: `codex debug models` ("Render the raw
+// Runtime model-preset resolution (0504). Codex gets provider-neutral tiers in
+// new commands: `codex debug models` ("Render the raw
 // model catalog as JSON") is its `--list-models`, so its tier also resolves at
 // run time against the account's own catalog and never against a baked slug.
 // That matters more for codex than for anyone: its slugs are codenames that rev
 // (`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` in the live catalog) and are
 // plan-gated — a run on a ChatGPT account rejects `gpt-5` outright with "The
 // 'gpt-5' model is not supported when using Codex with a ChatGPT account".
+//
+// Cursor remains below only as a compatibility reader for existing 0.9.2
+// configs that stored the old Anthropic-shaped tier names. New Hilos commands
+// do not set a Cursor tier: Cursor's catalog mixes providers and account-only
+// ids, so its own `auto` model choice is the only honest default.
+//
+// Design rules (mirror the .mjs siblings): the parse/resolve transforms are
+// PURE + node-builtins-only; the resolver takes an injected `run` (runCli) so
+// tests drive it with no CLI; a resolution failure NEVER breaks a run ([]).
 
 /** Strip ANSI SGR color codes (`--list-models` output is colorized). */
 export function stripAnsi(s) {
@@ -55,6 +52,24 @@ const TIER_PREFS = {
   haiku: [/^composer.*fast/, /-fast$/],
 };
 
+/**
+ * Public tier names are provider-neutral. Keep the original Anthropic-shaped
+ * values as read aliases so existing hilos-agent.json files and already-copied
+ * commands continue to work after 0.9.3.
+ */
+export function normalizeModelTier(tier) {
+  const value = String(tier || "").trim().toLowerCase();
+  return ({
+    "most-capable": "opus",
+    balanced: "sonnet",
+    fastest: "haiku",
+    opus: "opus",
+    sonnet: "sonnet",
+    haiku: "haiku",
+    default: "default",
+  })[value] || "";
+}
+
 /**
  * Pick the account's model id for a tier, or null when nothing fits.
  * @param {'opus'|'sonnet'|'haiku'|string} tier
@@ -62,7 +77,7 @@ const TIER_PREFS = {
  * @returns {string|null}
  */
 export function resolveCursorModel(tier, ids) {
-  const prefs = TIER_PREFS[tier];
+  const prefs = TIER_PREFS[normalizeModelTier(tier)];
   if (!prefs || !Array.isArray(ids)) return null;
   for (const re of prefs) {
     const hit = ids.find((id) => typeof id === "string" && re.test(id));
@@ -181,13 +196,14 @@ const CODEX_TIER_PREFS = {
  * @returns {string|null}
  */
 export function resolveCodexModel(tier, models) {
-  const prefs = CODEX_TIER_PREFS[tier];
+  const normalized = normalizeModelTier(tier);
+  const prefs = CODEX_TIER_PREFS[normalized];
   if (!prefs || !Array.isArray(models) || models.length === 0) return null;
   for (const re of prefs) {
     const hit = models.find((m) => m && typeof m.text === "string" && re.test(m.text));
     if (hit) return hit.slug;
   }
-  if (tier === "haiku") return models[models.length - 1].slug;
+  if (normalized === "haiku") return models[models.length - 1].slug;
   return models[0].slug;
 }
 
@@ -231,7 +247,7 @@ export function createModelArgsResolver({ run } = {}) {
   return async function modelArgsFor(cfg, vendor) {
     try {
       const spec = LIST_MODELS[vendor];
-      const tier = String(cfg?.codingModel || "").trim();
+      const tier = normalizeModelTier(cfg?.codingModel);
       if (!spec || !tier || tier === "default") return [];
       const cmd = String(cfg?.codingCmd || "");
       // Hand-pinned wins — including codex's short spelling (`-m gpt-5.6-sol`),

package/src/progress-emitter.mjs

@@ -69,7 +69,7 @@ export function detectVendor(codingCmd) {
  * @returns {string}
  */
 export function fastChatCmd(vendor) {
-  if (vendor === "claude_code") return "claude -p --model claude-haiku-4-5";
+  if (vendor === "claude_code") return "claude -p --model haiku";
   if (vendor === "codex") return "codex exec --skip-git-repo-check";
   if (vendor === "cursor") return "cursor-agent -p --output-format text --trust";
   if (vendor === "opencode") return "opencode run";

package/src/run.mjs

@@ -10,6 +10,7 @@ import { handleTask } from "./handler.mjs";
 import { createQueue, looksLikeCancel, dedupeKey } from "./queue.mjs";
 import { cleanupImages, fetchMentionImages } from "./attachments.mjs";
 import { reloadConfig } from "./config.mjs";
+import { startWake, createWakeGate } from "./wake.mjs";
 import { scanReplyBridge, handleReplyBridgeJob } from "./reply-bridge.mjs";
 
 /**
@@ -44,21 +45,13 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
       /* a bad event listener must never break the daemon */
     }
   };
-  // A sleep that resolves immediately when the signal aborts, so "stop" doesn't
-  // wait out the whole poll interval.
-  const interruptibleSleep = (ms) =>
-    new Promise((resolve) => {
-      if (signal?.aborted) return resolve();
-      const timer = setTimeout(() => {
-        signal?.removeEventListener?.("abort", onAbort);
-        resolve();
-      }, ms);
-      function onAbort() {
-        clearTimeout(timer);
-        resolve();
-      }
-      signal?.addEventListener?.("abort", onAbort, { once: true });
-    });
+  // The wake doorbell (0824): a Realtime ping resolves the pending inter-poll
+  // sleep so the next list_mentions poll happens NOW. A ping that lands while a
+  // poll is still running is remembered, so the following sleep returns
+  // immediately instead of the ping being lost to the race. That race lives in
+  // createWakeGate (wake.mjs) so it can be unit-tested; the sleep it hands back
+  // also resolves on abort, so "stop" never waits out the poll interval.
+  const { ping: onWakePing, sleep: interruptibleSleep } = createWakeGate({ signal });
 
   // Already asked to stop before we even connect → return cleanly, do nothing.
   if (signal?.aborted) {
@@ -115,8 +108,45 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     // server has to offer the tool, and the operator has to have turned
     // `uploadTranscripts` on. Older servers simply never see the call.
     uploadTranscript: toolNames.includes("upload_run_transcript"),
+    // Emoji reactions (0860): the lightest answer to an untagged DM message
+    // 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"),
   };
 
+  // The wake doorbell (0824): capability-checked like every optional surface.
+  // On an older server the tool is absent and the daemon polls exactly as
+  // before; with it, a new message in the workspace rings a content-free
+  // Realtime broadcast that cuts mention pickup from pollMs to instant.
+  let wake = null;
+  if (toolNames.includes("get_wake_channel")) {
+    try {
+      const chan = await tool("get_wake_channel");
+      if (chan?.url && chan?.topic) {
+        // Pass a RESOLVER, not the fetched value: wake.mjs re-asks on every
+        // reconnect and on a slow refresh timer, so if the workspace rotates
+        // its doorbell topic (rotate_wake_topic, after a leak) this daemon
+        // picks the new one up on its own instead of going quietly deaf until
+        // someone restarts it. First call reuses what we already have.
+        let first = chan;
+        wake = startWake(
+          async () => {
+            if (first) {
+              const f = first;
+              first = null;
+              return f;
+            }
+            return await tool("get_wake_channel");
+          },
+          { onWake: onWakePing, log },
+        );
+        log.log("wake: realtime doorbell enabled (polling stays as fallback)");
+      }
+    } catch (e) {
+      log.log(`wake: unavailable (${e.message}) — polling only`);
+    }
+  }
+
   // Register local folders (0324/0325): a folder-mode daemon announces each
   // channel→folder mapping to the server so the channel shows a folder chip
   // without any manual step. Capability-gated on the server advertising
@@ -161,6 +191,10 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
 
   const seen = new Set();
   const cursor = { value: 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.
+  let pollAgainMs = null;
 
   // Live config: re-read between polls so model/permission/codingCmd edits to
   // hilos-agent.json take effect without a restart. Identity stays pinned.
@@ -297,7 +331,10 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     // A report-card deploy decision is already visible in place. list_mentions
     // projects the pending decision into this structured event, so don't add a
     // misleading "queued" chat line while the active run settles it.
-    if (liveCfg.queueAcks && !r.startedImmediately && !m.deployRequest) {
+    // An untagged DM message (0860) skips the ack too: nobody summoned the
+    // agent, so "Got it — queued" over a line that may deserve no reply at all
+    // is exactly the noise the implicit lane promises not to make.
+    if (liveCfg.queueAcks && !r.startedImmediately && !m.deployRequest && !m.implicit) {
       await tool("post_message", {
         channelId,
         parentId: m.parentId ?? null,
@@ -312,6 +349,11 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
       ...(cfg.channelId ? { channelId: cfg.channelId } : {}),
     };
     const out = await tool("list_mentions", mentionArgs);
+    // Floor the server's settle hint so a clock skew can never hot-loop the poll.
+    pollAgainMs =
+      typeof out?.retryAfterMs === "number" && out.retryAfterMs > 0
+        ? Math.max(500, out.retryAfterMs)
+        : null;
     const mentions = (out?.mentions ?? []).slice().reverse();
     for (const m of mentions) {
       if (seen.has(m.id)) continue;
@@ -404,13 +446,17 @@ 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.
-    await interruptibleSleep(liveCfg.pollMs);
+    // 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,
+    );
   } while (!signal?.aborted);
 
-  // Clean stop: make sure any active job is cancelled (the abort listener already
-  // fired for the common case, but this covers a break for other reasons) and let
-  // in-flight teardown settle before returning.
+  // Clean stop: close the doorbell socket, make sure any active job is cancelled
+  // (the abort listener already fired for the common case, but this covers a
+  // break for other reasons) and let in-flight teardown settle before returning.
+  wake?.stop();
   if (signal?.aborted) {
     queue.cancelActive("run() aborted");
   }

package/src/wake.mjs

@@ -0,0 +1,288 @@
+// The Realtime wake doorbell (0824). Subscribes to the workspace's broadcast
+// topic (from the get_wake_channel tool) so a new message wakes the poll loop
+// instantly instead of waiting out pollMs. Dependency-free by design, like
+// mcp.mjs: this speaks the small slice of the Supabase Realtime (Phoenix)
+// protocol the doorbell needs over the global WebSocket (Node >= 22).
+//
+// What the credentials here are worth, so nobody mistakes one for the other:
+//   * `anonKey` is the project's PUBLIC key — the same string every page of the
+//     web app ships in its bundle. It grants nothing on its own: every table a
+//     daemon cares about is RLS-gated and the anon role has no membership, so
+//     it reads zero rows (asserted in scripts/verify-agent-wake.mjs).
+//   * `topic` is the actual secret. The broadcast is public (private=false), so
+//     the topic string is what gates the doorbell. All it buys is one repeated
+//     bit — "a message was posted somewhere in this workspace" — never content.
+//     If it leaks, an owner rotates it (rotate_wake_topic) and this client
+//     re-resolves on its own; see the `source` resolver below.
+//
+// Fail-soft everywhere: the doorbell is an accelerator, never a dependency.
+// No WebSocket global, a bad URL, a rejected join, a dropped socket — all of it
+// degrades to exactly the polling behavior the daemon has always had.
+
+const HEARTBEAT_MS = 25_000;
+const RECONNECT_MIN_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
+// A join that never gets its ok reply is a dead doorbell that LOOKS alive.
+// Give it a bounded window, then recycle the socket.
+const JOIN_TIMEOUT_MS = 15_000;
+// How often to re-ask the server for the topic when it did not tell us. Bounds
+// how long a rotated topic can leave a daemon on plain polling.
+const DEFAULT_REFRESH_MS = 15 * 60_000;
+
+/**
+ * Open (and keep open) the doorbell subscription.
+ *
+ * @param {{ url: string, anonKey: string, topic: string, refreshMs?: number }
+ *        | (() => Promise<{ url: string, anonKey: string, topic: string, refreshMs?: number }>)} source
+ *   Either a fixed get_wake_channel result, or an async resolver that fetches a
+ *   fresh one. Pass the resolver: it is re-run on every reconnect and on a slow
+ *   refresh timer, which is what makes a topic rotation heal itself instead of
+ *   silently dropping the daemon back to pollMs until someone restarts it.
+ * @param {{ onWake: () => void, log?: { log: Function, error: Function } }} opts
+ * @returns {{ stop: () => void }}
+ */
+export function startWake(source, { onWake, log = console }) {
+  const WS = globalThis.WebSocket;
+  if (typeof WS !== "function") {
+    log.log("wake: no WebSocket in this Node (need >= 22) — staying on polling only");
+    return { stop() {} };
+  }
+  const resolve =
+    typeof source === "function" ? source : async () => source;
+
+  let ws = null;
+  let stopped = false;
+  let heartbeat = null;
+  let joinTimer = null;
+  let reconnectTimer = null;
+  let refreshTimer = null;
+  let backoff = RECONNECT_MIN_MS;
+  let ref = 0;
+  let phxTopic = null;
+  let currentTopic = null;
+  let refreshMs = DEFAULT_REFRESH_MS;
+  let refreshArmed = false;
+
+  const send = (msg) => {
+    try {
+      if (ws?.readyState === WS.OPEN) ws.send(JSON.stringify(msg));
+    } catch {
+      /* a failed frame is the socket's problem; close/error handles it */
+    }
+  };
+
+  const teardown = () => {
+    if (heartbeat) clearInterval(heartbeat);
+    heartbeat = null;
+    if (joinTimer) clearTimeout(joinTimer);
+    joinTimer = null;
+    if (ws) {
+      ws.onopen = ws.onmessage = ws.onclose = ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+        /* already gone */
+      }
+      ws = null;
+    }
+  };
+
+  const scheduleReconnect = () => {
+    if (stopped || reconnectTimer) return;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, backoff);
+    // Capped, and only ever grows between successful joins — an endpoint that
+    // is down costs one attempt a minute, not a hot retry loop.
+    backoff = Math.min(backoff * 2, RECONNECT_MAX_MS);
+  };
+
+  // Recycle the socket: used for a rejected join, a join that never answered,
+  // and a server-side channel error. Each one leaves a socket that would
+  // otherwise sit there open and permanently deaf.
+  const recycle = (why) => {
+    if (stopped) return;
+    log.log(`wake: ${why} — retrying, polling continues`);
+    teardown();
+    scheduleReconnect();
+  };
+
+  async function connect() {
+    if (stopped) return;
+    teardown();
+
+    // Re-resolved every attempt, so a rotated topic is picked up here.
+    let chan;
+    try {
+      chan = await resolve();
+    } catch (e) {
+      log.error(`wake: could not get the doorbell topic (${e?.message || e}) — polling continues`);
+      return scheduleReconnect();
+    }
+    if (stopped) return;
+    if (!chan?.url || !chan?.anonKey || !chan?.topic) return scheduleReconnect();
+    if (Number.isFinite(chan.refreshMs) && chan.refreshMs > 0) refreshMs = chan.refreshMs;
+    currentTopic = chan.topic;
+    // Armed here, not at startup, so the FIRST interval already uses the
+    // server's refreshMs instead of the built-in default.
+    if (!refreshArmed) {
+      refreshArmed = true;
+      scheduleRefresh();
+    }
+
+    const wsUrl =
+      chan.url.replace(/^http/, "ws").replace(/\/$/, "") +
+      "/realtime/v1/websocket?apikey=" +
+      encodeURIComponent(chan.anonKey) +
+      "&vsn=1.0.0";
+    phxTopic = "realtime:" + chan.topic;
+
+    let sock;
+    try {
+      sock = new WS(wsUrl);
+    } catch (e) {
+      log.error(`wake: connect failed (${e.message}) — polling continues`);
+      return scheduleReconnect();
+    }
+    ws = sock;
+
+    sock.onopen = () => {
+      send({
+        topic: phxTopic,
+        event: "phx_join",
+        payload: {
+          config: { broadcast: { self: false, ack: false }, presence: { key: "" }, private: false },
+          access_token: chan.anonKey,
+        },
+        ref: String(++ref),
+      });
+      joinTimer = setTimeout(() => recycle("join timed out"), JOIN_TIMEOUT_MS);
+      heartbeat = setInterval(() => {
+        send({ topic: "phoenix", event: "heartbeat", payload: {}, ref: String(++ref) });
+      }, HEARTBEAT_MS);
+    };
+
+    sock.onmessage = (evt) => {
+      let msg;
+      try {
+        msg = JSON.parse(String(evt.data));
+      } catch {
+        return;
+      }
+      if (msg.topic !== phxTopic) return;
+      if (msg.event === "phx_reply") {
+        if (joinTimer) clearTimeout(joinTimer);
+        joinTimer = null;
+        if (msg.payload?.status === "ok") {
+          // Joined: the doorbell is live. Reset the backoff so a later drop
+          // recovers quickly.
+          backoff = RECONNECT_MIN_MS;
+          return;
+        }
+        // A rejected join used to leave the socket open and silent forever.
+        return recycle(`join refused (${msg.payload?.response?.reason || msg.payload?.status || "error"})`);
+      }
+      // The channel died server-side (or was closed under us): same treatment.
+      if (msg.event === "phx_error" || msg.event === "phx_close") return recycle("channel closed");
+      if (msg.event === "broadcast" && msg.payload?.event === "wake") onWake();
+    };
+
+    sock.onclose = () => {
+      teardown();
+      scheduleReconnect();
+    };
+    sock.onerror = () => {
+      // onclose follows and owns the reconnect; nothing to do here.
+    };
+  }
+
+  // Slow re-check: if the workspace rotated its topic while we were happily
+  // joined to the old one, nothing drops the socket — we would just stop
+  // hearing pings. Re-resolve on a timer and reconnect only when it changed.
+  const scheduleRefresh = () => {
+    if (stopped) return;
+    refreshTimer = setTimeout(async () => {
+      refreshTimer = null;
+      if (stopped) return;
+      try {
+        const next = await resolve();
+        if (!stopped && next?.topic && next.topic !== currentTopic) {
+          log.log("wake: doorbell topic rotated — resubscribing");
+          teardown();
+          if (reconnectTimer) clearTimeout(reconnectTimer);
+          reconnectTimer = null;
+          backoff = RECONNECT_MIN_MS;
+          void connect();
+        }
+      } catch {
+        /* the doorbell is an accelerator; a failed re-check changes nothing */
+      }
+      scheduleRefresh();
+    }, refreshMs);
+    // Never hold the process open for a doorbell re-check.
+    refreshTimer?.unref?.();
+  };
+
+  void connect();
+
+  return {
+    stop() {
+      stopped = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+      if (refreshTimer) clearTimeout(refreshTimer);
+      refreshTimer = null;
+      teardown();
+    },
+  };
+}
+
+/**
+ * The wake gate: the tiny bit of state that connects a doorbell ping to the
+ * poll loop's inter-poll sleep. Extracted from run.mjs so the race it exists to
+ * close is unit-testable — a ping that lands mid-poll (no sleeper armed) must
+ * be REMEMBERED, so the next sleep returns immediately instead of the ping
+ * being lost and the daemon waiting out a full pollMs anyway.
+ *
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {{ ping: () => void, sleep: (ms: number) => Promise<void> }}
+ */
+export function createWakeGate({ signal } = {}) {
+  let pending = false;
+  let sleeper = null;
+
+  const ping = () => {
+    pending = true;
+    if (sleeper) sleeper();
+  };
+
+  // A sleep that resolves immediately when the signal aborts (so "stop" doesn't
+  // wait out the whole poll interval) or when the wake doorbell rings.
+  const sleep = (ms) =>
+    new Promise((resolve) => {
+      if (signal?.aborted) return resolve();
+      if (pending) {
+        pending = false;
+        return resolve();
+      }
+      const done = () => {
+        signal?.removeEventListener?.("abort", onAbort);
+        sleeper = null;
+        resolve();
+      };
+      const timer = setTimeout(done, ms);
+      sleeper = () => {
+        pending = false;
+        clearTimeout(timer);
+        done();
+      };
+      function onAbort() {
+        clearTimeout(timer);
+        done();
+      }
+      signal?.addEventListener?.("abort", onAbort, { once: true });
+    });
+
+  return { ping, sleep };
+}