hilos-agent 0.1.5 → 0.1.7

package/README.md

@@ -4,21 +4,24 @@ Run **your own** coding agent — Claude Code, Codex, Cursor, or any command —
 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, runs your coding agent in a **local** checkout, and posts the
-proposed diff as a report card. **Nothing is pushed until a human approves in
-hilos.** Your code and your git/`gh` credentials never leave your machine — hilos
-only relays messages.
+git-linked channel (including thread replies), 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.
 
 ```
 hilos channel  ──MCP/HTTPS──▶  hilos-agent (your laptop)
   human: "@scout fix the navbar overflow"
-  agent: branches, runs your coding CLI, captures the diff
-  agent: posts a proposal card (NOT pushed)
-  human: Approve  ▶  agent: git push + gh pr create  ▶  posts the PR link
-         Reject   ▶  agent: discards the branch
-         Changes  ▶  agent: re-runs with your note, proposes again
+  agent: branches, runs your coding CLI, commits + pushes, opens a PR
+  agent: posts a report card with the PR link
+  human: Approve  ▶  hilos merges the PR
+         Reject   ▶  hilos closes the PR
+         Changes  ▶  agent re-works with your note
 ```
 
+Prefer **approve-before-push**? Set `"gate": true` — the agent then posts the
+proposed diff as a card and pushes only after you Approve (nothing leaves your
+machine until then).
+
 ## Quick start
 
 In hilos: open your agent's profile → **Connect** → copy the
@@ -39,9 +42,9 @@ Running from elsewhere, or want to map several repos explicitly? Use a config:
   "url": "https://hilos.sh/api/mcp",
   "token": "mgo_…",
   "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
-  "codingCmd": "claude -p",   // or "codex exec", "cursor-agent", any shell command
+  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent", any command
   "defaultBranch": "main",
-  "gate": true                 // false = propose only, never push
+  "gate": false                // default: open a PR directly. true = approve-before-push
 }
 ```
 
@@ -57,18 +60,49 @@ hilos-agent --channel <id>   # scope to one channel
   `repos`. No mapping → the agent says so and stops.
 - **Run** — it branches off `defaultBranch` (refuses a dirty tree), runs
   `codingCmd` with the task, and stages the result.
-- **Propose** — the staged diff is posted as a report card. The agent then polls
-  for your decision.
-- **Approve / Reject / Request changes** — approve pushes with *your* `git`/`gh`
-  and opens a PR; reject discards the branch; request-changes re-runs with your
-  note (bounded rounds).
+- **Open a PR** (default) — it commits, pushes with *your* `git`/`gh`, opens a PR,
+  and posts a report card with the link. Review on the card: **Approve** merges,
+  **Reject** closes, **Request changes** re-works.
+- **Approve-before-push** (`gate:true`) — instead, it posts the staged diff as a
+  card and polls for your decision; **Approve** pushes + opens the PR, **Reject**
+  discards the branch, **Request changes** re-runs with your note (bounded rounds).
+
+## Permissions / autonomy
+
+`codingCmd` decides how much the coding agent can do on its own. Three levels,
+safest first:
+
+- **`--permission-mode acceptEdits` (default).** The agent edits files without
+  prompting, but in headless `claude -p` a step that needs bash — run the tests,
+  install a dep — has no interactive prompt to grant, so the task can **stall**.
+  Good when the work is edit-only; frustrating for anything that needs to run
+  commands.
+- **`--dangerously-skip-permissions` (recommended for independent agents).** Full
+  autonomy: the agent can run the tests, install deps, and finish hands-off.
+  Caution: it can run **any** command in the repo you point it at — only use it
+  on a repo and machine where that's acceptable. This is the option to pick if
+  you want the agent to actually work on its own.
+
+  ```jsonc
+  "codingCmd": "claude -p --dangerously-skip-permissions"
+  ```
+
+- **Approve-before-push (`gate:true`), most cautious.** Independent of the two
+  above — the agent still runs locally, but posts the proposed diff as a card and
+  pushes only after you Approve. Pair it with either permission mode.
+
+The default stays `acceptEdits`. Reach for `--dangerously-skip-permissions` when
+you want a truly hands-off teammate, and keep `gate:true` if you'd rather review
+before anything is pushed.
 
 ## Security
 
 The daemon runs a coding agent that can execute code in your repo — exactly as if
-you ran it in your terminal. hilos can only send text; **push is gated on a human
-approval recorded in hilos**, and uses your local credentials. Keep your token in
-the config file or `HILOS_TOKEN`, never in shared shell history.
+you ran it in your terminal — and uses *your* local `git`/`gh` to push. By default
+it opens a PR (nothing is force-merged; you review the PR, and merge/close run via
+hilos's GitHub App only for workspace owners/admins). Want a human checkpoint
+before anything is pushed? Set `"gate": true`. Keep your token in the config file
+or `HILOS_TOKEN`, never in shared shell history.
 
 ## Flags
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hilos-agent",
-  "version": "0.1.5",
-  "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions, proposes a diff, and pushes only after a human approves — your code and credentials never leave your machine.",
+  "version": "0.1.7",
+  "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": {
     "hilos-agent": "bin/hilos-agent.mjs"

package/src/cli.mjs

@@ -28,6 +28,8 @@ const MAX_CAPTURE_BYTES = 50 * 1024 * 1024;
  * @property {number} [heartbeatMs] - heartbeat interval (0 = no heartbeat)
  * @property {() => number} [now] - clock, injectable for tests
  * @property {{ log: (m: string) => void }} [log] - logger, injectable for tests
+ * @property {AbortSignal} [signal] - abort to cancel the run (kills the child's
+ *   whole process group: SIGTERM, then SIGKILL after a short grace)
  */
 
 /**
@@ -50,11 +52,20 @@ export function runCli(opts) {
     heartbeatMs = 15000,
     now = Date.now,
     log = console,
+    signal,
   } = opts || {};
   return new Promise((resolve) => {
+    // Already cancelled before we even start.
+    if (signal?.aborted) {
+      resolve({ status: null, stdout: "", stderr: "", aborted: true, error: new Error("cancelled") });
+      return;
+    }
     let child;
     try {
-      child = spawn(cmd, args, { cwd });
+      // detached:true makes the child its own process-group leader, so we can
+      // kill the WHOLE tree (claude → node → git …) with process.kill(-pid) on
+      // cancel/timeout instead of orphaning its subprocesses.
+      child = spawn(cmd, args, { cwd, detached: true });
     } catch (error) {
       resolve({ status: null, stdout: "", stderr: "", error });
       return;
@@ -80,24 +91,60 @@ export function runCli(opts) {
         : null;
     if (beat?.unref) beat.unref();
 
+    // Kill the child's whole process group; fall back to a bare kill if the
+    // group signal isn't permitted (e.g. Windows / unusual setups).
+    const killGroup = (sig) => {
+      if (child.pid == null) return; // never spawned a pid → nothing to kill
+      try {
+        process.kill(-child.pid, sig);
+      } catch {
+        try {
+          child.kill(sig);
+        } catch {
+          /* already gone */
+        }
+      }
+    };
+
     let timedOut = false;
     const timer =
       timeoutMs > 0
         ? setTimeout(() => {
             timedOut = true;
-            child.kill("SIGKILL");
+            killGroup("SIGKILL");
           }, timeoutMs)
         : null;
     if (timer?.unref) timer.unref();
 
+    // Cancel via AbortSignal: SIGTERM the group, then SIGKILL after a grace so a
+    // well-behaved CLI can clean up but a stuck one still dies.
+    let aborted = false;
+    let graceTimer = null;
+    const onAbort = () => {
+      aborted = true;
+      killGroup("SIGTERM");
+      graceTimer = setTimeout(() => killGroup("SIGKILL"), 3000);
+      if (graceTimer?.unref) graceTimer.unref();
+    };
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
+
     const finish = (status, error) => {
       if (beat) clearInterval(beat);
       if (timer) clearTimeout(timer);
+      if (graceTimer) clearTimeout(graceTimer);
+      if (signal) signal.removeEventListener("abort", onAbort);
       resolve({
         status,
         stdout,
         stderr,
-        error: error || (timedOut ? new Error(`timed out after ${fmtElapsed(timeoutMs)}`) : null),
+        aborted,
+        error:
+          error ||
+          (aborted
+            ? new Error("cancelled")
+            : timedOut
+              ? new Error(`timed out after ${fmtElapsed(timeoutMs)}`)
+              : null),
       });
     };
     child.on("error", (error) => finish(null, error));

package/src/config.mjs

@@ -43,11 +43,21 @@ const DEFAULTS = {
   token: "",
   channelId: "", // when set, watch only this channel (the per-channel override)
   repos: {},
-  codingCmd: "claude -p",
+  // acceptEdits lets the CLI make file edits without prompting (bias to action);
+  // it still won't run arbitrary commands. Override in hilos-agent.json if you
+  // want a stricter (or `--dangerously-skip-permissions`) command.
+  codingCmd: "claude -p --permission-mode acceptEdits",
   defaultBranch: "main",
-  gate: true,
+  // Bias to action: open a PR directly for review (approve = merge on the card).
+  // Set gate:true for the older approve-before-push flow (propose a diff, wait).
+  gate: false,
   maxRounds: 3,
   pollMs: 5000,
+  // Work queue: run mentions one at a time (concurrency 1 — parallel CLI runs on
+  // one checkout would collide on git state). queueAcks posts "queued behind the
+  // current task" when a mention lands during a run; set false to keep it quiet.
+  queueConcurrency: 1,
+  queueAcks: true,
   runTimeoutMs: 600000,
   decisionTimeoutMs: 1800000,
   decisionPollMs: 5000,
@@ -89,7 +99,8 @@ export function writeStarterConfig(path, partial = {}) {
     repos: partial.repos || { "owner/name": "/absolute/path/to/checkout" },
     codingCmd: partial.codingCmd || DEFAULTS.codingCmd,
     defaultBranch: DEFAULTS.defaultBranch,
-    gate: true,
+    // false = open a PR directly (bias to action); true = approve-before-push.
+    gate: false,
   };
   writeFileSync(target, JSON.stringify(starter, null, 2) + "\n");
   return target;

package/src/handler.mjs

@@ -1,9 +1,16 @@
-// The default task handler: turn an @mention in a git-linked channel into a
-// branch + a coding-agent run + a proposed diff, gated on a human approval in
-// hilos. Nothing is pushed until approved. Your code + credentials stay local.
+// CANONICAL HANDLER — this is what the published `hilos-agent` package ships and
+// runs. Bias-to-PR by default (gate:false opens a PR; gate:true falls back to
+// approve-before-push). The legacy, propose-only reference lives at
+// scripts/examples/coding-agent-handler.mjs and is NOT what users run.
+//
+// Turn an @mention in a git-linked channel into a branch + a coding-agent run.
+// By default it opens a PR for review; with gate:true it posts a proposed diff
+// and pushes only after approval. Your code + credentials stay local.
 
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
 import {
   branchSlug,
   truncateDiff,
@@ -41,18 +48,31 @@ function defaultDeps() {
   };
 }
 
-async function awaitDecision({ tool, channelId, reportMessageId, cfg, deps }) {
+async function awaitDecision({ tool, channelId, reportMessageId, cfg, deps, parentId, signal }) {
   if (!reportMessageId) return { kind: "timeout" };
   const deadline = deps.now() + cfg.decisionTimeoutMs;
   while (deps.now() < deadline) {
+    // A "stop" while we wait for review must end the wait — otherwise a later
+    // Approve would still commit/push/open a PR despite the cancel.
+    if (signal?.aborted) return { kind: "cancelled" };
     let report = null;
     const gr = await tool("get_report", { messageId: reportMessageId }).catch(() => null);
     if (gr && gr.found && gr.report) report = gr.report;
     if (!report) {
-      const { messages = [] } = await tool("read_channel", { channelId, limit: 200 }).catch(
-        () => ({ messages: [] }),
-      );
-      const m = messages.find((x) => x.id === reportMessageId);
+      // Fallback for servers without get_report. In a thread the report lives
+      // under the thread root (read_channel only returns top-level), so scan the
+      // thread there; otherwise scan the channel tail.
+      let candidates = [];
+      if (parentId) {
+        const t = await tool("get_thread", { parentId }).catch(() => null);
+        candidates = t && t.found ? [t.root, ...(t.replies ?? [])].filter(Boolean) : [];
+      } else {
+        const { messages = [] } = await tool("read_channel", { channelId, limit: 200 }).catch(
+          () => ({ messages: [] }),
+        );
+        candidates = messages;
+      }
+      const m = candidates.find((x) => x.id === reportMessageId);
       report = m && m.report ? m.report : null;
     }
     const kind = report ? decisionKind(report) : null;
@@ -62,7 +82,15 @@ async function awaitDecision({ tool, channelId, reportMessageId, cfg, deps }) {
   return { kind: "timeout" };
 }
 
-async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps }) {
+/** Attach a just-opened PR to the channel (best-effort) so its live pill shows. */
+async function linkPrFromUrl({ tool, channelId, url }) {
+  if (!url) return;
+  const m = /github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)/.exec(url);
+  if (!m) return;
+  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 }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
   if (decision.kind === "approved") {
@@ -70,6 +98,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
     if (deps.git(repoPath, ["diff", "--cached", "--quiet"]).status === 0) {
       await tool("post_message", {
         channelId,
+        parentId,
         body: `Approved, but there are no staged changes to commit on \`${branch}\`.`,
       });
       return { status: "nothing-staged", branch };
@@ -78,6 +107,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
     if (commit.status !== 0) {
       await tool("post_message", {
         channelId,
+        parentId,
         body: `Approved, but the commit failed: ${(commit.stderr || "").trim().slice(0, 300)}`,
       });
       return { status: "commit-failed", branch };
@@ -86,6 +116,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
     if (push.status !== 0) {
       await tool("post_message", {
         channelId,
+        parentId,
         body: `Approved, but the push failed: ${(push.stderr || "").trim().slice(0, 300)}`,
       });
       return { status: "push-failed", branch };
@@ -94,6 +125,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
     const pr = deps.openPR(repoPath, { title, body, branch, base: cfg.defaultBranch });
     await tool("post_report", {
       channelId,
+      parentId,
       title: `Shipped: ${title}`,
       summary:
         pr.ok && pr.url
@@ -102,6 +134,8 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       prUrl: pr.ok && pr.url ? pr.url : undefined,
       caveats: pr.ok ? [] : [`gh pr create failed: ${(pr.stderr || "").trim().slice(0, 200)}`],
     });
+    // Work produced a PR → attach it to the channel so its live pill shows up.
+    await linkPrFromUrl({ tool, channelId, url: pr.ok ? pr.url : null });
     return { status: "pushed", branch, prUrl: pr.ok ? pr.url : null };
   }
 
@@ -110,13 +144,14 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
     deps.git(repoPath, ["clean", "-fd"]);
     deps.git(repoPath, ["switch", "-"]);
     deps.git(repoPath, ["branch", "-D", branch]);
-    await tool("post_message", { channelId, body: `Rejected — discarded \`${branch}\`.` });
+    await tool("post_message", { channelId, parentId, body: `Rejected — discarded \`${branch}\`.` });
     return { status: "discarded", branch };
   }
 
   if (decision.kind === "changes") {
     await tool("post_message", {
       channelId,
+      parentId,
       body: `Got it${decision.note ? `: ${decision.note}` : ""}. Leaving \`${branch}\` for a follow-up.`,
     });
     return { status: "changes", branch, note: decision.note };
@@ -124,6 +159,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
 
   await tool("post_message", {
     channelId,
+    parentId,
     body: `Still awaiting review on \`${branch}\`. Re-mention me once you've decided.`,
   });
   return { status: "timeout", branch };
@@ -162,21 +198,39 @@ export function normalizeRemote(url) {
   return m ? m[1] : null;
 }
 
+/** A short workspace-memory preamble for a CLI prompt, or "" when there is none. */
+function memoryPreamble(workspaceMemory) {
+  const m = (workspaceMemory || "").trim();
+  return m ? `Workspace context (the project's soul):\n${m}\n\n` : "";
+}
+
 /** Run the configured CLI to produce a chat reply, using recent channel context. */
-async function respondConversationally({ message, channelId, tool, me, cfg }) {
+async function respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal }) {
   void message;
-  const { messages = [] } = await tool("read_channel", { channelId, limit: 20 }).catch(() => ({
-    messages: [],
-  }));
-  const transcript = messages
-    .map((m) => `${m.author}: ${m.body}`)
-    .join("\n")
-    .slice(-6000);
+  // In a thread, use the thread's own messages as context (and reply there);
+  // otherwise the recent channel tail. Threads are where conversations live, so
+  // the agent must follow the thread it was pinged in, not the whole channel.
+  let transcript;
+  if (parentId) {
+    const t = await tool("get_thread", { parentId }).catch(() => null);
+    const rows = t && t.found ? [t.root, ...(t.replies ?? [])].filter(Boolean) : [];
+    transcript = rows.map((m) => `${m.author}: ${m.body}`).join("\n").slice(-6000);
+  } else {
+    const { messages = [] } = await tool("read_channel", { channelId, limit: 20 }).catch(() => ({
+      messages: [],
+    }));
+    transcript = messages.map((m) => `${m.author}: ${m.body}`).join("\n").slice(-6000);
+  }
   const name = me?.agentName || "an assistant";
+  // Tell the agent what the room is connected to so it doesn't ask "which repo?".
+  const repoLine = repoLink
+    ? `This channel is connected to the repository ${repoLink.repo_full_name}; assume that repo for any code work — don't ask which one.`
+    : `If asked to change code, note that a repo isn't linked to this channel yet.`;
   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. ` +
-    `If asked to change code, note that a repo isn't linked to this channel yet.\n\n` +
+    `${repoLine}\n\n` +
+    `${memoryPreamble(workspaceMemory)}` +
     `Conversation so far:\n${transcript}`;
 
   const parts = cfg.codingCmd.split(" ").filter(Boolean);
@@ -186,27 +240,41 @@ async function respondConversationally({ message, channelId, tool, me, cfg }) {
     args: [...parts.slice(1), prompt],
     timeoutMs: cfg.runTimeoutMs,
     label: "thinking",
+    signal,
   });
+  if (run.aborted || signal?.aborted) {
+    await tool("post_message", { channelId, parentId: parentId ?? null, body: "Stopped." });
+    return;
+  }
   const reply = (run.stdout || "").trim();
   if (run.error) console.log(`  ! ${parts[0]} failed to start: ${run.error.message}`);
   console.log(`  chat → ${reply ? `replied (${reply.length} chars)` : "no output"}; posting`);
   await tool("post_message", {
     channelId,
+    parentId: parentId ?? null,
     body: reply || `(my CLI returned nothing — is \`${cfg.codingCmd}\` installed and on PATH?)`,
   });
 }
 
-/** Handle one task. cfg/deps injectable for tests. */
-export async function handleTask({ message, channelId, tool, me }, cfg, depsOverride) {
+/** Handle one task. cfg/deps injectable for tests. `opts.signal` (AbortSignal)
+ *  cancels an in-flight run — the queue fires it when a human says "stop". */
+export async function handleTask({ message, channelId, tool, me }, cfg, depsOverride, opts = {}) {
   const deps = depsOverride || defaultDeps();
   const git = deps.git;
+  const signal = opts.signal;
+  // When the mention was a thread reply, keep the whole exchange in that thread.
+  const parentId = message.parentId ?? null;
 
   const { links = [] } = await tool("get_links", { channelId }).catch(() => ({ links: [] }));
   const repoLink = links.find((l) => l.repo_full_name);
+  // Workspace memory ("soul") — shared project context the agent should know.
+  const { memory: workspaceMemory = null } = await tool("get_workspace_memory", {}).catch(() => ({
+    memory: null,
+  }));
   // Chat (no repo linked, OR a greeting/question even in a repo channel) →
   // reply via the CLI. Only an actual code request runs the branch/diff/PR flow.
   if (!repoLink || !looksLikeCodeTask(message.body)) {
-    await respondConversationally({ message, channelId, tool, me, cfg });
+    await respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal });
     return { status: "chat" };
   }
   const repoFullName = repoLink.repo_full_name;
@@ -224,6 +292,7 @@ export async function handleTask({ message, channelId, tool, me }, cfg, depsOver
   if (!repoPath) {
     await tool("post_message", {
       channelId,
+      parentId,
       body:
         `I don't have a local checkout of ${repoFullName}. Either run me from inside that ` +
         `repo, or add it to your hilos-agent.json: "repos": { "${repoFullName}": "/abs/path" }.`,
@@ -233,23 +302,33 @@ export async function handleTask({ message, channelId, tool, me }, cfg, depsOver
 
   const status = git(repoPath, ["status", "--porcelain"]);
   if (status.status !== 0) {
-    await tool("post_message", { channelId, body: `Can't read git status in ${repoPath}.` });
+    await tool("post_message", { channelId, parentId, body: `Can't read git status in ${repoPath}.` });
     return { status: "git-error" };
   }
   if (status.stdout.trim()) {
     await tool("post_message", {
       channelId,
+      parentId,
       body: `Working tree at ${repoPath} is dirty — commit or stash first.`,
     });
     return { status: "dirty" };
   }
 
+  // Remember where we started so cancel/cleanup can switch back explicitly
+  // (relying on `git switch -` breaks from a detached HEAD).
+  const symref = git(repoPath, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  const startRef =
+    symref.status === 0 && symref.stdout.trim()
+      ? { kind: "branch", ref: symref.stdout.trim() }
+      : { kind: "detached", ref: (git(repoPath, ["rev-parse", "HEAD"]).stdout || "").trim() };
+
   const branch = branchSlug(message.body, randomBytes(3).toString("hex"));
   git(repoPath, ["fetch", "origin", cfg.defaultBranch]);
   const co = git(repoPath, ["switch", "-c", branch]);
   if (co.status !== 0) {
     await tool("post_message", {
       channelId,
+      parentId,
       body: `Couldn't create branch \`${branch}\`: ${co.stderr.trim()}`,
     });
     return { status: "branch-error" };
@@ -257,21 +336,30 @@ export async function handleTask({ message, channelId, tool, me }, cfg, depsOver
 
   await tool("post_message", {
     channelId,
+    parentId,
     body: `On it — working in ${repoFullName} on \`${branch}\`.`,
   });
 
   const parts = cfg.codingCmd.split(" ").filter(Boolean);
-  const proposeRound = async (promptText) => {
+  // Run the CLI and stage everything it changed; return the diff stats (no post).
+  // Workspace memory (the project's soul) is prepended so the coding agent has
+  // the shared context before it starts.
+  const runAndStage = async (promptText) => {
     console.log(
       `  code → running \`${cfg.codingCmd}\` in ${repoPath} (this can take a few minutes; output appears when it finishes)…`,
     );
     const run = await runCli({
       cmd: parts[0],
-      args: [...parts.slice(1), promptText],
+      args: [...parts.slice(1), memoryPreamble(workspaceMemory) + promptText],
       cwd: repoPath,
       timeoutMs: cfg.runTimeoutMs,
       label: "coding",
+      signal,
     });
+    if (run.aborted || signal?.aborted) {
+      console.log("  code → cancelled");
+      return { aborted: true };
+    }
     if (run.error) console.log(`  ! ${parts[0]} failed to start: ${run.error.message}`);
     git(repoPath, ["add", "-A"]);
     const diff = git(repoPath, ["diff", "--cached"]).stdout || "";
@@ -279,28 +367,70 @@ export async function handleTask({ message, channelId, tool, me }, cfg, depsOver
       console.log("  code → no changes produced");
       return { empty: true };
     }
-    console.log("  code → diff captured; posting proposal");
+    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 };
+  };
+
+  // Post a proposal card (approve-before-push mode) from a staged change.
+  const postProposal = async (staged) => {
     const report = buildProposalReport({
       task: message.body,
       requester: message.author,
       repoFullName,
       branch,
-      diffText,
-      truncated,
-      omittedLines,
-      stat,
-      runFailed: run.status !== 0,
+      diffText: staged.diffText,
+      truncated: staged.truncated,
+      omittedLines: staged.omittedLines,
+      stat: staged.stat,
+      runFailed: staged.runFailed,
+    });
+    const res = await tool("post_report", { channelId, parentId, ...report });
+    return { reportMessageId: res?.messageId ?? null, stat: staged.stat };
+  };
+
+  // Cancelled mid-run: discard whatever the CLI wrote + the branch, so a stopped
+  // run never leaves a dirty tree that blocks the next job (handleTask refuses on
+  // a dirty tree). The CLI child is dead by the time we get here (runCli resolves
+  // on the process close), so a leftover .git/index.lock is stale — clear it so
+  // reset/clean can run. Returns whether the tree ended up clean.
+  const discardBranch = () => {
+    try {
+      rmSync(join(repoPath, ".git", "index.lock"), { force: true });
+    } catch {
+      /* nothing to clear */
+    }
+    git(repoPath, ["reset", "--hard", "HEAD"]);
+    git(repoPath, ["clean", "-fd"]);
+    if (startRef.ref) {
+      git(repoPath, startRef.kind === "branch" ? ["switch", "--force", startRef.ref] : ["switch", "--detach", startRef.ref]);
+    } else {
+      git(repoPath, ["switch", "-"]);
+    }
+    git(repoPath, ["branch", "-D", branch]);
+    return (git(repoPath, ["status", "--porcelain"]).stdout || "").trim() === "";
+  };
+
+  // Post the right cancel message: honest about whether cleanup actually worked.
+  const postStopped = async () => {
+    const clean = discardBranch();
+    await tool("post_message", {
+      channelId,
+      parentId,
+      body: clean
+        ? `Stopped — discarded \`${branch}\`.`
+        : `Stopped, but couldn't fully clean \`${branch}\` — run \`git reset --hard && git switch ${startRef.ref || cfg.defaultBranch}\` in ${repoPath}.`,
     });
-    const res = await tool("post_report", { channelId, ...report });
-    return { reportMessageId: res?.messageId ?? null, stat };
+    return { status: "cancelled", branch };
   };
 
-  let proposal = await proposeRound(message.body);
-  if (proposal.empty) {
+  const staged = await runAndStage(message.body);
+  if (staged.aborted) return await postStopped();
+  if (staged.empty) {
     await tool("post_message", {
       channelId,
+      parentId,
       body: `No changes were produced. Cleaning up \`${branch}\`.`,
     });
     git(repoPath, ["switch", "-"]);
@@ -308,33 +438,58 @@ export async function handleTask({ message, channelId, tool, me }, cfg, depsOver
     return { status: "no-changes" };
   }
 
+  // Bias to action (default): commit, push, and open a PR for review now — the
+  // report card's Approve merges it. `gate:true` keeps the older
+  // propose-a-diff-and-wait flow for users who want approve-before-push.
   if (!cfg.gate) {
-    return { status: "proposed", branch, reportMessageId: proposal.reportMessageId, stat: proposal.stat };
+    // A "stop" that lands between the run finishing and the ship must still win.
+    if (signal?.aborted) return await postStopped();
+    const result = await applyDecision({
+      decision: { kind: "approved" },
+      repoPath,
+      branch,
+      task: message.body,
+      requester: message.author,
+      cfg,
+      tool,
+      channelId,
+      deps,
+      parentId,
+    });
+    return { ...result, stat: staged.stat };
   }
 
-  let decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps });
+  let proposal = await postProposal(staged);
+  let decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps, parentId, signal });
+  if (decision.kind === "cancelled") return await postStopped();
   const maxRounds = cfg.maxRounds || 3;
   let round = 1;
   while (decision.kind === "changes" && round < maxRounds) {
     await tool("post_message", {
       channelId,
+      parentId,
       body: `Revising with your feedback${decision.note ? `: ${decision.note}` : ""} (round ${round + 1}/${maxRounds}).`,
     });
-    const refined = await proposeRound(
+    const refined = await runAndStage(
       `${message.body}\n\nReviewer feedback to address: ${decision.note || "(see the channel)"}`,
     );
+    if (refined.aborted) return await postStopped();
     if (refined.empty) {
       await tool("post_message", {
         channelId,
+        parentId,
         body: `That feedback produced no further changes — leaving \`${branch}\` as proposed.`,
       });
       break;
     }
-    proposal = refined;
-    decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps });
+    proposal = await postProposal(refined);
+    decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps, parentId, signal });
+    if (decision.kind === "cancelled") return await postStopped();
     round += 1;
   }
 
+  // A stop during the final wait, too — don't ship a cancelled run.
+  if (signal?.aborted) return await postStopped();
   const result = await applyDecision({
     decision,
     repoPath,
@@ -345,6 +500,7 @@ export async function handleTask({ message, channelId, tool, me }, cfg, depsOver
     tool,
     channelId,
     deps,
+    parentId,
   });
   return { ...result, reportMessageId: proposal.reportMessageId, stat: proposal.stat, rounds: round };
 }

package/src/mcp.mjs

@@ -1,5 +1,15 @@
 // Minimal MCP-over-HTTP client (JSON-RPC 2.0). Dependency-free: uses global
 // fetch (Node >= 18). One bearer token, one endpoint.
+import os from "node:os";
+
+// Best-effort host label so hilos can show "whose machine" this daemon runs on.
+const CLIENT = (() => {
+  try {
+    return `${os.userInfo().username}@${os.hostname()}`;
+  } catch {
+    return os.hostname?.() || "";
+  }
+})();
 
 export function makeClient({ url, token }) {
   let id = 0;
@@ -7,7 +17,11 @@ export function makeClient({ url, token }) {
   async function rpc(method, params) {
     const res = await fetch(url, {
       method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${token}`,
+        ...(CLIENT ? { "x-hilos-client": CLIENT } : {}),
+      },
       body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method, params }),
     });
     if (!res.ok) {

package/src/queue.mjs

@@ -0,0 +1,133 @@
+// Per-agent work queue + cancel/dedupe intent helpers. Pure + dependency-free
+// so it stands alone and is unit-testable. (Mirror of scripts/lib/queue.mjs —
+// keep the two equivalent.)
+//
+// Why: the poll loop used to `await` each multi-minute run inline, so the daemon
+// stopped fetching while it worked — rapid mentions from several people queued up
+// invisibly (or were dropped), and there was no way to interrupt. This queue lets
+// the loop keep polling: it enqueues work, the queue runs it one at a time, and a
+// plain-text "stop" picked up on the same poll can cancel the active run.
+
+/** Normalize task text for dedupe: lowercase, strip @mentions, collapse space. */
+export function normalizeTask(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/@[a-z0-9-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Burst-dedupe key: same requester + same thread (or channel) + same normalized
+ *  ask. A burst of identical pings from ONE person collapses to one job (one ask
+ *  never spawns N branches), but two different people asking the same thing stay
+ *  distinct. `author` is a display name (not a stable id), so same-named users can
+ *  still collide — acceptable until the mention payload carries a user id. */
+export function dedupeKey(message, channelId) {
+  const scope = (message && message.parentId) || channelId || "";
+  const who = (message && message.author) || "";
+  return `${scope}::${who}::${normalizeTask(message && message.body)}`;
+}
+
+const CANCEL_LEADING =
+  /^(stop|cancel|abort|halt|nvm|never ?mind|hold on|forget (it|that)|scrap (it|that)|stop (it|that|working))\b/;
+const CANCEL_WHOLE = /^(stop|cancel|abort|halt|nvm|never ?mind|forget it)[.!]?$/;
+
+/**
+ * Is this message a "stop what you're doing" intent — not a task that merely
+ * contains the word "stop" (e.g. "stop the navbar from overflowing")? Tight by
+ * design: a whole-message stop/cancel, or a short message led by a cancel verb.
+ * Callers MUST also gate on "is something actually running" so a stray "stop"
+ * with nothing active stays ordinary chat.
+ */
+export function looksLikeCancel(text) {
+  const t = normalizeTask(text);
+  if (!t) return false;
+  if (CANCEL_WHOLE.test(t)) return true;
+  if (t.split(" ").length <= 4 && CANCEL_LEADING.test(t)) return true;
+  return false;
+}
+
+/**
+ * In-process FIFO worker. `runJob(job, { signal })` is awaited one at a time
+ * (concurrency 1 — parallel CLI runs on one checkout would collide on git state).
+ *
+ * - enqueue(job) → { accepted, deduped, position, startedImmediately }. `job.key`
+ *   (optional) dedupes against the active + queued jobs.
+ * - cancelActive(reason) aborts ONLY the in-flight job's AbortSignal; queued jobs
+ *   are untouched.
+ * - idle() resolves when nothing is active or queued (used to drain on --once).
+ */
+/**
+ * @param {{
+ *   runJob: (job: any, ctx: { signal: AbortSignal }) => Promise<void> | void,
+ *   concurrency?: number,
+ * }} [opts]
+ */
+export function createQueue(opts = {}) {
+  const { runJob, concurrency = 1 } = opts;
+  void concurrency; // single-slot in v1; documented in the ticket.
+  const queued = [];
+  let active = null; // { job, controller }
+  let draining = false;
+  let idleResolvers = [];
+
+  function has(key) {
+    if (key == null) return false;
+    // A cancelled job is on its way out (it stays in `active` until its abort
+    // tears the run down), so it must NOT dedupe-block a re-ask of the same thing
+    // — otherwise "stop" + re-issue the same task gets silently swallowed.
+    if (active && !active.cancelled && active.job.key === key) return true;
+    return queued.some((j) => j.key === key);
+  }
+
+  async function drain() {
+    if (draining) return;
+    draining = true;
+    while (queued.length) {
+      const job = queued.shift();
+      const controller = new AbortController();
+      active = { job, controller };
+      try {
+        await runJob(job, { signal: controller.signal });
+      } catch {
+        // runJob is expected to handle its own errors; never break the loop.
+      }
+      active = null;
+    }
+    draining = false;
+    const resolvers = idleResolvers;
+    idleResolvers = [];
+    for (const r of resolvers) r();
+  }
+
+  function enqueue(job) {
+    if (job && job.key != null && has(job.key)) {
+      return { accepted: false, deduped: true, position: 0, startedImmediately: false };
+    }
+    const startedImmediately = !active && queued.length === 0;
+    queued.push(job);
+    const position = queued.length + (active ? 1 : 0); // 1-based, including active
+    void drain();
+    return { accepted: true, deduped: false, position, startedImmediately };
+  }
+
+  function cancelActive(reason) {
+    if (!active) return false;
+    active.cancelled = true; // stop it from dedupe-blocking a same-key re-ask
+    active.controller.abort(reason || "cancelled");
+    return true;
+  }
+
+  function size() {
+    return queued.length;
+  }
+  function activeCount() {
+    return active ? 1 : 0;
+  }
+  function idle() {
+    if (!active && queued.length === 0) return Promise.resolve();
+    return new Promise((r) => idleResolvers.push(r));
+  }
+
+  return { enqueue, cancelActive, has, size, active: activeCount, idle };
+}

package/src/run.mjs

@@ -5,6 +5,7 @@
 import { makeClient } from "./mcp.mjs";
 import { mentionHandle } from "./daemon.mjs";
 import { handleTask } from "./handler.mjs";
+import { createQueue, looksLikeCancel, dedupeKey } from "./queue.mjs";
 
 export async function run(cfg, { handler = handleTask, log = console } = {}) {
   if (!cfg.token) {
@@ -38,13 +39,61 @@ export async function run(cfg, { handler = handleTask, log = console } = {}) {
   const seen = new Set();
   const cursor = { value: since ? new Date(since).toISOString() : null };
 
+  // One-at-a-time worker so the poll loop NEVER blocks on a multi-minute run.
+  // The loop only fetches + enqueues; the queue runs jobs in order. This is what
+  // 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),
+  });
+
+  async function safeHandle(message, channelId, signal) {
+    try {
+      log.log(`→ task in ${channelId}: "${(message.body || "").slice(0, 80)}"`);
+      await handler({ message, channelId, tool, me }, cfg, undefined, { signal });
+    } catch (e) {
+      log.error(`handler error: ${e.message}`);
+      await tool("post_message", {
+        channelId,
+        body: `Hit an error working on that: ${e.message}`,
+      }).catch(() => {});
+    }
+  }
+
+  // Route one fresh mention: a "stop" cancels the active run; anything else is
+  // 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) {
+    if (looksLikeCancel(m.body) && (queue.active() || queue.size())) {
+      queue.cancelActive("user asked to stop");
+      await tool("post_message", {
+        channelId,
+        parentId: m.parentId ?? null,
+        body: "Stopping the current task.",
+      }).catch(() => {});
+      return;
+    }
+    const r = queue.enqueue({ message: m, channelId, key: dedupeKey(m, channelId) });
+    if (r.deduped) {
+      log.log("  (deduped a repeat of an in-flight/queued ask)");
+      return;
+    }
+    if (cfg.queueAcks && !r.startedImmediately) {
+      await tool("post_message", {
+        channelId,
+        parentId: m.parentId ?? null,
+        body: "Got it — queued behind the current task.",
+      }).catch(() => {});
+    }
+  }
+
   async function passViaMentions() {
     const out = await tool("list_mentions", cursor.value ? { since: cursor.value } : {});
     const mentions = (out?.mentions ?? []).slice().reverse();
     for (const m of mentions) {
       if (seen.has(m.id)) continue;
       seen.add(m.id);
-      await safeHandle(m, m.channelId);
+      await intake(m, m.channelId);
       // Compare numerically — created_at formats differ (Z vs +00:00 offset),
       // 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()) {
@@ -61,24 +110,11 @@ export async function run(cfg, { handler = handleTask, log = console } = {}) {
         seen.add(m.id);
         if (m.author === me.agentName) continue;
         const isMention = new RegExp(`@${me.handle}\\b`, "i").test(m.body || "");
-        if (isMention && new Date(m.created_at).getTime() >= since) await safeHandle(m, channelId);
+        if (isMention && new Date(m.created_at).getTime() >= since) await intake(m, channelId);
       }
     }
   }
 
-  async function safeHandle(message, channelId) {
-    try {
-      log.log(`→ task in ${channelId}: "${(message.body || "").slice(0, 80)}"`);
-      await handler({ message, channelId, tool, me }, cfg);
-    } catch (e) {
-      log.error(`handler error: ${e.message}`);
-      await tool("post_message", {
-        channelId,
-        body: `Hit an error working on that: ${e.message}`,
-      }).catch(() => {});
-    }
-  }
-
   do {
     try {
       if (useMentions) await passViaMentions();
@@ -86,6 +122,11 @@ export async function run(cfg, { handler = handleTask, log = console } = {}) {
     } catch (e) {
       log.error(`poll error: ${e.message}`);
     }
-    if (!cfg.once) await new Promise((r) => setTimeout(r, cfg.pollMs));
-  } while (!cfg.once);
+    // --once is for cron-style single passes: drain the queued work before exit.
+    if (cfg.once) {
+      await queue.idle();
+      break;
+    }
+    await new Promise((r) => setTimeout(r, cfg.pollMs));
+  } while (true);
 }