hilos-agent 0.7.0 → 0.9.0

package/README.md

@@ -82,9 +82,24 @@ 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.
+- **Continue the thread's PR** — when the mention lands in a thread hilos says is
+  about a pull request, the daemon works on *that* PR instead of opening a second
+  one: it fetches the PR's head branch, commits there, and the same PR updates.
+  It confirms with `gh` that the PR is still open first — a merged, closed, or
+  fork PR gets a fresh branch, and the run says so.
+- **Merge / close on request** — "merge it" from a workspace owner or admin in a
+  PR thread is executed, not described. The daemon relays the request to hilos
+  with the id of the message that asked; hilos verifies the person's role and
+  that their message really asks for it, then acts with the workspace's GitHub
+  App. The daemon never merges on its own judgment and holds no merge rights.
 - **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.
+- **Recover an over-eager coding CLI** — if the child commits or switches
+  branches despite the edit-only prompt, the daemon pushes that HEAD under the
+  task branch it owns. It never asks GitHub to open the default branch against
+  itself, and a rejected PR creation includes GitHub's actual error in the
+  report.
 - **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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.7.0",
+  "version": "0.9.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/acp-session.mjs

@@ -0,0 +1,538 @@
+// ACP (Agent Client Protocol) session runner (0759).
+//
+// Drives an agent subprocess over ACP — JSON-RPC 2.0, newline-delimited, on
+// stdio — instead of argv + stdout scraping. The 0596 spike proved the loop
+// live against `opencode acp`: permissions arrive as blocking JSON-RPC
+// requests with allow-once/always/reject options, and streaming arrives as
+// structured session/update notifications.
+//
+// The permission callback contract is EXACTLY the HTTP bridge's
+// (requestPermission / getPermissionDecision, see opencode-permissions.mjs),
+// so neither transport can become the ungated exception; the decision
+// vocabulary is shared via mapOpenCodePermissionDecision. Every failure mode
+// answers the agent with a rejection — fail closed, never fail open.
+//
+// The public runner returns the same small shape as runCli /
+// runOpenCodeHttpSession so handler.mjs keeps one integration seam:
+//   { status, stdout, stderr, error?, sessionId?, aborted? }
+
+import { spawn } from "node:child_process";
+import { mapOpenCodePermissionDecision } from "./opencode-permissions.mjs";
+
+const DEFAULT_TIMEOUT_MS = 30 * 60_000;
+const DEFAULT_POLL_MS = 1_000;
+const SHUTDOWN_GRACE_MS = 750;
+const PROTOCOL_VERSION = 1;
+const MAX_LINE_BYTES = 4 * 1024 * 1024;
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function abortError(reason = "cancelled") {
+  const error = new Error(String(reason || "cancelled"));
+  error.name = "AbortError";
+  return error;
+}
+
+function raceWithAbort(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(abortError(signal.reason));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal.reason));
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve(promise).then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Choose the agent's option id for a hilos reply ("once"|"always"|"reject").
+ * Matches on the ACP option `kind` first (allow_once / allow_always /
+ * reject_once / reject_always), then falls back to id/name heuristics. A
+ * reject reply with no recognizable option returns null — the caller answers
+ * with a protocol-level cancel, which the agent must treat as not-allowed.
+ */
+export function pickAcpPermissionOption(options, reply) {
+  const list = Array.isArray(options) ? options.filter(isObject) : [];
+  const byKind = (kind) => list.find((o) => o.kind === kind);
+  const byPattern = (re) =>
+    list.find((o) => re.test(`${o.optionId ?? ""} ${o.name ?? ""}`));
+  if (reply === "always") {
+    // The name fallback must never land on "Reject always" — a human's
+    // allow-always answered with a rejection would invert the decision.
+    return (
+      byKind("allow_always") ??
+      list.find(
+        (o) =>
+          !String(o.kind ?? "").startsWith("reject") &&
+          /always/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`) &&
+          !/reject|deny|\bno\b/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`),
+      ) ??
+      null
+    );
+  }
+  if (reply === "once") {
+    // Never widen a single-use approval into a persistent one: an allow_once
+    // option is required; allow_always is NOT an acceptable stand-in.
+    return (
+      byKind("allow_once") ??
+      list.find(
+        (o) =>
+          o.kind !== "allow_always" &&
+          /\bonce\b|allow/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`) &&
+          !/always/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`),
+      ) ??
+      null
+    );
+  }
+  return (
+    byKind("reject_once") ??
+    byKind("reject_always") ??
+    byPattern(/reject|deny|no\b/i) ??
+    null
+  );
+}
+
+/**
+ * Shape an ACP session/request_permission into the vendor-neutral request the
+ * hilos permission callbacks expect (the same fields the SSE relay produces).
+ */
+export function normalizeAcpPermissionRequest(params, fallbackId, vendor = "opencode") {
+  const toolCall = isObject(params?.toolCall) ? params.toolCall : {};
+  const rawInput = isObject(toolCall.rawInput) ? toolCall.rawInput : {};
+  const locations = Array.isArray(toolCall.locations)
+    ? toolCall.locations
+        .map((l) => (isObject(l) && typeof l.path === "string" ? l.path : null))
+        .filter(Boolean)
+    : [];
+  const command = typeof rawInput.command === "string" ? rawInput.command : null;
+  const resources = locations.length ? locations : command ? [command] : [];
+  const vendorRequestId =
+    typeof toolCall.toolCallId === "string" && toolCall.toolCallId
+      ? toolCall.toolCallId
+      : `acp_${fallbackId}`;
+  return {
+    vendor,
+    vendorRequestId,
+    sessionId: typeof params?.sessionId === "string" ? params.sessionId : "",
+    action: typeof toolCall.kind === "string" && toolCall.kind ? toolCall.kind : "tool",
+    resources,
+    suggestedSave: undefined,
+    metadata: {
+      ...(typeof toolCall.title === "string" && toolCall.title
+        ? { title: toolCall.title }
+        : {}),
+      ...(command ? { command } : {}),
+      transport: "acp",
+    },
+    source: { type: "tool", ...(typeof toolCall.title === "string" ? { name: toolCall.title } : {}) },
+  };
+}
+
+/** Split a stdout stream into newline-delimited JSON-RPC messages. */
+export function createNdjsonParser() {
+  let buffer = "";
+  return {
+    push(chunk) {
+      buffer += String(chunk);
+      if (buffer.length > MAX_LINE_BYTES) {
+        // A frame this large is not a protocol message; drop it rather than
+        // letting a runaway agent grow the daemon's heap without bound.
+        buffer = "";
+        return [];
+      }
+      const messages = [];
+      let idx;
+      while ((idx = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, idx).trim();
+        buffer = buffer.slice(idx + 1);
+        if (!line) continue;
+        try {
+          const parsed = JSON.parse(line);
+          if (isObject(parsed)) messages.push(parsed);
+        } catch {
+          // Non-JSON stdout noise (banners, stray logs) is not a frame.
+        }
+      }
+      return messages;
+    },
+  };
+}
+
+/**
+ * Run one prompt against an ACP agent subprocess.
+ *
+ * Slice 1 (0759) intentionally mirrors the HTTP runner's text mode: stdout
+ * collects the agent's completed message text, tool activity stays off the
+ * transcript, and the session id is returned for the caller's records.
+ *
+ * @param {{
+ *   cmd?: string,
+ *   acpArgs?: string[],
+ *   vendor?: string,
+ *   cwd?: string,
+ *   prompt?: string,
+ *   env?: Record<string, string | undefined>,
+ *   timeoutMs?: number,
+ *   pollIntervalMs?: number,
+ *   signal?: AbortSignal,
+ *   onData?: (chunk: string) => void,
+ *   requestPermission?: (request: object, context: object) => Promise<unknown>,
+ *   getPermissionDecision?: (handle: unknown, context: object) => Promise<unknown>,
+ *   mcpServers?: object[],
+ *   spawnImpl?: (cmd: string, args: string[], options: object) => import("node:child_process").ChildProcess,
+ *   setTimer?: typeof setTimeout,
+ *   clearTimer?: typeof clearTimeout,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   now?: () => number,
+ *   log?: { error?: (message: string) => void },
+ * }} [options]
+ * @returns {Promise<{ status: number | null, stdout: string, stderr: string, error?: Error | null, sessionId?: string | null, aborted?: boolean }>}
+ */
+export async function runAcpSession({
+  cmd = "opencode",
+  acpArgs = ["acp"],
+  vendor = "opencode",
+  cwd,
+  prompt,
+  env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  pollIntervalMs = DEFAULT_POLL_MS,
+  signal,
+  onData,
+  requestPermission,
+  getPermissionDecision,
+  mcpServers = [],
+  spawnImpl = spawn,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+  log = console,
+} = {}) {
+  if (!cwd) {
+    return { status: null, stdout: "", stderr: "", error: new Error("ACP requires cwd") };
+  }
+  if (typeof requestPermission !== "function" || typeof getPermissionDecision !== "function") {
+    // Without the hilos gate there is no one to answer asks; refuse to start
+    // rather than run a session whose permissions would dead-end.
+    return {
+      status: null,
+      stdout: "",
+      stderr: "",
+      error: new Error("ACP transport requires the hilos permission callbacks"),
+    };
+  }
+
+  const controller = new AbortController();
+  let abortKind = null;
+  const abort = (kind, reason) => {
+    if (controller.signal.aborted) return;
+    abortKind = kind;
+    controller.abort(reason);
+  };
+  const onParentAbort = () => abort("cancelled", signal?.reason ?? "cancelled");
+  if (signal?.aborted) onParentAbort();
+  else signal?.addEventListener?.("abort", onParentAbort, { once: true });
+  const timeout =
+    timeoutMs > 0
+      ? setTimer(() => abort("timeout", `ACP session timed out after ${timeoutMs}ms`), timeoutMs)
+      : null;
+  timeout?.unref?.();
+
+  let child = null;
+  let sessionId = null;
+  let stdout = "";
+  let stderr = "";
+  let nextId = 0;
+  const pending = new Map();
+  const permissionTasks = new Set();
+  let currentMessageId = null;
+  let messageBuffer = "";
+
+  const emitOutput = (text) => {
+    try {
+      onData?.(`${text}\n`);
+    } catch {
+      // Output observers never own session correctness.
+    }
+  };
+  const flushMessage = () => {
+    const text = messageBuffer.trim();
+    messageBuffer = "";
+    currentMessageId = null;
+    if (!text) return;
+    stdout += `${text}\n`;
+    emitOutput(text);
+  };
+
+  const writeFrame = (frame) => {
+    if (!child || child.stdin.destroyed) return false;
+    try {
+      child.stdin.write(`${JSON.stringify(frame)}\n`);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const rpc = (method, params) => {
+    const id = ++nextId;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject, method });
+      if (!writeFrame({ jsonrpc: "2.0", id, method, params })) {
+        pending.delete(id);
+        reject(new Error(`ACP agent is not accepting frames (${method})`));
+      }
+    });
+  };
+  const respond = (id, result, error) => {
+    writeFrame(
+      error
+        ? { jsonrpc: "2.0", id, error }
+        : { jsonrpc: "2.0", id, result },
+    );
+  };
+  const failPending = (reason) => {
+    for (const [, entry] of pending) entry.reject(new Error(reason));
+    pending.clear();
+  };
+
+  async function settlePermission(msg) {
+    const request = normalizeAcpPermissionRequest(msg.params, msg.id, vendor);
+    const receivedAt = now();
+    const deadlineAt = receivedAt + Math.max(1, timeoutMs || DEFAULT_TIMEOUT_MS);
+    let reply = "reject";
+    let handle = null;
+    try {
+      if (controller.signal.aborted) throw abortError(controller.signal.reason);
+      handle = await raceWithAbort(
+        requestPermission(request, { signal: controller.signal, deadlineAt }),
+        controller.signal,
+      );
+      let decision = handle;
+      let mapped = mapOpenCodePermissionDecision(decision);
+      while (!mapped) {
+        if (now() >= deadlineAt) throw abortError("timeout");
+        decision = await raceWithAbort(
+          getPermissionDecision(handle, {
+            request,
+            signal: controller.signal,
+            deadlineAt,
+          }),
+          controller.signal,
+        );
+        mapped = mapOpenCodePermissionDecision(decision);
+        if (mapped) break;
+        const waitMs = Math.min(Math.max(1, pollIntervalMs), Math.max(1, deadlineAt - now()));
+        await raceWithAbort(sleep(waitMs), controller.signal);
+      }
+      reply = mapped;
+    } catch (error) {
+      reply = "reject";
+      log?.error?.(`acp permission decision: ${error?.message ?? error}`);
+      // The agent is about to be failed closed. Settle the durable hilos card
+      // too, on a bounded one-shot call — the run signal may already be gone.
+      if (handle) {
+        try {
+          await getPermissionDecision(handle, {
+            request,
+            deadlineAt,
+            failClosed: true,
+          });
+        } catch (settlementError) {
+          log?.error?.(
+            `acp permission settlement: ${settlementError?.message ?? settlementError}`,
+          );
+        }
+      }
+    }
+    const option = pickAcpPermissionOption(msg.params?.options, reply);
+    if (option && (reply !== "reject" || option.kind?.startsWith("reject"))) {
+      respond(msg.id, { outcome: { outcome: "selected", optionId: option.optionId } });
+    } else if (reply === "reject") {
+      // No recognizable reject option: cancel the ask at the protocol level.
+      respond(msg.id, { outcome: { outcome: "cancelled" } });
+    } else {
+      // An approval we cannot express in the agent's options must not become
+      // an implicit rejection card-side; the wire still gets a cancel.
+      log?.error?.("acp permission: no matching option for reply, cancelling");
+      respond(msg.id, { outcome: { outcome: "cancelled" } });
+    }
+  }
+
+  function handleUpdate(update) {
+    if (!isObject(update)) return;
+    const kind = update.sessionUpdate;
+    if (kind === "agent_message_chunk") {
+      const messageId = typeof update.messageId === "string" ? update.messageId : null;
+      if (currentMessageId !== null && messageId !== currentMessageId) flushMessage();
+      currentMessageId = messageId;
+      const text =
+        isObject(update.content) && typeof update.content.text === "string"
+          ? update.content.text
+          : "";
+      messageBuffer += text;
+      return;
+    }
+    // Thoughts, tool calls, usage, command lists: structurally received, not
+    // part of slice 1's transcript (parity with the HTTP runner's text mode).
+  }
+
+  function handleMessage(msg) {
+    if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+      const entry = pending.get(msg.id);
+      if (!entry) return;
+      pending.delete(msg.id);
+      if (msg.error) {
+        entry.reject(
+          new Error(
+            `ACP ${entry.method} failed: ${msg.error.message ?? JSON.stringify(msg.error)}`,
+          ),
+        );
+      } else {
+        entry.resolve(msg.result);
+      }
+      return;
+    }
+    if (msg.method === "session/update") {
+      if (isObject(msg.params) && msg.params.sessionId === sessionId) {
+        handleUpdate(msg.params.update);
+      }
+      return;
+    }
+    if (msg.method === "session/request_permission" && msg.id !== undefined) {
+      const task = settlePermission(msg).finally(() => permissionTasks.delete(task));
+      permissionTasks.add(task);
+      return;
+    }
+    if (msg.id !== undefined && msg.method) {
+      // fs/terminal requests should never arrive (capabilities declared off);
+      // refuse anything unexpected instead of guessing.
+      respond(msg.id, undefined, {
+        code: -32601,
+        message: `hilos does not implement ${msg.method}`,
+      });
+    }
+  }
+
+  try {
+    child = spawnImpl(cmd, acpArgs, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+    const spawned = new Promise((resolve, reject) => {
+      child.once("spawn", resolve);
+      child.once("error", reject);
+    });
+    child.once("exit", (code) => {
+      failPending(`ACP agent exited (${code ?? "signal"}) before replying`);
+    });
+    const parser = createNdjsonParser();
+    child.stdout.on("data", (chunk) => {
+      for (const msg of parser.push(chunk)) {
+        try {
+          handleMessage(msg);
+        } catch (error) {
+          log?.error?.(`acp frame handling: ${error?.message ?? error}`);
+        }
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+      if (stderr.length > MAX_LINE_BYTES) stderr = stderr.slice(-MAX_LINE_BYTES);
+    });
+    await raceWithAbort(spawned, controller.signal);
+
+    const init = await raceWithAbort(
+      rpc("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: {
+          fs: { readTextFile: false, writeTextFile: false },
+          terminal: false,
+        },
+      }),
+      controller.signal,
+    );
+    if (isObject(init) && init.protocolVersion !== undefined && init.protocolVersion !== PROTOCOL_VERSION) {
+      throw new Error(`ACP agent speaks protocol ${init.protocolVersion}, expected ${PROTOCOL_VERSION}`);
+    }
+
+    const session = await raceWithAbort(
+      rpc("session/new", { cwd, mcpServers }),
+      controller.signal,
+    );
+    sessionId = isObject(session) && typeof session.sessionId === "string" ? session.sessionId : null;
+    if (!sessionId) throw new Error("ACP agent created a session without an id");
+
+    const turn = await raceWithAbort(
+      rpc("session/prompt", {
+        sessionId,
+        prompt: [{ type: "text", text: String(prompt ?? "") }],
+      }),
+      controller.signal,
+    );
+    flushMessage();
+    // Every in-flight permission has been answered or is being failed closed by
+    // its own error path; give those settlements a bounded chance to finish.
+    await Promise.allSettled([...permissionTasks]);
+
+    const stopReason = isObject(turn) && typeof turn.stopReason === "string" ? turn.stopReason : null;
+    const clean = stopReason === "end_turn" || stopReason == null;
+    return {
+      status: clean ? 0 : 1,
+      stdout: stdout.trimEnd(),
+      stderr: stderr.trimEnd(),
+      error: clean ? null : new Error(`ACP turn stopped: ${stopReason}`),
+      sessionId,
+    };
+  } catch (error) {
+    flushMessage();
+    const aborted = abortKind === "cancelled";
+    const timedOut = abortKind === "timeout";
+    return {
+      status: null,
+      stdout: stdout.trimEnd(),
+      stderr: stderr.trimEnd(),
+      ...(aborted ? { aborted: true } : {}),
+      ...(sessionId ? { sessionId } : {}),
+      error:
+        error instanceof Error && !timedOut
+          ? error
+          : new Error(timedOut ? "ACP session timed out" : String(error)),
+    };
+  } finally {
+    if (timeout != null) clearTimer(timeout);
+    signal?.removeEventListener?.("abort", onParentAbort);
+    if (child && child.exitCode === null && !child.killed) {
+      // Ask for a graceful stop first (the agent may flush state), then kill.
+      if (sessionId) {
+        writeFrame({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+      }
+      try {
+        child.stdin.end();
+      } catch {
+        // Already gone.
+      }
+      const grace = setTimer(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // Already gone.
+        }
+      }, SHUTDOWN_GRACE_MS);
+      grace?.unref?.();
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // Already gone.
+      }
+    }
+    failPending("ACP session finished");
+  }
+}

package/src/agent-events.mjs

@@ -219,6 +219,15 @@ function parseCodexLine(line) {
  * `shellToolCall`, each with an `args` object), and a terminal `result` with
  * `is_error` + the full text in `result`. `thinking` deltas, the `user` echo,
  * and `tool_call` completions are deliberately not steps.
+ *
+ * LOCKSTEP (0574 phase 2 / 0749): `parseCursorCloudEvent` in
+ * lib/hosted-progress.ts is this function's CLOUD twin — same field knowledge,
+ * same restraint (`started` only, unknown tools skipped, never throws) — for
+ * Cursor's Cloud Agents SSE stream, whose event NAMES differ from this CLI
+ * stream-json (`tool_call` with a flat `name` + `args`, not `<kind>ToolCall`
+ * envelopes). Change one, look at the other. The cloud side's mappings are
+ * WIRE (unconfirmed) until a real cloud transcript is captured; the shapes
+ * below were captured live and are not.
  */
 function parseCursorLine(line) {
   const obj = tryParse(line);
@@ -548,3 +557,113 @@ export function summarizeSteps(events, limit = 8) {
   for (const ev of events || []) ring.push(ev);
   return ring.labels();
 }
+
+// ── Activity fold (0537/0750) ────────────────────────────────────────────────
+//
+// The step ring's richer sibling: structured feed rows the run card renders as
+// sentences that MUTATE IN PLACE. LOCKSTEP with the server's fold in
+// `lib/hosted-progress.ts` (the hosted lanes) — same tense rule (the sentence
+// is formatted at read time so "Editing lib/x.ts" flips to "Edited lib/x.ts"
+// once the next action starts), same aggregation (repeat edits count up, read
+// sweeps recede into one row), same loud failures. Change one, look at the
+// other. The server re-validates every row (sanitizeProgress), so this side
+// only has to be honest, not paranoid.
+
+const MAX_ACTIVITY = 30;
+
+/** @param {{kind: string, subject: string, status: string, n: number}} row */
+function activitySentence(row) {
+  const running = row.status === "running";
+  switch (row.kind) {
+    case "edit":
+      return `${running ? "Editing" : "Edited"} ${row.subject || "files"}`;
+    case "read":
+      if (row.n > 1) return `${running ? "Reading" : "Read"} ${row.n} files`;
+      return `${running ? "Reading" : "Read"} ${row.subject || "a file"}`;
+    case "run": {
+      const label = describeRun(row.subject);
+      return running ? label : label.replace(/^Running/, "Ran");
+    }
+    default:
+      return row.subject; // note/result carry their own sentence
+  }
+}
+
+/**
+ * A bounded fold of AgentEvents into activity rows. Starts are the only ground
+ * truth a CLI stream carries, so "done" is the sequential-execution inference:
+ * a new action starting settles the one in flight. `settle("failed")` is for a
+ * dying run — leaving "Editing…" forever is the dishonesty this feed exists to
+ * avoid. session/phase events are metadata, not rows (same as stepLabel).
+ * @param {number} [limit]
+ */
+export function createActivityFold(limit = MAX_ACTIVITY) {
+  /** @type {{kind: string, subject: string, status: string, n: number}[]} */
+  const rows = [];
+
+  function settle(as = "done") {
+    const last = rows[rows.length - 1];
+    if (last && last.status === "running") last.status = as;
+  }
+
+  function add(row) {
+    settle();
+    rows.push(row);
+    if (rows.length > limit) rows.shift();
+  }
+
+  /** @param {AgentEvent} event */
+  function push(event) {
+    if (!event || typeof event !== "object") return;
+    const last = rows[rows.length - 1];
+    switch (event.t) {
+      case "edit":
+        if (last && last.status === "running" && last.kind === "edit" && last.subject === event.path) {
+          last.n += 1;
+          return;
+        }
+        add({ kind: "edit", subject: event.path || "", status: "running", n: 1 });
+        return;
+      case "read":
+        if (last && last.status === "running" && last.kind === "read") {
+          last.n += 1;
+          return;
+        }
+        add({ kind: "read", subject: event.path || "", status: "running", n: 1 });
+        return;
+      case "run":
+        add({ kind: "run", subject: event.cmd || "", status: "running", n: 1 });
+        return;
+      case "note":
+        if (!event.text) return;
+        add({ kind: "note", subject: event.text, status: "done", n: 1 });
+        return;
+      case "result":
+        add({
+          kind: "result",
+          subject: event.ok ? "Done" : (event.summary && event.summary.trim()) || "Finished with errors",
+          status: event.ok ? "done" : "failed",
+          n: 1,
+        });
+        return;
+      default:
+        return; // session / phase / unknown — metadata, not activity
+    }
+  }
+
+  /** The wire rows, sentences formatted for the CURRENT statuses, sanitized.
+   *  @returns {{kind: string, text: string, status: string, n?: number}[]} */
+  function list() {
+    const out = [];
+    for (const row of rows) {
+      const text = sanitizeText(activitySentence(row));
+      if (!text) continue;
+      const wire = { kind: row.kind, text, status: row.status };
+      if (row.kind === "edit" && row.n > 1) wire.n = row.n;
+      out.push(wire);
+    }
+    return out;
+  }
+
+  return { push, settle, list };
+}