@yannelli/paseo-linear-plugin 1.0.0 → 1.1.0-beta.0

package/shared/shell-activity.ts

@@ -0,0 +1,309 @@
+import { lexShell, splitCommands, type Word } from "./shell-lexer";
+
+// Agents that read through the shell (`cat`, `sed -n`, `grep`, `ls`) touch files without a Read
+// tool call. This finds those files in a command, so Linear Live can show them. It only knows
+// common read, search, and list commands; anything else yields no paths.
+
+export interface ExploredDir {
+  /** Repo-relative folder with a trailing slash; "" is the root. */
+  path: string;
+  /** Searched recursively, not only listed. */
+  deep: boolean;
+}
+
+export interface ShellWrite {
+  path: string;
+  mode: "write" | "edit";
+}
+
+export interface ShellActivity {
+  reads: string[];
+  writes: ShellWrite[];
+  dirs: ExploredDir[];
+  pattern: string | null;
+  summary: string;
+}
+
+const KEYWORDS = new Set(["do", "then", "else", "elif", "if", "while", "until", "!", "{", "time"]);
+const WRAPPERS = new Set(["sudo", "command", "nice", "nohup", "env", "builtin", "exec"]);
+// Not named in a summary: shell setup, and filters that only shape another command's output.
+const NO_VERB = new Set(
+  "cd echo printf true false sleep export set : head tail sort uniq wc cut tr grep egrep cat xargs"
+    .split(" "),
+);
+const SUBCOMMANDS = new Set(["git", "npm", "npx", "bun", "bunx", "pnpm", "yarn", "gh", "linear"]);
+const LONG_VALUES = new Set([
+  "glob", "type", "type-not", "max-count", "context", "after-context", "before-context", "regexp",
+  "file", "max-depth", "sort", "include", "exclude", "exclude-dir", "color", "colors", "encoding",
+]);
+const READERS: Record<string, string> = {
+  cat: "", nl: "bdfhilnsvw", less: "", more: "", bat: "rlHm", tac: "", wc: "", file: "",
+  stat: "c", head: "nc", tail: "ncs", sort: "ktoS", uniq: "fs", cut: "dfcb", diff: "", cmp: "",
+  column: "st", xxd: "lsc", od: "", strings: "n", md5sum: "", sha256sum: "",
+};
+const SEARCHERS: Record<string, string> = {
+  grep: "efABCmd", egrep: "efABCmd", fgrep: "efABCmd", rg: "efABCmgtTMdj", ag: "ABCmG",
+  ack: "ABCm",
+};
+
+interface Parsed {
+  options: Set<string>;
+  values: Map<string, string[]>;
+  positionals: Word[];
+  /** Positionals after `--`. */
+  dashed: Word[];
+}
+
+function parseArgs(args: readonly Word[], shortValues: string): Parsed {
+  const parsed: Parsed = { options: new Set(), values: new Map(), positionals: [], dashed: [] };
+  const value = (name: string, text: string | undefined) => {
+    if (text !== undefined) parsed.values.set(name, [...(parsed.values.get(name) ?? []), text]);
+  };
+  let ended = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] as Word;
+    const { text } = arg;
+    if (ended) parsed.dashed.push(arg);
+    else if (text === "--") ended = true;
+    else if (text === "-" || !text.startsWith("-") || arg.dynamic) parsed.positionals.push(arg);
+    else if (text.startsWith("--")) {
+      const [name = "", inline] = text.slice(2).split(/=(.*)/s);
+      parsed.options.add(name);
+      if (inline !== undefined) value(name, inline);
+      else if (LONG_VALUES.has(name)) value(name, args[++index]?.text);
+    } else {
+      for (let at = 1; at < text.length; at += 1) {
+        const flag = text[at] as string;
+        parsed.options.add(flag);
+        if (!shortValues.includes(flag)) continue;
+        value(flag, at + 1 < text.length ? text.slice(at + 1) : args[++index]?.text);
+        break;
+      }
+    }
+  }
+  return parsed;
+}
+
+const MAX_PATTERN = 28;
+
+function hasExtension(path: string): boolean {
+  return /[^./][^/]*\.[A-Za-z0-9]+$/.test(path.split("/").pop() ?? "");
+}
+
+function shortName(path: string): string {
+  const parts = path.replace(/\/$/, "").split("/");
+  return path.endsWith("/") ? parts.slice(-2).join("/") || "the repository" : (parts.pop() ?? path);
+}
+
+function names(paths: readonly string[]): string {
+  const shown = [...new Set(paths.map(shortName))];
+  const extra = shown.length - 2;
+  return `${shown.slice(0, 2).join(", ")}${extra > 0 ? ` +${extra}` : ""}`;
+}
+
+export function parseShell(command: string, cwd: string, start = ""): ShellActivity {
+  const root = cwd.replace(/\/+$/, "");
+  const reads = new Set<string>();
+  const writes = new Map<string, ShellWrite["mode"]>();
+  const dirs = new Map<string, boolean>();
+  const verbs: string[] = [];
+  const env = new Map<string, Word[]>();
+  let pattern: string | null = null;
+  let base: string | null = start;
+
+  const resolve = (raw: string, from: string | null): string | null => {
+    let joined: string;
+    if (raw.startsWith("/")) {
+      if (raw === root || raw === `${root}/`) return "";
+      if (!raw.startsWith(`${root}/`)) return null;
+      joined = raw.slice(root.length + 1);
+    } else if (from === null || raw.startsWith("~")) return null;
+    else joined = from ? `${from}/${raw}` : raw;
+    const parts: string[] = [];
+    for (const part of joined.split("/")) {
+      if (!part || part === ".") continue;
+      if (part !== "..") parts.push(part);
+      else if (parts.pop() === undefined) return null;
+    }
+    return parts.join("/");
+  };
+  const expand = (word: Word): Word[] => {
+    if (!word.dynamic) return [word];
+    const name = /^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/.exec(word.text)?.[1];
+    return name ? (env.get(name) ?? []) : [];
+  };
+  const addDir = (path: string | null, deep: boolean) => {
+    if (path === null) return;
+    const dir = path === "" ? "" : `${path}/`;
+    dirs.set(dir, deep || (dirs.get(dir) ?? false));
+  };
+  // A glob reads from its folder; a plain word is a file, or a folder when `asDir` says so.
+  const target = (word: Word, from: string | null, asDir: (path: string) => boolean, deep = false) => {
+    if (word.globAt >= 0) {
+      const prefix = word.text.slice(0, word.globAt);
+      addDir(resolve(prefix.slice(0, prefix.lastIndexOf("/") + 1), from), deep);
+      return;
+    }
+    const path = resolve(word.text, from);
+    if (path === null) return;
+    if (path === "" || asDir(word.text)) addDir(path, deep);
+    else reads.add(path);
+  };
+  const never = () => false;
+  const noExtension = (text: string) => text.endsWith("/") || !hasExtension(text);
+
+  for (const simple of splitCommands(lexShell(command))) {
+    let words = simple.words;
+    while (words[0] && (KEYWORDS.has(words[0].text) || /^[A-Za-z_]\w*=/.test(words[0].text))) {
+      words = words.slice(1);
+    }
+    while (words[0] && WRAPPERS.has(words[0].text)) words = words.slice(1);
+    const first = words[0]?.text;
+    if (first === "for" && words[2]?.text === "in" && words[1]) {
+      env.set(words[1].text, words.slice(3).flatMap(expand));
+      continue;
+    }
+    const args = words.slice(1).flatMap(expand);
+    for (const { operator, target: file } of simple.redirects) {
+      if (file.dynamic || file.text.startsWith("/dev/")) continue;
+      const path = resolve(file.text, base);
+      if (path === null || path === "") continue;
+      if (operator === "<") reads.add(path);
+      else if (operator === ">" || operator === ">>") writes.set(path, operator === ">" ? "write" : "edit");
+    }
+    if (!first || first === "done" || first === "fi") continue;
+    let from = base;
+    let name = first.split("/").pop() ?? first;
+    let rest = args;
+    if (name === "cd" || name === "pushd") {
+      base = args[0] ? resolve(args[0].text, base) : base;
+      continue;
+    }
+    if (name === "git") {
+      const global = parseArgs(args, "Cc");
+      const at = args.findIndex((arg) => arg === global.positionals[0]);
+      for (const dir of global.values.get("C") ?? []) from = resolve(dir, base);
+      name = `git ${global.positionals[0]?.text ?? ""}`.trim();
+      rest = at < 0 ? [] : args.slice(at + 1);
+    }
+    if (!NO_VERB.has(name)) {
+      const sub = SUBCOMMANDS.has(name) ? args.find((arg) => !arg.text.startsWith("-")) : undefined;
+      verbs.push(sub ? `${name} ${sub.text}` : name);
+    }
+    if (name in READERS) {
+      for (const word of parseArgs(rest, READERS[name] ?? "").positionals) target(word, from, never);
+    } else if (name === "sed" || name === "awk" || name === "gawk" || name === "jq") {
+      const parsed = parseArgs(rest, name === "sed" ? "efl" : name === "jq" ? "" : "Ffv");
+      const scripted = parsed.options.has("e") || parsed.options.has("f");
+      const files = parsed.positionals.slice(scripted && name !== "jq" ? 0 : 1);
+      const inPlace = name === "sed" && parsed.options.has("i");
+      for (const word of files) {
+        if (/^\w+=/.test(word.text)) continue;
+        const path = resolve(word.text, from);
+        if (inPlace && path) writes.set(path, "edit");
+        else target(word, from, never);
+      }
+    } else if (name in SEARCHERS || name === "git grep") {
+      const parsed = parseArgs(rest, SEARCHERS[name] ?? "efABCm");
+      const listing = parsed.options.has("files");
+      const given = parsed.values.get("e")?.[0] ?? parsed.values.get("regexp")?.[0];
+      const explicit = given !== undefined || parsed.options.has("f") || listing;
+      const paths = [...parsed.positionals.slice(explicit ? 0 : 1), ...parsed.dashed];
+      // A grep in a pipe without files or -r filters output and searches nothing.
+      const recursive = parsed.options.has("r") || parsed.options.has("R");
+      const filter = /^[ef]?grep$/.test(name) && !recursive && paths.length === 0;
+      if (filter) continue;
+      if (!listing) pattern ??= given ?? parsed.positionals[0]?.text ?? null;
+      if (paths.length === 0) addDir(from, true);
+      for (const word of paths) target(word, from, noExtension, true);
+    } else if (name === "ls" || name === "tree" || name === "find" || name === "fd") {
+      const parsed = parseArgs(rest, name === "tree" ? "LPIo" : name === "fd" ? "etdE" : "");
+      const deep = name !== "ls" || parsed.options.has("R");
+      const expression = rest.findIndex((word) => /^[-(!]/.test(word.text));
+      let paths = parsed.positionals;
+      // find takes folders first and then an expression whose words are not paths.
+      if (name === "find") paths = expression < 0 ? rest : rest.slice(0, expression);
+      if (name === "fd") paths = paths.slice(1);
+      if (paths.length === 0) addDir(from, deep);
+      for (const word of paths) target(word, from, (text) => name !== "ls" || noExtension(text), deep);
+    } else if (/^git (show|diff|log|blame|annotate)$/.test(name)) {
+      const parsed = parseArgs(rest, "nSGL");
+      for (const word of parsed.positionals) {
+        const path = word.text.includes(":") ? word.text.slice(word.text.indexOf(":") + 1) : null;
+        if (path) target({ ...word, text: path }, from, never);
+      }
+      for (const word of parsed.dashed) target(word, from, noExtension);
+      if (name === "git blame" && parsed.dashed.length === 0) {
+        const last = parsed.positionals.at(-1);
+        if (last) target(last, from, never);
+      }
+    } else if (name === "git ls-files") {
+      const parsed = parseArgs(rest, "x");
+      const paths = [...parsed.positionals, ...parsed.dashed];
+      if (paths.length === 0) addDir(from, true);
+      for (const word of paths) target(word, from, noExtension, true);
+    } else if (name === "tee" || name === "touch") {
+      for (const word of parseArgs(rest, "").positionals) {
+        const path = resolve(word.text, from);
+        if (path) writes.set(path, name === "tee" && rest.some((w) => w.text === "-a") ? "edit" : "write");
+      }
+    } else if (name === "cp" || name === "mv") {
+      const files = parseArgs(rest, "St").positionals;
+      const destination = files.pop();
+      for (const word of files) if (name === "cp") target(word, from, never);
+      const path = destination ? resolve(destination.text, from) : null;
+      if (path && hasExtension(path)) writes.set(path, "write");
+    }
+  }
+
+  const writeList = [...writes].map(([path, mode]) => ({ path, mode }));
+  const readList = [...reads].filter((path) => !writes.has(path));
+  const dirList = [...dirs].map(([path, deep]) => ({ path, deep }));
+  const parts: string[] = [];
+  if (writeList.length > 0) parts.push(`wrote ${names(writeList.map((write) => write.path))}`);
+  if (readList.length > 0) parts.push(`read ${names(readList)}`);
+  if (pattern !== null) {
+    const scope = dirList.filter((dir) => dir.deep && dir.path !== "").map((dir) => dir.path);
+    const shown = pattern.replace(/\\\|/g, "|");
+    const short = shown.length > MAX_PATTERN ? `${shown.slice(0, MAX_PATTERN - 1)}…` : shown;
+    parts.push(`searched "${short}"${scope.length > 0 ? ` in ${names(scope)}` : ""}`);
+  } else if (parts.length === 0 && dirList.length > 0) {
+    parts.push(`listed ${names(dirList.map((dir) => dir.path || "./"))}`);
+  }
+  if (parts.length === 0 && verbs.length > 0) {
+    const shown = [...new Set(verbs)];
+    parts.push(`ran ${shown.slice(0, 2).join(", ")}${shown.length > 2 ? ` +${shown.length - 2}` : ""}`);
+  }
+  const summary = parts.slice(0, 2).join(", ") || "Ran a command";
+  return {
+    reads: readList,
+    writes: writeList,
+    dirs: dirList,
+    pattern,
+    summary: summary.charAt(0).toUpperCase() + summary.slice(1),
+  };
+}
+
+const MAX_CACHED = 500;
+const cache = new Map<string, ShellActivity>();
+
+/** parseShell with a cache: the panel derives activity again on every timeline update. */
+export function shellActivity(command: string, cwd: string, start = ""): ShellActivity {
+  const key = `${cwd}\u0000${start}\u0000${command}`;
+  const hit = cache.get(key);
+  if (hit) return hit;
+  const parsed = parseShell(command, cwd, start);
+  if (cache.size >= MAX_CACHED) cache.delete(cache.keys().next().value as string);
+  cache.set(key, parsed);
+  return parsed;
+}
+
+/** The command as shown in the feed: one line, without a leading `cd` into the agent folder. */
+export function displayCommand(command: string, cwd: string): string {
+  const root = cwd.replace(/\/+$/, "");
+  const firstLine = command.split("\n")[0] ?? command;
+  return firstLine
+    .replace(new RegExp(`^cd\\s+['"]?${root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/?['"]?\\s*&&\\s*`), "")
+    .replaceAll(`${root}/`, "")
+    .trim();
+}

package/shared/shell-lexer.ts

@@ -0,0 +1,180 @@
+// Splits a shell command into words, operators, and redirects, the way the shell would
+// before running it. Expansions are kept as text and marked, since their values are unknown.
+
+export interface Word {
+  kind: "word";
+  text: string;
+  /** Contains `$` or backtick expansion, so the shell may change the text. */
+  dynamic: boolean;
+  /** Index of the first unquoted glob character, or -1. */
+  globAt: number;
+}
+export type Token = Word | { kind: "op"; text: string } | { kind: "redirect"; text: string };
+
+function readExpansion(input: string, start: number): number {
+  const open = input[start + 1];
+  if (input[start] === "`") {
+    const end = input.indexOf("`", start + 1);
+    return end < 0 ? input.length : end + 1;
+  }
+  if (open === "(" || open === "{") {
+    const close = open === "(" ? ")" : "}";
+    let depth = 0;
+    for (let index = start + 1; index < input.length; index += 1) {
+      if (input[index] === open) depth += 1;
+      else if (input[index] === close && --depth === 0) return index + 1;
+    }
+    return input.length;
+  }
+  let index = start + 1;
+  while (index < input.length && /[A-Za-z0-9_@*#?!-]/.test(input[index] as string)) index += 1;
+  return index === start + 1 ? start + 1 : index;
+}
+
+/** Splits a command into words, operators, and redirects. Heredoc bodies are skipped. */
+export function lexShell(input: string): Token[] {
+  const tokens: Token[] = [];
+  const heredocs: { delimiter: string; strip: boolean }[] = [];
+  let text: string | null = null;
+  let dynamic = false;
+  let globAt = -1;
+  let index = 0;
+  const add = (value: string) => {
+    text = (text ?? "") + value;
+  };
+  const flush = () => {
+    if (text !== null) tokens.push({ kind: "word", text, dynamic, globAt });
+    text = null;
+    dynamic = false;
+    globAt = -1;
+  };
+  const skipHeredocs = () => {
+    for (const { delimiter, strip } of heredocs.splice(0)) {
+      while (index < input.length) {
+        const end = input.indexOf("\n", index) < 0 ? input.length : input.indexOf("\n", index);
+        const line = input.slice(index, end);
+        index = end + 1;
+        if ((strip ? line.replace(/^\t+/, "") : line) === delimiter) break;
+      }
+    }
+  };
+  while (index < input.length) {
+    const char = input[index] as string;
+    const next = input[index + 1] ?? "";
+    if (char === "\n") {
+      flush();
+      tokens.push({ kind: "op", text: ";" });
+      index += 1;
+      skipHeredocs();
+    } else if (char === " " || char === "\t" || char === "\r") {
+      flush();
+      index += 1;
+    } else if (char === "#" && text === null) {
+      while (index < input.length && input[index] !== "\n") index += 1;
+    } else if (char === "\\") {
+      if (next !== "\n") add(next);
+      index += 2;
+    } else if (char === "'") {
+      const end = input.indexOf("'", index + 1);
+      const stop = end < 0 ? input.length : end;
+      add(input.slice(index + 1, stop));
+      index = stop + 1;
+    } else if (char === '"') {
+      let value = "";
+      index += 1;
+      while (index < input.length && input[index] !== '"') {
+        const inner = input[index] as string;
+        if (inner === "\\" && '"\\$`'.includes(input[index + 1] ?? "")) {
+          value += input[index + 1];
+          index += 2;
+          continue;
+        }
+        if (inner === "$" || inner === "`") dynamic = true;
+        value += inner;
+        index += 1;
+      }
+      add(value);
+      index += 1;
+    } else if (char === "$" || char === "`") {
+      const end = readExpansion(input, index);
+      dynamic = true;
+      add(input.slice(index, end));
+      index = end;
+    } else if ((char === "&" || char === "|") && next === char) {
+      flush();
+      tokens.push({ kind: "op", text: char + char });
+      index += 2;
+    } else if (char === "&" && next === ">") {
+      flush();
+      tokens.push({ kind: "redirect", text: ">" });
+      index += input[index + 2] === ">" ? 3 : 2;
+    } else if (char === "|" || char === ";" || char === "&" || char === "(" || char === ")") {
+      flush();
+      tokens.push({ kind: "op", text: char === "|" ? "|" : ";" });
+      index += char === "|" && next === "&" ? 2 : 1;
+    } else if (char === ">" || char === "<") {
+      // A bare number before the arrow is a file descriptor, as in `2>/dev/null`.
+      if (text !== null && /^\d+$/.test(text) && !dynamic) text = null;
+      else flush();
+      if (char === "<" && next === "<" && input[index + 2] !== "<") {
+        index += 2;
+        const strip = input[index] === "-";
+        if (strip) index += 1;
+        while (input[index] === " ") index += 1;
+        let delimiter = "";
+        while (index < input.length && !/[\s;&|<>]/.test(input[index] as string)) {
+          if (!`'"\\`.includes(input[index] as string)) delimiter += input[index];
+          index += 1;
+        }
+        heredocs.push({ delimiter, strip });
+        continue;
+      }
+      let operator = char;
+      index += 1;
+      while (input[index] === "<" || (char === ">" && input[index] === ">")) {
+        operator += input[index];
+        index += 1;
+      }
+      if (input[index] === "&") {
+        index += 1;
+        while (/[0-9-]/.test(input[index] ?? "")) index += 1;
+        continue;
+      }
+      if (input[index] === "|") index += 1;
+      tokens.push({ kind: "redirect", text: operator });
+    } else {
+      if (globAt < 0 && (char === "*" || char === "?" || char === "[")) globAt = (text ?? "").length;
+      add(char);
+      index += 1;
+    }
+  }
+  flush();
+  return tokens;
+}
+
+export interface SimpleCommand {
+  words: Word[];
+  redirects: { operator: string; target: Word }[];
+}
+
+export function splitCommands(tokens: readonly Token[]): SimpleCommand[] {
+  const list: SimpleCommand[] = [];
+  let current: SimpleCommand = { words: [], redirects: [] };
+  let pending: string | null = null;
+  for (const token of tokens) {
+    if (token.kind === "op") {
+      pending = null;
+      if (current.words.length > 0 || current.redirects.length > 0) list.push(current);
+      current = { words: [], redirects: [] };
+    } else if (token.kind === "redirect") {
+      pending = token.text;
+    } else if (pending) {
+      current.redirects.push({ operator: pending, target: token });
+      pending = null;
+    } else {
+      current.words.push(token);
+    }
+  }
+  if (current.words.length > 0 || current.redirects.length > 0) list.push(current);
+  return list;
+}

package/shared/subagents.ts

@@ -0,0 +1,106 @@
+import { pathsIn } from "./live";
+
+// Subagents that run inside the provider (Claude's Agent tool, Codex sub-agents) report only
+// a type, a description, and while the launch streams, the prompt. Their own file reads never
+// reach the parent timeline, so the files their prompt names are the best clue to their place.
+
+export type SubagentStatus = "running" | "completed" | "failed" | "canceled";
+
+export interface SubagentRun {
+  /** Type and description, the same for the launch call and the subagent item. */
+  key: string;
+  type: string;
+  description: string;
+  status: SubagentStatus;
+  /** Repo-relative files and folders its prompt or description names. */
+  targets: string[];
+  order: number;
+}
+
+export interface SubagentSignal {
+  key: string;
+  type: string;
+  description: string;
+  /** Null for the launch call: it completes as soon as the subagent starts in the background. */
+  status: SubagentStatus | null;
+  targets: string[];
+}
+
+type ToolItem = Readonly<Record<string, unknown>>;
+
+const LAUNCHERS = new Set(["Agent", "Task"]);
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function statusOf(value: unknown): SubagentStatus {
+  return value === "failed" || value === "canceled" || value === "completed" ? value : "running";
+}
+
+/** A call that starts, reports on, or waits for a subagent. */
+export function isSubagentCall(item: ToolItem): boolean {
+  const detail = (item.detail ?? {}) as Record<string, unknown>;
+  return detail.type === "sub_agent" || (LAUNCHERS.has(text(item.name)) && detail.type === "unknown");
+}
+
+/** The subagent a tool call starts or reports on, or null for any other call or a wait. */
+export function subagentOf(
+  item: ToolItem,
+  resolve: (path: string) => string | null,
+): SubagentSignal | null {
+  const detail = (item.detail ?? {}) as Record<string, unknown>;
+  let type: string;
+  let description: string;
+  let prompt = "";
+  let status: SubagentStatus | null;
+  if (detail.type === "sub_agent") {
+    type = text(detail.subAgentType);
+    description = text(detail.description);
+    status = statusOf(item.status);
+    const actions = Array.isArray(detail.actions) ? detail.actions : [];
+    prompt = actions.map((action) => text((action as { summary?: unknown }).summary)).join("\n");
+  } else if (LAUNCHERS.has(text(item.name)) && detail.type === "unknown") {
+    const input = (detail.input ?? {}) as Record<string, unknown>;
+    type = text(input.subagent_type);
+    description = text(input.description);
+    prompt = text(input.prompt);
+    status = null;
+  } else {
+    return null;
+  }
+  if (!description && !type) return null;
+  // Waiting for background agents shows as one more Agent call; it starts nothing.
+  if (/^wait(ing)? (for|on)\b/i.test(description)) return null;
+  const named = pathsIn(`${description}\n${prompt}`)
+    .map(resolve)
+    .filter((path): path is string => path !== null && path !== "");
+  return {
+    key: `${type}\u0000${description}`,
+    type: type || "Subagent",
+    description,
+    status,
+    targets: [...new Set(named)],
+  };
+}
+
+/** Folds launch and report calls into one run per subagent, in launch order. */
+export function mergeSubagent(
+  runs: Map<string, SubagentRun>,
+  signal: SubagentSignal,
+  order: number,
+): SubagentRun {
+  const known = runs.get(signal.key);
+  const run: SubagentRun = known ?? {
+    key: signal.key,
+    type: signal.type,
+    description: signal.description,
+    status: "running",
+    targets: [],
+    order,
+  };
+  if (signal.status) run.status = signal.status;
+  run.targets = [...new Set([...run.targets, ...signal.targets])];
+  runs.set(signal.key, run);
+  return run;
+}