hilos-agent 0.1.16 → 0.4.0

package/src/hook.mjs

@@ -0,0 +1,427 @@
+// Claude Code hook → hilos live progress (0448). This is the "watch your
+// agent's hands move" path for a RAW CLI session (no daemon): install the
+// hilos hooks in a repo (`hilos-agent hooks install`) and every tool call your
+// Claude Code session makes streams a step into the agent's live status card
+// in its hilos channel, via the `post_progress` MCP tool's channelId mode.
+//
+// Design rules:
+//   - NEVER block or break the user's CLI. Every entry point swallows every
+//     error and exits 0; the network send is capped by a hard timeout.
+//   - Cheap by default: a state file per Claude session carries the message id,
+//     step ring and last-send time, so most invocations are one small read +
+//     at most one bounded fetch. Sends are throttled (default 2s) with pending
+//     steps carried over — a burst of tool calls becomes one coalesced update.
+//   - Privacy is the install default: `hooks install` writes to the PROJECT's
+//     .claude/settings.json, so only repos you opt in ever stream. HILOS_HOOKS=off
+//     is the global kill switch.
+//   - Pure helpers (event parsing, step labels, throttling decisions) are
+//     exported for offline unit tests; I/O lives only in runHook/main.
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, delimiter } from "node:path";
+import { sanitizeText } from "./agent-events.mjs";
+import { resolveConfig } from "./config.mjs";
+
+export const HOOK_STATE_DIR = join(homedir(), ".hilos", "hook-state");
+/** Coalesce window between sends; Stop/SessionEnd always flush. */
+const MIN_SEND_MS = 2000;
+/** A hook must never hang the CLI on a slow network. */
+const FETCH_TIMEOUT_MS = 3000;
+/** Step/file bounds — mirror the server's caps (lib/agent-progress.ts). */
+const MAX_STEPS = 8;
+const MAX_FILES = 20;
+/** Session state older than this is dead — GC'd opportunistically. */
+const STATE_TTL_MS = 48 * 60 * 60 * 1000;
+
+/**
+ * Parse a Claude Code hook event from stdin text. Returns a normalized
+ * { event, sessionId, toolName, toolInput, cwd } or null when unusable.
+ * PURE — never throws.
+ */
+export function parseHookEvent(raw) {
+  try {
+    const o = JSON.parse(String(raw));
+    if (!o || typeof o !== "object") return null;
+    const event = typeof o.hook_event_name === "string" ? o.hook_event_name : "";
+    const sessionId = typeof o.session_id === "string" ? o.session_id : "";
+    if (!event || !sessionId) return null;
+    return {
+      event,
+      sessionId,
+      toolName: typeof o.tool_name === "string" ? o.tool_name : "",
+      toolInput: o.tool_input && typeof o.tool_input === "object" ? o.tool_input : {},
+      cwd: typeof o.cwd === "string" ? o.cwd : "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Strip the session cwd prefix so step labels read as repo-relative paths. */
+function relPath(p, cwd) {
+  const s = String(p || "");
+  if (cwd && s.startsWith(cwd + "/")) return s.slice(cwd.length + 1);
+  return s;
+}
+
+/** First line of a shell command, trimmed to a readable label. */
+function cmdLabel(cmd) {
+  const first = String(cmd || "").split("\n")[0].trim();
+  return first.length > 60 ? first.slice(0, 59) + "…" : first;
+}
+
+/**
+ * Map a PostToolUse event to a human step label (and the file it touched, if
+ * any), or null for tools too noisy to narrate (TodoWrite etc). PURE.
+ * Mirrors the daemon's vocabulary (agent-events stepLabel) so a hook-streamed
+ * card and a daemon-streamed card read the same.
+ */
+export function hookStep(toolName, toolInput, cwd = "") {
+  const name = String(toolName || "");
+  const input = toolInput && typeof toolInput === "object" ? toolInput : {};
+  const file = typeof input.file_path === "string" ? relPath(input.file_path, cwd) : "";
+  // MCP tools arrive as `mcp__<server>__<tool>`. Skip hilos's own tools — a
+  // session posting to hilos narrating "posting to hilos" is self-referential
+  // noise — and label other servers by their short tool name.
+  const mcp = name.match(/^mcp__([^_]+(?:_[^_]+)*)__(.+)$/);
+  if (mcp) {
+    if (/hilos/i.test(mcp[1])) return null;
+    return { label: `Using ${mcp[2].replace(/_/g, " ")} (${mcp[1]})` };
+  }
+  switch (name) {
+    case "Edit":
+    case "Write":
+    case "MultiEdit":
+    case "NotebookEdit":
+      return file ? { label: `Editing ${file}`, file } : { label: "Editing files" };
+    case "Read":
+      return file ? { label: `Reading ${file}`, file } : { label: "Reading files" };
+    case "Bash": {
+      const c = cmdLabel(input.command);
+      return { label: c ? `Running ${c}` : "Running a command" };
+    }
+    case "Grep":
+    case "Glob": {
+      const q = typeof input.pattern === "string" ? input.pattern : "";
+      return { label: q ? `Searching for ${q.slice(0, 60)}` : "Searching the repo" };
+    }
+    case "Task": {
+      const d = typeof input.description === "string" ? input.description : "";
+      return { label: d ? `Delegating: ${d.slice(0, 60)}` : "Delegating a task" };
+    }
+    case "WebFetch": {
+      let host = "";
+      try {
+        host = new URL(String(input.url || "")).host;
+      } catch {
+        /* not a url */
+      }
+      return { label: host ? `Fetching ${host}` : "Fetching a page" };
+    }
+    case "WebSearch": {
+      const q = typeof input.query === "string" ? input.query : "";
+      return { label: q ? `Searching the web: ${q.slice(0, 60)}` : "Searching the web" };
+    }
+    case "TodoWrite":
+      return null; // planning chatter — too noisy to narrate
+    default:
+      return { label: `Using ${name || "a tool"}` };
+  }
+}
+
+/**
+ * Fold a step into the session state: dedupe an immediate repeat (a run of
+ * edits to one file stays one step), ring-bound steps, set-bound files. PURE —
+ * mutates and returns `state`.
+ */
+export function foldStep(state, step) {
+  if (!step) return state;
+  const label = sanitizeText(step.label);
+  if (!label) return state;
+  const steps = Array.isArray(state.steps) ? state.steps : [];
+  if (steps[steps.length - 1] !== label) steps.push(label);
+  while (steps.length > MAX_STEPS) steps.shift();
+  state.steps = steps;
+  if (step.file) {
+    const file = sanitizeText(step.file);
+    const files = Array.isArray(state.files) ? state.files : [];
+    if (file && !files.includes(file)) {
+      files.push(file);
+      while (files.length > MAX_FILES) files.shift();
+    }
+    state.files = files;
+  }
+  return state;
+}
+
+/** Throttle decision: send now, or fold and wait for a later event? PURE. */
+export function shouldSendNow(state, now, minSendMs = MIN_SEND_MS) {
+  const last = typeof state.lastSentAt === "number" ? state.lastSentAt : 0;
+  return now - last >= minSendMs;
+}
+
+/** Filename-safe session key (a session_id is a uuid, but never trust input). */
+function sessionKey(sessionId) {
+  return String(sessionId).replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+}
+
+export function statePath(sessionId, dir = HOOK_STATE_DIR) {
+  return join(dir, sessionKey(sessionId) + ".json");
+}
+
+export function readState(sessionId, dir = HOOK_STATE_DIR) {
+  try {
+    return JSON.parse(readFileSync(statePath(sessionId, dir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeState(sessionId, state, dir = HOOK_STATE_DIR) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(statePath(sessionId, dir), JSON.stringify(state));
+  } catch {
+    /* best-effort */
+  }
+}
+
+export function deleteState(sessionId, dir = HOOK_STATE_DIR) {
+  try {
+    unlinkSync(statePath(sessionId, dir));
+  } catch {
+    /* already gone */
+  }
+}
+
+/** Drop state files from long-dead sessions. Best-effort, bounded, silent. */
+export function gcStateDir(dir = HOOK_STATE_DIR, now = Date.now()) {
+  try {
+    for (const f of readdirSync(dir).slice(0, 200)) {
+      const p = join(dir, f);
+      try {
+        if (now - statSync(p).mtimeMs > STATE_TTL_MS) unlinkSync(p);
+      } catch {
+        /* skip */
+      }
+    }
+  } catch {
+    /* no dir yet */
+  }
+}
+
+/** One bounded post_progress call. Returns the server's messageId, or null. */
+async function sendProgress({ url, token, messageId, channelId, progress }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const args = messageId ? { messageId, progress } : { channelId, progress };
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "post_progress", arguments: args },
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    const text = json?.result?.content?.[0]?.text;
+    const parsed = typeof text === "string" ? JSON.parse(text) : null;
+    return parsed && typeof parsed.messageId === "string" ? parsed.messageId : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Handle one hook invocation end to end. Reads nothing from process.* so the
+ * caller (bin) owns stdin/env; returns quietly on every failure path.
+ */
+export async function runHook({ raw, cfg, now = Date.now, stateDir = HOOK_STATE_DIR }) {
+  const ev = parseHookEvent(raw);
+  if (!ev) return;
+  const { url, token, channelId } = cfg;
+  if (!url || !token || !channelId) return; // not connected to hilos — no-op
+
+  if (ev.event === "Stop" || ev.event === "SessionEnd") {
+    // End of a turn (or the session): settle the card honestly — "not doing
+    // anything right now". The next tool call revives the SAME card to working
+    // via its stored messageId, so a session stays one card, not one per turn.
+    const state = readState(ev.sessionId, stateDir);
+    if (!state || !state.messageId) return;
+    await sendProgress({
+      url,
+      token,
+      messageId: state.messageId,
+      progress: {
+        state: "done",
+        elapsedMs: Math.max(0, now() - (state.startedAt || now())),
+      },
+    });
+    if (ev.event === "SessionEnd") deleteState(ev.sessionId, stateDir);
+    else {
+      state.lastSentAt = now();
+      writeState(ev.sessionId, state, stateDir);
+    }
+    return;
+  }
+
+  if (ev.event !== "PostToolUse") return;
+
+  const step = hookStep(ev.toolName, ev.toolInput, ev.cwd);
+  if (!step) return;
+
+  let state = readState(ev.sessionId, stateDir);
+  if (!state) {
+    gcStateDir(stateDir, now()); // new session — a cheap moment to sweep old ones
+    state = { startedAt: now(), lastSentAt: 0, steps: [], files: [], messageId: null };
+  }
+  foldStep(state, step);
+
+  if (!shouldSendNow(state, now())) {
+    // Inside the coalesce window: fold only. The next event (or Stop) flushes.
+    writeState(ev.sessionId, state, stateDir);
+    return;
+  }
+
+  const progress = {
+    state: "working",
+    step: state.steps[state.steps.length - 1],
+    steps: state.steps,
+    filesTouched: state.files,
+    elapsedMs: Math.max(0, now() - (state.startedAt || now())),
+  };
+  const messageId = await sendProgress({
+    url,
+    token,
+    messageId: state.messageId || undefined,
+    channelId,
+    progress,
+  });
+  if (messageId) state.messageId = messageId;
+  state.lastSentAt = now();
+  writeState(ev.sessionId, state, stateDir);
+}
+
+/** Read all of stdin (the hook event JSON Claude Code pipes in). */
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    const timer = setTimeout(() => resolve(data), 2000); // stdin must never hang the hook
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+  });
+}
+
+/** `hilos-agent hook` — the command Claude Code invokes. Always exits 0. */
+export async function hookMain() {
+  try {
+    if (/^(off|0|false)$/i.test(process.env.HILOS_HOOKS || "")) return;
+    const raw = await readStdin();
+    const cfg = resolveConfig({});
+    await runHook({ raw, cfg });
+  } catch {
+    /* a hook must never fail the user's CLI */
+  }
+}
+
+// --- `hilos-agent hooks print|install [--global]` ---------------------------
+
+const HOOK_COMMAND = "hilos-agent hook";
+
+/** The hooks block hilos needs inside a Claude Code settings.json. */
+export function hilosHooksBlock() {
+  const entry = { hooks: [{ type: "command", command: HOOK_COMMAND }] };
+  return {
+    PostToolUse: [{ matcher: "*", ...entry }],
+    Stop: [entry],
+    SessionEnd: [entry],
+  };
+}
+
+/**
+ * Idempotently merge the hilos hooks into a settings object (parsed
+ * settings.json). Existing user hooks are preserved; a second install is a
+ * no-op. PURE — returns { settings, changed }.
+ */
+export function mergeHooksIntoSettings(settings) {
+  const out = settings && typeof settings === "object" ? settings : {};
+  const hooks = (out.hooks = out.hooks && typeof out.hooks === "object" ? out.hooks : {});
+  let changed = false;
+  for (const [event, entries] of Object.entries(hilosHooksBlock())) {
+    const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const already = existing.some((e) =>
+      (e?.hooks || []).some((h) => h?.command === HOOK_COMMAND),
+    );
+    if (!already) {
+      hooks[event] = [...existing, ...entries];
+      changed = true;
+    }
+  }
+  return { settings: out, changed };
+}
+
+/** `hilos-agent hooks install [--global]` / `hilos-agent hooks print`. */
+export function hooksMain(sub, { global: isGlobal = false } = {}) {
+  if (sub === "print") {
+    console.log(JSON.stringify({ hooks: hilosHooksBlock() }, null, 2));
+    console.log("\nMerge this into .claude/settings.json in the repo you want to stream.");
+    return;
+  }
+  if (sub !== "install") {
+    console.log("Usage: hilos-agent hooks <install|print> [--global]");
+    return;
+  }
+  const target = isGlobal
+    ? join(homedir(), ".claude", "settings.json")
+    : join(process.cwd(), ".claude", "settings.json");
+  let current = {};
+  if (existsSync(target)) {
+    try {
+      current = JSON.parse(readFileSync(target, "utf8"));
+    } catch {
+      console.error(`${target} exists but isn't valid JSON — fix it first (nothing written).`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const { settings, changed } = mergeHooksIntoSettings(current);
+  if (!changed) {
+    console.log(`hilos hooks already installed in ${target}.`);
+    return;
+  }
+  if (existsSync(target)) writeFileSync(target + ".bak", readFileSync(target));
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, JSON.stringify(settings, null, 2) + "\n");
+  console.log(`Installed hilos hooks into ${target}${existsSync(target + ".bak") ? ` (backup: ${target}.bak)` : ""}.`);
+  console.log(
+    isGlobal
+      ? "Every Claude Code session on this machine will now stream its steps to your hilos channel."
+      : "Claude Code sessions in THIS repo will now stream their steps to your hilos channel.",
+  );
+  console.log("Kill switch: HILOS_HOOKS=off.");
+  // The installed entry runs `hilos-agent hook` directly (npx per tool call
+  // would add cold-start latency) — warn now if that won't resolve.
+  const onPath = (process.env.PATH || "")
+    .split(delimiter)
+    .some((dir) => dir && existsSync(join(dir, "hilos-agent")));
+  if (!onPath) {
+    console.log(
+      "NOTE: hilos-agent isn't on your PATH — the hooks won't fire until you run: npm i -g hilos-agent",
+    );
+  }
+}

package/src/memory.mjs

@@ -8,9 +8,17 @@ const REMEMBER_NOTE =
   "To record durable new learnings from this task, use the `remember` MCP tool " +
   "(call it if your MCP config includes the hilos server).";
 
+// Budgets are deliberately TIGHTER than lib/memory.ts formatMemoryBlock
+// (25/6000/400): the daemon injects this into a coding-agent prompt that already
+// carries the repo + task context, so it keeps a smaller footprint (25/4000/300)
+// to leave headroom for the code.
 const DEFAULT_MAX_ENTRIES = 25;
 const DEFAULT_MAX_CHARS = 4000;
 const DEFAULT_BODY_CHARS = 300;
+// Reserve up to this many entry slots for workspace-wide learnings when both
+// scopes have entries, so channel-first ordering can't starve team-wide
+// conventions out of the cap. Mirrors lib/memory.ts. Channel entries still lead.
+const RESERVED_WS_SLOTS = 5;
 
 /** Truncate `text` to `max` chars, appending "…" when clipped. */
 function clip(text, max) {
@@ -27,7 +35,8 @@ function clip(text, max) {
  * line: `- [kind] title: body`. Bodies are truncated to ~300 chars. The whole
  * block is capped at ~4000 chars (entries that would overflow are dropped, but
  * at least one entry is always kept). Ends with a note reminding the agent to
- * record new learnings via the `remember` MCP tool.
+ * record new learnings via the `remember` MCP tool. Saved memory is active
+ * immediately; people can correct or hide it later in hilos.
  *
  * Returns "" when entries is empty or null so callers can concatenate
  * unconditionally (`block ? block + "\n\n" : ""`).
@@ -51,10 +60,25 @@ export function buildMemoryBlock(entries, opts = {}) {
     return (b.updated_at || "").localeCompare(a.updated_at || "");
   });
 
+  // Entry-count selection with a reserved workspace quota (see RESERVED_WS_SLOTS):
+  // hold back a few slots for workspace-wide entries when both scopes are present
+  // so channel entries can't claim every slot. Channel entries still lead.
+  const channelEntries = ordered.filter((e) => e.scope === "channel");
+  const workspaceEntries = ordered.filter((e) => e.scope !== "channel");
+  let picked;
+  if (channelEntries.length > 0 && workspaceEntries.length > 0) {
+    const wsReserve = Math.min(RESERVED_WS_SLOTS, workspaceEntries.length);
+    const chosenChannel = channelEntries.slice(0, Math.max(0, maxEntries - wsReserve));
+    const chosenWs = workspaceEntries.slice(0, maxEntries - chosenChannel.length);
+    picked = [...chosenChannel, ...chosenWs];
+  } else {
+    picked = ordered.slice(0, maxEntries);
+  }
+
   const lines = [];
   // Reserve chars for: header line + newline + 2 newlines before footer + footer.
   let total = HEADER.length + 1 + 2 + REMEMBER_NOTE.length;
-  for (const e of ordered.slice(0, maxEntries)) {
+  for (const e of picked) {
     const kind = (e.kind || "note").trim();
     const title = (e.title || "").replace(/\s+/g, " ").trim();
     const body = clip(e.body || "", bodyChars);

package/src/run.mjs

@@ -2,16 +2,66 @@
 // each one to the task handler. Prefers the workspace-wide list_mentions tool
 // (one poll, cursor-based); falls back to per-channel scanning on older servers.
 
+import { hostname } from "node:os";
+import { basename } from "node:path";
 import { makeClient } from "./mcp.mjs";
 import { mentionHandle } from "./daemon.mjs";
 import { handleTask } from "./handler.mjs";
 import { createQueue, looksLikeCancel, dedupeKey } from "./queue.mjs";
 import { reloadConfig } from "./config.mjs";
 
-export async function run(cfg, { handler = handleTask, log = console } = {}) {
+/**
+ * The poll loop. Embeddable: pass a `signal` to stop it cleanly (interrupts the
+ * inter-poll sleep, cancels the active job, then resolves) and an `onEvent`
+ * listener to observe lifecycle events (status / task-start / task-done /
+ * task-error). Both are optional and backward compatible.
+ *
+ * @param {any} cfg
+ * @param {{
+ *   handler?: (ctx: any, cfg: any, deps?: any, opts?: any) => Promise<any>,
+ *   log?: any,
+ *   signal?: AbortSignal,
+ *   onEvent?: (event: { type: string, [k: string]: any }) => void,
+ * }} [opts]
+ */
+export async function run(cfg, { handler = handleTask, log = console, signal, onEvent } = {}) {
   if (!cfg.token) {
-    log.error("No token. Run `hilos-agent init`, set HILOS_TOKEN, or use --join <blob>.");
-    process.exit(1);
+    // Throw, don't process.exit — the CLI's main().catch prints + exits 1 exactly
+    // as before, and an embedding host (the desktop Local Agents runner) must
+    // never be killed by the daemon.
+    throw new Error("No token. Run `hilos-agent init`, set HILOS_TOKEN, or use --join <blob>.");
+  }
+
+  // Lifecycle events for an embedding host (e.g. the desktop Local Agents window).
+  // EVERY listener call is wrapped so a bad listener can never crash the loop.
+  const emit = (event) => {
+    if (!onEvent) return;
+    try {
+      onEvent(event);
+    } catch {
+      /* 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 });
+    });
+
+  // Already asked to stop before we even connect → return cleanly, do nothing.
+  if (signal?.aborted) {
+    emit({ type: "status", text: "stopping" });
+    return;
   }
 
   const { tool, listToolNames } = makeClient({ url: cfg.url, token: cfg.token });
@@ -19,8 +69,8 @@ export async function run(cfg, { handler = handleTask, log = console } = {}) {
   const who = await tool("whoami");
   const me = { ...who, handle: mentionHandle(who.agentName) };
   if (!me.handle) {
-    log.error("This agent has no display name / handle — set one in hilos, then reconnect.");
-    process.exit(1);
+    // Throw for the same reason as the token guard above — embed-safe, CLI-equal.
+    throw new Error("This agent has no display name / handle — set one in hilos, then reconnect.");
   }
   log.log(`hilos-agent: ${me.agentName} (@${me.handle}) — ${cfg.url}`);
   if (cfg.channelId) log.log(`scope: channel ${cfg.channelId}`);
@@ -48,12 +98,33 @@ export async function run(cfg, { handler = handleTask, log = console } = {}) {
     recall: toolNames.includes("recall"),
   };
 
+  // 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
+  // link_folder (older deploys skip silently, exactly like recall). Best-effort:
+  // each call is wrapped so a failure logs one line and NEVER blocks startup.
+  // Done ONCE here at startup — config live-reload (reloadConfig, below) does NOT
+  // re-register, so a folders entry added while running needs a restart to link.
+  if (toolNames.includes("link_folder") && cfg.folders && Object.keys(cfg.folders).length) {
+    for (const [channelId, path] of Object.entries(cfg.folders)) {
+      if (!channelId || !path) continue;
+      const title = basename(path);
+      try {
+        await tool("link_folder", { channelId, path, title, hostname: hostname() });
+        emit({ type: "status", text: `linked folder ${title} to its channel` });
+      } catch (e) {
+        log.error(`link_folder failed for ${path}: ${e?.message || e}`);
+      }
+    }
+  }
+
   let channelIds = [];
   if (!useMentions) {
     if (cfg.channelId) channelIds = [cfg.channelId];
     else channelIds = ((await tool("list_channels"))?.channels ?? []).map((c) => c.id);
   }
   log.log(useMentions ? "watching: @-mentions" : `watching: ${channelIds.length} channel(s)`);
+  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 };
@@ -67,15 +138,34 @@ export async function run(cfg, { handler = handleTask, log = console } = {}) {
   // lets a "stop" (and new mentions) be picked up while a task is still running.
   const queue = createQueue({
     concurrency: cfg.queueConcurrency || 1,
-    runJob: (job, { signal }) => safeHandle(job.message, job.channelId, signal),
+    runJob: (job, { signal: jobSignal }) => safeHandle(job.message, job.channelId, jobSignal),
   });
 
-  async function safeHandle(message, channelId, signal) {
+  // Stopping the embedded daemon: the moment the caller aborts, cancel the active
+  // job (via the queue's existing cancel path — it aborts the in-flight job's
+  // signal) so a multi-minute run is torn down promptly, and emit a stopping
+  // event. New tasks are refused in intake(); the loop below exits on the same
+  // signal and run() resolves cleanly.
+  if (signal) {
+    signal.addEventListener(
+      "abort",
+      () => {
+        emit({ type: "status", text: "stopping" });
+        queue.cancelActive("run() aborted");
+      },
+      { once: true },
+    );
+  }
+
+  async function safeHandle(message, channelId, jobSignal) {
+    emit({ type: "task-start", channelId, messageId: message.id, text: (message.body || "").slice(0, 200) });
     try {
       log.log(`→ task in ${channelId}: "${(message.body || "").slice(0, 80)}"`);
       // liveCfg so a job uses the latest model/permission/codingCmd at run time.
-      await handler({ message, channelId, tool, me, caps }, liveCfg, undefined, { signal });
+      const result = await handler({ message, channelId, tool, me, caps }, liveCfg, undefined, { signal: jobSignal });
+      emit({ type: "task-done", channelId, status: result && result.status });
     } catch (e) {
+      emit({ type: "task-error", channelId, error: e?.message || String(e) });
       log.error(`handler error: ${e.message}`);
       await tool("post_message", {
         channelId,
@@ -88,6 +178,8 @@ export async function run(cfg, { handler = handleTask, log = console } = {}) {
   // enqueued (deduped against an identical in-flight/queued ask), with an ack
   // when it lands behind work already in progress.
   async function intake(m, channelId) {
+    // Once we're stopping, don't start anything new.
+    if (signal?.aborted) return;
     if (looksLikeCancel(m.body) && (queue.active() || queue.size())) {
       queue.cancelActive("user asked to stop");
       await tool("post_message", {
@@ -140,11 +232,15 @@ export async function run(cfg, { handler = handleTask, log = console } = {}) {
   }
 
   do {
+    if (signal?.aborted) break;
     // Pick up live edits to hilos-agent.json (model/permission/codingCmd/etc.)
     // before each pass. Guarded: a bad file leaves liveCfg untouched.
     try {
       const next = reloadConfig(liveCfg);
-      if (next.codingCmd !== liveCfg.codingCmd) log.log(`daemon: coding command → ${next.codingCmd}`);
+      if (next.codingCmd !== liveCfg.codingCmd) {
+        log.log(`daemon: coding command → ${next.codingCmd}`);
+        emit({ type: "status", text: "config reloaded" });
+      }
       liveCfg = next;
     } catch (e) {
       log.error(`config reload error (keeping previous): ${e.message}`);
@@ -160,6 +256,16 @@ export async function run(cfg, { handler = handleTask, log = console } = {}) {
       await queue.idle();
       break;
     }
-    await new Promise((r) => setTimeout(r, liveCfg.pollMs));
-  } while (true);
+    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);
+  } 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.
+  if (signal?.aborted) {
+    queue.cancelActive("run() aborted");
+  }
 }