hilos-agent 0.1.15 → 0.4.0

package/README.md

@@ -87,6 +87,69 @@ hilos-agent --channel <id>   # scope to one channel
   card and polls for your decision; **Approve** pushes + opens the PR, **Reject**
   discards the branch, **Request changes** re-runs with your note (bounded rounds).
 
+## Local folders (no repo required)
+
+A channel doesn't need a linked GitHub repo to get coding work done. Map a channel
+to a plain **local folder** and the agent works in it **directly** — it edits the
+files in place (no branch, no commit, no PR), then posts a report of what changed.
+It's your own machine, so this is the same trust as running the CLI yourself.
+
+```jsonc
+// hilos-agent.json
+{
+  "folders": { "<channelId>": "/Users/you/notes-site" }
+}
+```
+
+- **Trigger** — an `@mention` in a channel with **no linked repo** but a `folders`
+  mapping. The same LLM router decides chat vs. code; a coding ask runs in the
+  folder.
+- **Git folders** — if the folder is a git repo, the agent snapshots `git status`
+  before/after and reports the exact files it created/changed/removed plus a
+  `git diff --stat`. It **never** touches your index, branches, pushes, or runs
+  `gh`. On the report card: **Approve** keeps the changes (they're already live),
+  **Request changes** re-runs in place with your note (bounded by `maxRounds`),
+  **Reject** reverts *only what this run changed* (`git checkout` the files it
+  modified, delete the files it created) — your pre-existing local edits are left
+  untouched.
+- **Non-git folders** — it still runs, but says up front it can't show a file-level
+  diff or auto-undo; a reject asks you to revert by hand.
+- A **linked repo always wins** — the folder map is only consulted when the channel
+  has no repo link.
+- **Folder link registration** — on startup the daemon registers each `folders`
+  mapping with hilos (over the `link_folder` MCP tool) so the channel shows a
+  folder chip — the folder's name, its full path, and which machine it lives on —
+  without any manual step. It's best-effort and capability-gated: older servers
+  that don't expose `link_folder` are skipped silently, and a failed registration
+  only logs a line, never blocking the daemon. Registration happens once at
+  startup, so a `folders` entry added while the daemon is running needs a restart
+  to appear.
+
+## Embedding the daemon
+
+`run(cfg, opts)` is the poll loop, and it's embeddable. Beyond `handler`/`log` it
+accepts:
+
+```js
+import { run } from "hilos-agent/src/run.mjs";
+
+const controller = new AbortController();
+await run(cfg, {
+  signal: controller.signal,   // abort → interrupts the poll sleep, cancels the
+                               //         active job, and returns cleanly
+  onEvent: (e) => {            // lifecycle events for a host UI (wrapped in
+    // e.type: "status" | "task-start" | "task-done" | "task-error"
+    console.log(e);            //   try/catch — a bad listener can't crash the loop)
+  },
+});
+// later: controller.abort();  // run() resolves once the active job tears down
+```
+
+Event shapes: `{ type: "status", text }`, `{ type: "task-start", channelId,
+messageId, text }`, `{ type: "task-done", channelId, status }`, and
+`{ type: "task-error", channelId, error }`. Both options are optional and fully
+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
@@ -125,6 +188,47 @@ 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.
 
+## Hooks — stream a raw Claude Code session
+
+Don't want to run a persistent daemon? You can still make your Claude Code CLI
+sessions visible to your team in real time. **Claude Code hooks** (shipped in
+0448) let every tool call your session makes stream directly into your agent's
+live status card in hilos — no daemon, no extra process.
+
+```sh
+# Inside the repo you want to stream:
+npx hilos-agent hooks install
+
+# Or stream all your Claude Code sessions, everywhere:
+npx hilos-agent hooks install --global
+```
+
+This writes `PostToolUse`, `Stop`, and `SessionEnd` hook entries into
+`.claude/settings.json` (project) or `~/.claude/settings.json` (global),
+preserving any hooks you already have. Preview the block without writing anything:
+
+```sh
+npx hilos-agent hooks print
+```
+
+**Requirements:**
+- `npm i -g hilos-agent` so the `hilos-agent hook` command resolves at hook time.
+- A `~/.hilos/agent.json` with `url`, `token`, and `channelId`. Generate these in
+  the agent's **Connect via MCP** panel in hilos (same panel as `--join`).
+
+**What you get:**
+- Team members see "Editing lib/x.ts" or "Running pnpm test" on the agent's live
+  card as each tool fires — without you doing anything beyond the install.
+- Steps are coalesced into ~2s batches to keep traffic light.
+- When a turn ends (`Stop`), the card settles to done. The next turn revives the
+  same card — one card per session, not one per turn.
+- Up to 20 unique files touched are surfaced so reviewers can glance at the scope
+  before the report card arrives.
+
+**Privacy:** project-level by default (only repos you opt into stream). Global
+kill switch: `HILOS_HOOKS=off`. The hook always exits 0 — it will never interrupt
+or break your CLI session.
+
 ## Security
 
 The daemon runs a coding agent that can execute code in your repo — exactly as if

package/bin/hilos-agent.mjs

@@ -18,6 +18,7 @@
 
 import { resolveConfig, decodeJoin, writeStarterConfig, GLOBAL_CONFIG } from "../src/config.mjs";
 import { run } from "../src/run.mjs";
+import { hookMain, hooksMain } from "../src/hook.mjs";
 
 function parseArgs(argv) {
   const flags = {};
@@ -34,10 +35,11 @@ function parseArgs(argv) {
     else if (a === "--once") flags.once = true;
     else if (a === "--backfill") flags.backfill = true;
     else if (a === "--no-gate") flags.gate = false;
+    else if (a === "--global") flags.global = true;
     else if (a === "-h" || a === "--help") flags.help = true;
     else positional.push(a);
   }
-  return { cmd: positional[0] || "run", flags };
+  return { cmd: positional[0] || "run", flags, positional };
 }
 
 const HELP = `hilos-agent — your coding agent as a teammate in hilos
@@ -45,6 +47,10 @@ const HELP = `hilos-agent — your coding agent as a teammate in hilos
   hilos-agent --join <blob>      connect using a link copied from hilos
   hilos-agent init               write a starter config to ~/.hilos/agent.json
   hilos-agent                    run the daemon (watch @mentions, propose diffs)
+  hilos-agent hooks install      stream this repo's Claude Code sessions to your
+                                 hilos channel (writes .claude/settings.json;
+                                 --global for every repo). "hooks print" shows
+                                 the snippet; HILOS_HOOKS=off pauses streaming.
 
 Options:
   --channel <id>     watch only one channel (per-channel override)
@@ -60,12 +66,24 @@ Options:
 Docs: https://hilos.sh  ·  https://www.npmjs.com/package/hilos-agent`;
 
 async function main() {
-  const { cmd, flags } = parseArgs(process.argv.slice(2));
+  const { cmd, flags, positional } = parseArgs(process.argv.slice(2));
   if (flags.help || cmd === "help") {
     console.log(HELP);
     return;
   }
 
+  // `hook` is invoked BY Claude Code on every tool call (0448) — it must be
+  // fast, silent, and always exit 0, so it short-circuits before any daemon
+  // machinery.
+  if (cmd === "hook") {
+    await hookMain();
+    return;
+  }
+  if (cmd === "hooks") {
+    hooksMain(positional[1], { global: Boolean(flags.global) });
+    return;
+  }
+
   const joinPayload = flags.join ? decodeJoin(flags.join) : undefined;
   if (flags.join && !joinPayload) {
     console.error("That --join link is invalid. Re-copy it from hilos.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.1.15",
+  "version": "0.4.0",
   "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/agent-events.mjs

@@ -0,0 +1,371 @@
+// Normalized vendor stream parser (0272). The KEYSTONE of the "Agents feel
+// alive" epic: coding CLIs each narrate their work in a different, unstable
+// wire format (Claude Code emits `--output-format stream-json` NDJSON, Codex
+// emits `--json` item events, Cursor emits unstructured text). This module turns
+// any of them into ONE small, typed `AgentEvent` stream the UI can render as a
+// live "what the agent is doing right now" card.
+//
+// Design rules that make this safe to point at an untrusted, evolving CLI:
+//   - PURE + dependency-free (node builtins only) so it stands alone and is
+//     unit-tested without a sandbox — mirror of the .mjs siblings' style.
+//   - NEVER throws. A vendor changing its format, a non-JSON log line, or an
+//     unknown event type must DEGRADE (emit nothing), never crash a run.
+//   - Every string that reaches the UI is sanitized (token-shaped secrets
+//     stripped, length capped) — a chatty CLI can echo a `Bearer …` header.
+//
+// Claude shapes here MATCH `lib/hosted-worklog.ts` / `lib/hosted-agent.ts`
+// (`formatClaudeEvent`, `parseStreamResult`) so ticket 0274 can swap the daemon's
+// hand-rolled `lastLine` capture (see handler.mjs onData ~:787) for this parser
+// with zero behavior change. NOTHING imports this yet except the test — wiring is
+// 0274.
+
+/**
+ * @typedef {object} AgentEvent
+ * A normalized, render-ready step. Exactly one of these per meaningful thing the
+ * coding agent did. Small on purpose — the LiveRunCard maps `t` to a label.
+ * @property {'phase'|'edit'|'run'|'read'|'think'|'note'|'session'|'result'} t
+ *   - 'session' → { sessionId }        the CLI's resumable session id (init only)
+ *   - 'edit'    → { path }             wrote/edited a file
+ *   - 'read'    → { path }             read a file
+ *   - 'run'     → { cmd }              ran a shell command
+ *   - 'note'    → { text }             the agent's narration / thinking (think→note)
+ *   - 'result'  → { ok, summary? }     the run finished (ok=false on error)
+ *   - 'phase'   → { name }             reserved lifecycle marker (unused by v1
+ *                                       parsers; kept so 0274 can add start/end
+ *                                       phases without widening the type)
+ * @property {string} [sessionId]
+ * @property {string} [path]
+ * @property {string} [cmd]
+ * @property {string} [text]
+ * @property {string} [name]
+ * @property {boolean} [ok]
+ * @property {string} [summary]
+ */
+
+// --- Security: sanitize everything that reaches the UI ---------------------
+
+const MAX_LEN = 300;
+const REDACTED = "[redacted]";
+
+// Token-shaped strings a CLI might echo (auth headers, keys it was handed, hex/
+// base64 blobs). Order matters — specific prefixes before the generic blobs so a
+// `ghp_…` is labelled, not swallowed by the base64 rule.
+const SECRET_PATTERNS = [
+  /\bBearer\s+[A-Za-z0-9._\-]+/gi, // "Bearer <token>"
+  /\bhilos_[A-Za-z0-9]{8,}/g, // hilos MCP bearer tokens
+  /\bsbp_[A-Za-z0-9]{16,}/g, // Supabase access/management tokens (SUPABASE_ACCESS_TOKEN)
+  /\bgithub_pat_[A-Za-z0-9_]{20,}/g, // fine-grained GitHub PAT
+  /\bgh[pousr]_[A-Za-z0-9]{20,}/g, // ghp_/gho_/ghu_/ghs_/ghr_ GitHub tokens
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/g, // Slack tokens
+  /\bsk-[A-Za-z0-9_-]{16,}/g, // OpenAI/Anthropic-style secret keys
+  /\b[A-Fa-f0-9]{32,}\b/g, // long hex blobs
+  /\b[A-Za-z0-9+/]{40,}={0,2}\b/g, // long base64 blobs
+];
+
+/**
+ * Strip token-shaped secrets and cap length. Exported so the server (0274+) can
+ * reuse the exact same redaction on anything it echoes. Never throws; non-string
+ * input → "".
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function sanitizeText(value) {
+  if (typeof value !== "string") return "";
+  let out = value;
+  for (const re of SECRET_PATTERNS) out = out.replace(re, REDACTED);
+  if (out.length > MAX_LEN) out = out.slice(0, MAX_LEN - 1) + "…";
+  return out;
+}
+
+// --- Line parsing per vendor ----------------------------------------------
+
+/** JSON.parse that returns null instead of throwing on a non-JSON line. */
+function tryParse(line) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed) return null;
+  try {
+    const obj = JSON.parse(trimmed);
+    return obj && typeof obj === "object" ? obj : null;
+  } catch {
+    return null; // log noise / partial line / plain text → ignore
+  }
+}
+
+/** Map a Claude/agent tool name to a normalized event kind (or null to skip). */
+function toolKind(name) {
+  switch (name) {
+    case "Edit":
+    case "MultiEdit":
+    case "Write":
+    case "NotebookEdit":
+      return "edit";
+    case "Read":
+      return "read";
+    case "Bash":
+      return "run";
+    default:
+      // Grep/Glob/WebFetch/Task/etc. carry less "alive" signal; ignore in v1 so
+      // an unknown tool can never crash the parser. 0274 may promote some.
+      return null;
+  }
+}
+
+/** One assistant content block → an AgentEvent, or null. */
+function blockToEvent(block) {
+  if (!block || typeof block !== "object") return null;
+  if (block.type === "text" && typeof block.text === "string") {
+    const text = sanitizeText(block.text.replace(/\s+/g, " ").trim());
+    return text ? { t: "note", text } : null;
+  }
+  if (block.type === "tool_use" && typeof block.name === "string") {
+    const kind = toolKind(block.name);
+    if (!kind) return null;
+    const input = block.input && typeof block.input === "object" ? block.input : {};
+    if (kind === "run") {
+      const cmd = typeof input.command === "string" ? input.command.replace(/\s+/g, " ").trim() : "";
+      return { t: "run", cmd: sanitizeText(cmd) };
+    }
+    const raw = input.file_path ?? input.path ?? input.notebook_path;
+    const path = typeof raw === "string" ? sanitizeText(raw) : "";
+    return { t: kind, path };
+  }
+  return null;
+}
+
+/**
+ * Parse ONE Claude Code `stream-json` NDJSON line → AgentEvent[]. Shapes mirror
+ * `lib/hosted-agent.ts`: system init (session_id), assistant turns (text +
+ * tool_use), and the final result. Everything else (user tool_result, unknown
+ * types) → [].
+ */
+function parseClaudeLine(line) {
+  const obj = tryParse(line);
+  if (!obj) return [];
+  if (obj.type === "system" && typeof obj.session_id === "string") {
+    return [{ t: "session", sessionId: sanitizeText(obj.session_id) }];
+  }
+  if (obj.type === "result") {
+    const ok = obj.is_error !== true && obj.subtype !== "error";
+    const summary = typeof obj.result === "string" ? sanitizeText(obj.result) : undefined;
+    return [summary ? { t: "result", ok, summary } : { t: "result", ok }];
+  }
+  if (obj.type === "assistant" && obj.message && Array.isArray(obj.message.content)) {
+    const out = [];
+    for (const block of obj.message.content) {
+      const ev = blockToEvent(block);
+      if (ev) out.push(ev);
+    }
+    return out;
+  }
+  return [];
+}
+
+/**
+ * Parse ONE Codex `--json` item line → AgentEvent[]. Best-effort / experimental:
+ * Codex's format is younger and less documented, so we read the kind from either
+ * `item.type` (the `{type:"item.completed", item:{…}}` envelope) or a bare
+ * top-level `type`, and pull fields from whichever object carries them. Unknown
+ * kinds → [].
+ */
+function parseCodexLine(line) {
+  const obj = tryParse(line);
+  if (!obj) return [];
+  const item = obj.item && typeof obj.item === "object" ? obj.item : obj;
+  const kind = item.type ?? obj.type;
+  switch (kind) {
+    case "command_execution": {
+      const raw = item.command ?? item.cmd;
+      const cmd = typeof raw === "string" ? raw.replace(/\s+/g, " ").trim() : "";
+      return cmd ? [{ t: "run", cmd: sanitizeText(cmd) }] : [];
+    }
+    case "file_change": {
+      const changes = Array.isArray(item.changes)
+        ? item.changes
+        : item.path
+          ? [{ path: item.path }]
+          : [];
+      const out = [];
+      for (const c of changes) {
+        const p = c && (c.path ?? c.file_path);
+        if (typeof p === "string" && p) out.push({ t: "edit", path: sanitizeText(p) });
+      }
+      return out;
+    }
+    case "agent_message": {
+      const raw = item.text ?? item.message;
+      const text = typeof raw === "string" ? sanitizeText(raw.replace(/\s+/g, " ").trim()) : "";
+      return text ? [{ t: "note", text }] : [];
+    }
+    case "task_complete":
+    case "turn.completed": {
+      const raw = item.text ?? item.message ?? obj.text;
+      const summary = typeof raw === "string" ? sanitizeText(raw) : undefined;
+      return [summary ? { t: "result", ok: true, summary } : { t: "result", ok: true }];
+    }
+    default:
+      return [];
+  }
+}
+
+/** claude / claude_code / claude-code all mean the Claude parser. */
+function normalizeVendor(vendor) {
+  const v = String(vendor || "").toLowerCase();
+  if (v === "claude" || v === "claude_code" || v === "claude-code") return "claude";
+  if (v === "codex") return "codex";
+  return "cursor"; // cursor + ANY unknown vendor → lastLine fallback
+}
+
+// --- Streaming parsers -----------------------------------------------------
+
+/**
+ * The daemon pushes raw stdout chunks (see handler.mjs onData ~:787) that can
+ * split a JSON object mid-line. A structured parser buffers the partial tail and
+ * only parses COMPLETE lines; flush() drains a trailing unterminated line.
+ * @param {(line: string) => AgentEvent[]} parseLine
+ */
+function makeLineBufferedParser(parseLine) {
+  let buf = "";
+  return {
+    /** @param {string} chunk @returns {AgentEvent[]} */
+    push(chunk) {
+      buf += String(chunk ?? "");
+      const out = [];
+      let nl;
+      while ((nl = buf.indexOf("\n")) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        for (const ev of parseLine(line)) out.push(ev);
+      }
+      return out;
+    },
+    /** @returns {AgentEvent[]} */
+    flush() {
+      const out = [];
+      if (buf.trim()) for (const ev of parseLine(buf)) out.push(ev);
+      buf = "";
+      return out;
+    },
+  };
+}
+
+/**
+ * Fallback for Cursor and any vendor with no structured stream. There's nothing
+ * to parse, so we only remember the last non-empty line seen — matching exactly
+ * what the daemon does today (handler.mjs onData) so we NEVER regress below it —
+ * and emit at most one sparse note on flush.
+ */
+function makeCursorParser() {
+  let lastLine = "";
+  return {
+    /** @returns {AgentEvent[]} */
+    push(chunk) {
+      const lines = String(chunk ?? "")
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (lines.length) lastLine = lines[lines.length - 1];
+      return []; // no structured events mid-stream
+    },
+    /** @returns {AgentEvent[]} */
+    flush() {
+      if (!lastLine) return [];
+      const text = sanitizeText(lastLine);
+      lastLine = "";
+      return text ? [{ t: "note", text }] : [];
+    },
+  };
+}
+
+/**
+ * Build a stateful stream parser for `vendor`.
+ * @param {'claude'|'claude_code'|'codex'|'cursor'|string} vendor
+ * @returns {{ push: (chunk: string) => AgentEvent[], flush: () => AgentEvent[] }}
+ */
+export function makeStreamParser(vendor) {
+  const v = normalizeVendor(vendor);
+  if (v === "claude") return makeLineBufferedParser(parseClaudeLine);
+  if (v === "codex") return makeLineBufferedParser(parseCodexLine);
+  return makeCursorParser();
+}
+
+// --- Human step labels (what the LiveRunCard shows) ------------------------
+
+/** Describe a shell command in plain words (design rule: no emoji, calm copy). */
+function describeRun(cmd) {
+  const c = String(cmd || "").trim();
+  if (!c) return "Running a command";
+  if (/\b(test|tests)\b|vitest|jest|pytest|\bgo test\b/i.test(c)) return "Running tests";
+  const short = c.length > 60 ? c.slice(0, 59) + "…" : c;
+  return `Running ${short}`;
+}
+
+/**
+ * One AgentEvent → a human step label, or null for events that aren't shown as
+ * steps (session/phase are metadata). Pure.
+ * @param {AgentEvent} event
+ * @returns {string | null}
+ */
+export function stepLabel(event) {
+  switch (event && event.t) {
+    case "edit":
+      return event.path ? `Editing ${event.path}` : "Editing files";
+    case "read":
+      return event.path ? `Reading ${event.path}` : "Reading files";
+    case "run":
+      return describeRun(event.cmd);
+    case "note":
+      return event.text ? event.text : null;
+    case "result":
+      return event.ok ? "Done" : "Finished with errors";
+    default:
+      return null; // session / phase / unknown → not a step
+  }
+}
+
+/**
+ * A bounded ring buffer of the most recent human step labels. Coalesces
+ * sequential edits to the SAME file into one step (a run that touches one file
+ * ten times reads as one "Editing …" line) and drops immediate duplicate
+ * labels. `limit` steps kept (default 8) — the card shows a short rolling window.
+ * @param {number} [limit]
+ */
+export function createStepRing(limit = 8) {
+  const steps = [];
+  let lastEditPath = null; // for collapsing consecutive same-file edits
+
+  /** @param {AgentEvent} event */
+  function push(event) {
+    const label = stepLabel(event);
+    if (!label) return;
+    if (event.t === "edit") {
+      if (lastEditPath === event.path) return; // same file again → collapse
+      lastEditPath = event.path;
+    } else {
+      lastEditPath = null; // any other step breaks an edit run
+    }
+    if (steps.length && steps[steps.length - 1] === label) return; // dup guard
+    steps.push(label);
+    if (steps.length > limit) steps.shift();
+  }
+
+  return {
+    push,
+    /** @returns {string[]} */
+    labels: () => steps.slice(),
+    /** @returns {string | null} */
+    latest: () => (steps.length ? steps[steps.length - 1] : null),
+  };
+}
+
+/**
+ * Fold a batch of events through a fresh ring → the coalesced step labels. Pure
+ * convenience over createStepRing for callers that have the whole list.
+ * @param {AgentEvent[]} events
+ * @param {number} [limit]
+ * @returns {string[]}
+ */
+export function summarizeSteps(events, limit = 8) {
+  const ring = createStepRing(limit);
+  for (const ev of events || []) ring.push(ev);
+  return ring.labels();
+}

package/src/config.mjs

@@ -43,6 +43,11 @@ const DEFAULTS = {
   token: "",
   channelId: "", // when set, watch only this channel (the per-channel override)
   repos: {},
+  // Local-folder mode (0322): map a channelId → an absolute folder path so a
+  // channel with NO linked GitHub repo can still get coding work done in a plain
+  // folder on this machine. Changes apply directly (no branch/PR). Live-reloadable
+  // like `repos`. Shape: { "<channelId>": "/abs/path" }.
+  folders: {},
   // 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.
@@ -63,6 +68,11 @@ const DEFAULTS = {
   // spam. 0 disables. Clamped to >=15s so a misconfig can't spam realtime
   // UPDATEs. (Distinct from cli.mjs's 15s LOCAL terminal heartbeat.)
   heartbeatMs: 180000,
+  // Live-progress throttle (0274): when the server supports post_progress, the
+  // code run streams a coalesced "what I'm doing right now" card instead of the
+  // 3-min heartbeat. This caps how often it pushes an UPDATE (leading+trailing).
+  // Clamped to >=750ms so a misconfig can't hammer realtime.
+  progressMs: 2000,
   // Cap a chat reply / plan-ack so a stalled model can't dead-air the channel;
   // on timeout we post an honest "taking longer than expected" line.
   chatTimeoutMs: 90000,
@@ -88,6 +98,7 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
     codingCmd: process.env.CODING_CMD,
     chatCmd: process.env.HILOS_CHAT_CMD,
     heartbeatMs: process.env.HILOS_HEARTBEAT_MS ? Number(process.env.HILOS_HEARTBEAT_MS) : undefined,
+    progressMs: process.env.HILOS_PROGRESS_MS ? Number(process.env.HILOS_PROGRESS_MS) : undefined,
     chatTimeoutMs: process.env.HILOS_CHAT_TIMEOUT_MS ? Number(process.env.HILOS_CHAT_TIMEOUT_MS) : undefined,
     backfill: process.env.HILOS_BACKFILL === "1" ? true : undefined,
     once: process.env.HILOS_ONCE === "1" ? true : undefined,
@@ -96,6 +107,8 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
   for (const [k, v] of Object.entries(env)) if (v !== undefined && v !== "") merged[k] = v;
   // Clamp the chat heartbeat: 0 (off) stays off, otherwise never below 15s.
   if (merged.heartbeatMs > 0) merged.heartbeatMs = Math.max(15000, Number(merged.heartbeatMs) || 0);
+  // Clamp the live-progress throttle to a >=750ms floor (a bad value → the default).
+  merged.progressMs = Math.max(750, Number(merged.progressMs) || 2000);
   if (joinPayload) {
     merged.url = joinPayload.url;
     merged.token = joinPayload.token;
@@ -103,6 +116,8 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
   }
   for (const [k, v] of Object.entries(flags)) if (v !== undefined) merged[k] = v;
   merged.repos = { ...DEFAULTS.repos, ...(file.repos || {}) };
+  // Local-folder map, merged like `repos` (an object, not a scalar overlay).
+  merged.folders = { ...DEFAULTS.folders, ...(file.folders || {}) };
   // Remember where the file lives so reloadConfig can re-read it live.
   merged.configPath = findConfigPath(flags.config) || null;
   return merged;
@@ -122,10 +137,15 @@ const LIVE_FIELDS = [
   "decisionTimeoutMs",
   "decisionPollMs",
   "heartbeatMs",
+  "progressMs",
   "chatTimeoutMs",
   // NOT queueConcurrency: the queue is built once at startup, so it can't change
   // live. queueAcks IS live (intake() reads it per-mention from liveCfg).
   "queueAcks",
+  // folders is an object map; it's listed here for documentation, but the actual
+  // live merge (with DEFAULTS) happens in the special-cased block below, exactly
+  // like `repos`, so a partial edit doesn't drop the defaults.
+  "folders",
 ];
 
 /**
@@ -146,9 +166,14 @@ export function reloadConfig(prev) {
   if (process.env.CODING_CMD) next.codingCmd = process.env.CODING_CMD;
   if (process.env.HILOS_CHAT_CMD) next.chatCmd = process.env.HILOS_CHAT_CMD;
   if (process.env.HILOS_HEARTBEAT_MS) next.heartbeatMs = Number(process.env.HILOS_HEARTBEAT_MS);
+  if (process.env.HILOS_PROGRESS_MS) next.progressMs = Number(process.env.HILOS_PROGRESS_MS);
   if (process.env.HILOS_CHAT_TIMEOUT_MS) next.chatTimeoutMs = Number(process.env.HILOS_CHAT_TIMEOUT_MS);
   if (next.heartbeatMs > 0) next.heartbeatMs = Math.max(15000, Number(next.heartbeatMs) || 0);
+  next.progressMs = Math.max(750, Number(next.progressMs) || 2000);
   if (file.repos) next.repos = { ...DEFAULTS.repos, ...file.repos };
+  // Merge the folder map like repos (overriding the raw scalar-loop assignment
+  // above with a proper DEFAULTS-merged object).
+  if (file.folders) next.folders = { ...DEFAULTS.folders, ...file.folders };
   return next;
 }