@famonfa/mono 0.0.0-stage → 0.3.0

package/src/refresh.mjs

@@ -0,0 +1,124 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import * as store from "./store.mjs";
+
+const HOME = os.homedir();
+const RUN_DIR = path.join(os.tmpdir(), "ws-refresh");
+const JOBS_DIR = path.join(store.DATA_DIR, ".jobs");
+const PATH = [path.join(HOME, ".local/bin"), path.join(HOME, ".npm-global/bin"), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", process.env.PATH].join(":");
+
+/**
+ * Read-mostly allowlist: the headless session can inspect PRs and load workspace data through `ws`,
+ * but cannot change repos. acceptEdits limits file writes to its own temp working directory.
+ */
+const ALLOWED_TOOLS = [
+  "Bash(ws:*)",
+  "Bash(gh pr view:*)",
+  "Bash(gh pr checks:*)",
+  "Bash(gh pr diff:*)",
+  "Bash(git log:*)",
+  "Bash(git diff:*)",
+  "Bash(git show:*)",
+  "Read",
+  "Glob",
+  "Grep",
+  "Skill",
+];
+
+function prompt(task, since) {
+  return [
+    `Actualizá la tarea ${task.id} ("${task.title}") de Mono usando el skill workspace en modo actualización.`,
+    `1. Corré \`ws show ${task.id}\` y \`ws get ${task.id} <board>\` para ver cada board; reusá los ids de nodos existentes.`,
+    `2. La fuente principal es lo que hicieron los agentes: corré \`ws sessions ${task.id}${since ? ` --since ${since}` : ""}\` para ver la actividad reciente de las sesiones y subagentes vinculados.`,
+    "3. Actualizá sobre todo el board de testeo con resultados reales que aparezcan ahí (pass/fail solo con evidencia; lo demás queda todo). Si aparecen bugs o hallazgos nuevos, agregalos como notas o tarjetas con status risk. Actualizá estado, TL;DR o resumen solo si cambiaron de verdad.",
+    "4. Board `ui`: corré `gh pr diff` de los PRs de la tarea. Si el diff toca archivos de UI (.tsx, .css, .css.ts, pantallas/componentes) y la tarea NO tiene un board `ui`, crealo (layout lanes, una lane por pantalla o estado). Usá imágenes ya existentes en los assets de la tarea (`ws show`) como nodos image; si no hay capturas, describí cada pantalla/estado con nodos card (new/changed) a partir del diff e indicá que faltan capturas. Si el board `ui` ya existe, solo actualizalo con --patch. Si el diff no toca UI, no lo crees.",
+    "5. Escribí los JSON en el directorio actual. Los boards existentes cargalos SIEMPRE con `ws board <tarea> <board> <archivo> --patch` (agrega/actualiza, nunca borra nodos existentes; mandá solo los nodos nuevos o cambiados); un board nuevo se crea sin --patch. No toques repos, no publiques nada en GitHub ni en ningún otro servicio.",
+    "6. Terminá con 2 líneas: qué cambiaste y qué requiere atención.",
+  ].join("\n");
+}
+
+const jobFile = (taskId) => (store.assertSafe(taskId), path.join(JOBS_DIR, `${taskId}.json`));
+
+function readJob(taskId) {
+  try {
+    return JSON.parse(fs.readFileSync(jobFile(taskId), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJob(job) {
+  fs.mkdirSync(JOBS_DIR, { recursive: true });
+  fs.writeFileSync(jobFile(job.taskId), JSON.stringify(job, null, 2));
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const tail = (file) => {
+  try {
+    return fs.readFileSync(file, "utf8").slice(-4000);
+  } catch {
+    return "";
+  }
+};
+
+/**
+ * Job state lives on disk (pid, log, exit-code file) so it survives dev-server restarts,
+ * which happen whenever a server module changes or the launchd service restarts.
+ */
+function resolveJob(job) {
+  if (job.status !== "running") return job;
+  if (fs.existsSync(job.exitFile)) {
+    const code = Number(fs.readFileSync(job.exitFile, "utf8").trim());
+    const finished = { ...job, status: code === 0 ? "done" : "failed", exitCode: code, finishedAt: fs.statSync(job.exitFile).mtime.toISOString() };
+    writeJob(finished);
+    if (code === 0) store.saveTask(job.taskId, { refreshedAt: job.startedAt });
+    return finished;
+  }
+  if (!isAlive(job.pid)) {
+    const lost = { ...job, status: "failed", exitCode: null, finishedAt: new Date().toISOString() };
+    writeJob(lost);
+    return lost;
+  }
+  return job;
+}
+
+export function startRefresh(taskId) {
+  const task = store.getTask(taskId);
+  if (!task) throw new Error(`No existe la tarea ${taskId}`);
+  const current = readJob(taskId);
+  if (current && resolveJob(current).status === "running") return refreshStatus(taskId);
+
+  const cwd = path.join(RUN_DIR, `${taskId}-${Date.now()}`);
+  fs.mkdirSync(cwd, { recursive: true });
+  const logFile = path.join(cwd, "refresh.log");
+  const exitFile = path.join(cwd, "exit-code");
+  const log = fs.openSync(logFile, "a");
+  const args = ["-p", prompt(task, task.refreshedAt), "--permission-mode", "acceptEdits", "--allowedTools", ...ALLOWED_TOOLS];
+  const child = spawn("/bin/sh", ["-c", 'claude "$@"; echo $? > "$0"', exitFile, ...args], {
+    cwd,
+    env: { ...process.env, PATH },
+    stdio: ["ignore", log, log],
+    detached: true,
+  });
+  child.unref();
+  const job = { taskId, status: "running", startedAt: new Date().toISOString(), pid: child.pid, cwd, logFile, exitFile };
+  writeJob(job);
+  return refreshStatus(taskId);
+}
+
+export function refreshStatus(taskId) {
+  const job = readJob(taskId);
+  if (!job) return { status: "never" };
+  const resolved = resolveJob(job);
+  return { status: resolved.status, startedAt: resolved.startedAt, finishedAt: resolved.finishedAt, exitCode: resolved.exitCode, output: tail(resolved.logFile) };
+}

package/src/remote.mjs

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import WebSocket from "ws";
+
+import { CONFIG_DIR } from "./paths.mjs";
+
+export { CONFIG_DIR };
+export const REMOTE_FILE = path.join(CONFIG_DIR, "remote.json");
+
+export function readRemote() {
+  try {
+    return JSON.parse(fs.readFileSync(REMOTE_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeRemote(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  if (config) fs.writeFileSync(REMOTE_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+  else fs.rmSync(REMOTE_FILE, { force: true });
+}
+
+/** Status the relay connection publishes for `mono status`. */
+export const STATUS_FILE = path.join(CONFIG_DIR, "remote-status.json");
+
+export function remoteStatus() {
+  try {
+    return JSON.parse(fs.readFileSync(STATUS_FILE, "utf8"));
+  } catch {
+    return { state: "off" };
+  }
+}
+
+/**
+ * Keeps an outbound WebSocket to the relay (`mono connect`) so the phone or any browser can use this
+ * machine without opening ports. The relay sends HTTP requests over the socket; they are replayed
+ * against the local server as if they came from localhost, so the API's own checks still apply.
+ * Server events are pushed up as SSE frames for the relay to fan out.
+ */
+export function startRemote({ port }) {
+  let socket = null;
+  let retry = 1000;
+  let config = null;
+
+  const writeStatus = (status) => {
+    try {
+      fs.mkdirSync(CONFIG_DIR, { recursive: true });
+      fs.writeFileSync(STATUS_FILE, JSON.stringify({ ...status, relay: config?.relay ?? null, at: new Date().toISOString() }));
+    } catch {}
+  };
+
+  function connect() {
+    config = readRemote();
+    if (!config?.relay || !config?.token) return writeStatus({ state: "off" });
+    const url = new URL("/_mono/host", config.relay);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    const ws = new WebSocket(url, { maxPayload: 64 * 1024 * 1024 });
+    socket = ws;
+    let alive = true;
+    const heartbeat = setInterval(() => {
+      if (!alive) return ws.terminate();
+      alive = false;
+      ws.ping();
+    }, 30_000);
+    ws.on("pong", () => (alive = true));
+    ws.on("open", () => ws.send(JSON.stringify({ type: "hello", token: config.token, name: config.name ?? os.hostname() })));
+    ws.on("message", (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw);
+      } catch {
+        return;
+      }
+      if (msg.type === "welcome") {
+        retry = 1000;
+        console.log(`Mono conectado al relay ${config.relay} como ${msg.email}`);
+        writeStatus({ state: "connected", email: msg.email, hostId: msg.hostId });
+      }
+      if (msg.type === "rejected") {
+        console.error(`El relay rechazó esta máquina: ${msg.reason}`);
+        writeStatus({ state: "rejected", reason: msg.reason });
+        retry = 5 * 60_000;
+      }
+      if (msg.type === "req") proxy(ws, msg, port);
+    });
+    ws.on("error", (error) => writeStatus({ state: "error", reason: error.message }));
+    ws.on("close", () => {
+      clearInterval(heartbeat);
+      if (socket !== ws) return;
+      socket = null;
+      setTimeout(connect, retry);
+      retry = Math.min(retry * 2, 5 * 60_000);
+    });
+  }
+
+  // `mono connect` / `mono disconnect` rewrite the config file; pick it up without a restart.
+  fs.watchFile(REMOTE_FILE, { interval: 2000 }, () => {
+    const previous = socket;
+    socket = null;
+    previous?.close();
+    retry = 1000;
+    connect();
+  });
+  connect();
+
+  return {
+    forward(frame) {
+      if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ type: "event", frame }));
+    },
+  };
+}
+
+function proxy(ws, msg, port) {
+  const headers = { host: `localhost:${port}` };
+  if (msg.headers?.["content-type"]) headers["content-type"] = msg.headers["content-type"];
+  if (msg.method !== "GET" && msg.method !== "HEAD") headers.origin = `http://localhost:${port}`;
+  const body = msg.body ? Buffer.from(msg.body, "base64") : null;
+  if (body) headers["content-length"] = body.length;
+
+  const reply = (status, resHeaders, chunks) => {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify({ type: "res", id: msg.id, status, headers: resHeaders, body: Buffer.concat(chunks).toString("base64") }));
+  };
+
+  const req = http.request({ host: "127.0.0.1", port, method: msg.method, path: msg.path, headers }, (res) => {
+    const chunks = [];
+    res.on("data", (chunk) => chunks.push(chunk));
+    res.on("end", () => reply(res.statusCode, pick(res.headers, ["content-type", "cache-control"]), chunks));
+  });
+  req.on("error", (error) => reply(502, { "content-type": "application/json" }, [Buffer.from(JSON.stringify({ error: error.message }))]));
+  req.end(body ?? undefined);
+}
+
+const pick = (headers, keys) => Object.fromEntries(keys.filter((k) => headers[k]).map((k) => [k, headers[k]]));

package/src/sessions.mjs

@@ -0,0 +1,422 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
+
+const STALE_TURN_MS = 15 * 60_000;
+const RECENT_MS = 2 * 60 * 60_000;
+const TAIL_BYTES = 4 * 1024 * 1024;
+const MENTION = /\b(IME-\d{3,5}|PR-\d{2,5})\b/g;
+
+/** Incremental per-file state: only bytes appended since the last read are parsed. */
+const metaCache = new Map();
+
+function readFrom(file, start, end) {
+  const fd = fs.openSync(file, "r");
+  try {
+    const buf = Buffer.alloc(end - start);
+    fs.readSync(fd, buf, 0, buf.length, start);
+    return buf;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function splitLines(buf) {
+  const lines = [];
+  let from = 0;
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === 10) {
+      lines.push(buf.subarray(from, i).toString("utf8"));
+      from = i + 1;
+    }
+  }
+  return { lines, rest: buf.subarray(from) };
+}
+
+function parse(line) {
+  if (!line) return null;
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+const truncate = (text, max) => (text && text.length > max ? `${text.slice(0, max)}…` : text);
+
+function toolTitle(name, input = {}) {
+  return input.description || input.title || input.file_path || input.pattern || input.query || input.url || input.skill || (typeof input.command === "string" ? input.command : "") || "";
+}
+
+function toolDetail(name, input = {}) {
+  if (typeof input.command === "string") return input.command;
+  if (input.prompt) return input.prompt;
+  if (input.file_path && (input.old_string || input.content)) return `${input.file_path}\n\n${input.new_string ?? input.content ?? ""}`;
+  return JSON.stringify(input, null, 2);
+}
+
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map((c) => (c.type === "text" ? c.text : "")).join("\n");
+  return "";
+}
+
+const IMAGE_CACHE_NOTE = /^(\s*\[Image: source: [^\]]+\]\s*)+$/;
+
+function isSystemText(text) {
+  if (IMAGE_CACHE_NOTE.test(text)) return true;
+  return /^\s*(<(task-notification|system-reminder|local-command|command-|bash-|user-memory|ide_)|Base directory for this skill:|Caveat: The messages below)/.test(text);
+}
+
+function emptyMeta(file) {
+  return {
+    file,
+    title: null,
+    customTitle: null,
+    cwd: null,
+    firstCwd: null,
+    gitBranch: null,
+    model: null,
+    contextTokens: 0,
+    peakContext: 0,
+    prLinks: new Set(),
+    mentions: new Set(),
+    firstTs: null,
+    lastTs: null,
+    firstPrompt: null,
+    lastPrompt: null,
+    lastText: null,
+    lastAction: null,
+    turnOpen: false,
+    turns: 0,
+  };
+}
+
+function applyRecord(meta, rec) {
+  if (rec.timestamp) {
+    meta.firstTs ??= rec.timestamp;
+    if (!meta.lastTs || rec.timestamp > meta.lastTs) meta.lastTs = rec.timestamp;
+  }
+  switch (rec.type) {
+    case "ai-title":
+      if (rec.aiTitle) meta.title = rec.aiTitle;
+      break;
+    case "custom-title":
+      if (rec.customTitle) meta.customTitle = rec.customTitle;
+      break;
+    case "summary":
+      if (rec.summary && !meta.title) meta.title = rec.summary;
+      break;
+    case "pr-link":
+      if (rec.prUrl) meta.prLinks.add(rec.prUrl);
+      break;
+    case "user": {
+      if (rec.cwd) {
+        meta.firstCwd ??= rec.cwd;
+        meta.cwd = rec.cwd;
+      }
+      if (rec.gitBranch) meta.gitBranch = rec.gitBranch;
+      const content = rec.message?.content;
+      const typedByUser = typeof content === "string" || (Array.isArray(content) && !content.some((c) => c.type === "tool_result"));
+      const text = textOf(content);
+      if (typedByUser || (Array.isArray(content) && content.some((c) => c.type === "tool_result"))) meta.turnOpen = true;
+      if (typedByUser && text.includes("<command-name>")) {
+        const command = commandEvent(text);
+        meta.firstPrompt ??= truncate(`/${command.name} ${command.text}`.trim(), 120);
+        meta.turns++;
+      } else if (typedByUser && text && !isSystemText(text)) {
+        meta.firstPrompt ??= truncate(text.trim(), 120);
+        meta.lastPrompt = truncate(text.trim(), 280);
+        meta.turns++;
+        for (const m of text.slice(0, 4000).matchAll(MENTION)) meta.mentions.add(m[1]);
+      }
+      break;
+    }
+    case "assistant": {
+      if (rec.message?.model && !rec.message.model.startsWith("<")) meta.model = rec.message.model;
+      const u = rec.message?.usage;
+      if (u && !rec.isSidechain && rec.message?.model !== "<synthetic>") {
+        const used = (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
+        if (used > 0) {
+          meta.contextTokens = used;
+          meta.peakContext = Math.max(meta.peakContext, used);
+        }
+      }
+      if (rec.message?.stop_reason) meta.turnOpen = rec.message.stop_reason === "tool_use";
+      for (const block of rec.message?.content ?? []) {
+        if (block.type === "text" && block.text?.trim()) meta.lastText = truncate(block.text.trim(), 400);
+        if (block.type === "tool_use") meta.lastAction = { tool: block.name, title: truncate(toolTitle(block.name, block.input), 160), ts: rec.timestamp };
+      }
+      break;
+    }
+  }
+}
+
+function readMeta(file) {
+  const stat = fs.statSync(file);
+  let entry = metaCache.get(file);
+  if (!entry || stat.size < entry.offset) entry = { offset: 0, rest: Buffer.alloc(0), meta: emptyMeta(file) };
+  if (stat.size > entry.offset) {
+    const chunk = Buffer.concat([entry.rest, readFrom(file, entry.offset, stat.size)]);
+    const { lines, rest } = splitLines(chunk);
+    for (const line of lines) {
+      const rec = parse(line);
+      if (rec) applyRecord(entry.meta, rec);
+    }
+    entry.offset = stat.size;
+    entry.rest = rest;
+  }
+  entry.mtimeMs = stat.mtimeMs;
+  metaCache.set(file, entry);
+  return { ...entry.meta, mtimeMs: stat.mtimeMs, size: stat.size };
+}
+
+/**
+ * A turn is open from a user message or tool result until an assistant message ends with a stop
+ * reason other than tool_use. Turns silent for 15 minutes count as stale (crashed or abandoned).
+ */
+function statusFor(meta, now = Date.now()) {
+  const age = now - meta.mtimeMs;
+  if (meta.turnOpen && age < STALE_TURN_MS) return "working";
+  if (age < RECENT_MS) return "idle";
+  return "inactive";
+}
+
+function projectLabel(cwd, dir) {
+  const source = cwd ?? dir;
+  const refresh = source.match(/ws-refresh\/([^/]+?)-\d+$/);
+  if (refresh) return `Refresco IA · ${refresh[1]}`;
+  const worktree = source.match(/\.worktrees\/([^/]+)\/([^/]+)/);
+  if (worktree) return `${worktree[1]} · ${worktree[2]}`;
+  return path.basename(source);
+}
+
+function listSubagents(sessionFile) {
+  const dir = path.join(sessionFile.replace(/\.jsonl$/, ""), "subagents");
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    return [];
+  }
+  return files
+    .map((f) => {
+      const file = path.join(dir, f);
+      const id = f.replace(/\.jsonl$/, "").replace(/^agent-/, "");
+      let info = {};
+      try {
+        info = JSON.parse(fs.readFileSync(file.replace(/\.jsonl$/, ".meta.json"), "utf8"));
+      } catch {}
+      const meta = readMeta(file);
+      return {
+        id,
+        description: info.description ?? meta.lastPrompt ?? id,
+        agentType: info.agentType,
+        toolUseId: info.toolUseId,
+        status: statusFor(meta),
+        lastTs: meta.lastTs,
+        lastAction: meta.lastAction,
+        lastText: meta.lastText,
+      };
+    })
+    .sort((a, b) => (b.lastTs ?? "").localeCompare(a.lastTs ?? ""));
+}
+
+function sessionFiles(maxAgeMs) {
+  const now = Date.now();
+  const out = [];
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(PROJECTS_DIR);
+  } catch {
+    return out;
+  }
+  for (const dir of dirs) {
+    const full = path.join(PROJECTS_DIR, dir);
+    let entries;
+    try {
+      entries = fs.readdirSync(full);
+    } catch {
+      continue;
+    }
+    for (const f of entries) {
+      if (!f.endsWith(".jsonl")) continue;
+      const file = path.join(full, f);
+      const stat = fs.statSync(file);
+      if (now - stat.mtimeMs <= maxAgeMs) out.push({ id: f.replace(/\.jsonl$/, ""), dir, file });
+    }
+  }
+  return out;
+}
+
+function summarize({ id, dir, file }, withSubagents = true) {
+  const meta = readMeta(file);
+  const subagents = withSubagents ? listSubagents(file) : [];
+  const anySubWorking = subagents.some((s) => s.status === "working");
+  const status = anySubWorking ? "working" : statusFor(meta);
+  return {
+    id,
+    title: meta.customTitle ?? meta.title ?? meta.firstPrompt ?? "Sesión sin título",
+    project: projectLabel(meta.cwd, dir),
+    cwd: meta.cwd,
+    firstCwd: meta.firstCwd,
+    gitBranch: meta.gitBranch,
+    model: meta.model,
+    contextTokens: meta.contextTokens,
+    // The transcript doesn't record the window; assume 200k unless the session already went past it (1M).
+    contextWindow: meta.peakContext > 200_000 ? 1_000_000 : 200_000,
+    prLinks: [...meta.prLinks],
+    mentions: [...meta.mentions],
+    firstTs: meta.firstTs,
+    lastTs: meta.lastTs,
+    status,
+    lastAction: meta.lastAction,
+    lastText: meta.lastText,
+    lastPrompt: meta.lastPrompt,
+    turns: meta.turns,
+    subagents: subagents.map(({ toolUseId, ...s }) => s),
+  };
+}
+
+export function listSessions({ days = 3 } = {}) {
+  return sessionFiles(days * 24 * 60 * 60_000)
+    .map((s) => summarize(s))
+    .sort((a, b) => (b.lastTs ?? "").localeCompare(a.lastTs ?? ""));
+}
+
+function findSessionFile(id) {
+  if (!/^[\w-]+$/.test(id)) return null;
+  for (const dir of fs.readdirSync(PROJECTS_DIR)) {
+    const file = path.join(PROJECTS_DIR, dir, `${id}.jsonl`);
+    if (fs.existsSync(file)) return { id, dir, file };
+  }
+  return null;
+}
+
+/** A slash command the user typed (`/pr-plan foo`), which Claude Code records as tagged text. */
+function commandEvent(text, ts) {
+  const name = text.match(/<command-name>\/?([^<]+)<\/command-name>/)?.[1]?.trim() ?? "comando";
+  const args = text.match(/<command-args>([\s\S]*?)<\/command-args>/)?.[1]?.trim() ?? "";
+  return { kind: "command", ts, name, text: args };
+}
+
+function toEvents(rec, agentsByToolUse) {
+  const ts = rec.timestamp;
+  const events = [];
+  if (rec.type === "user") {
+    const content = rec.message?.content;
+    if (typeof content === "string") {
+      if (content.startsWith("<task-notification")) {
+        const summary = content.match(/<summary>([\s\S]*?)<\/summary>/)?.[1];
+        events.push({ kind: "notice", ts, text: truncate(summary ?? "Notificación de tarea en background", 300) });
+      } else if (content.includes("<command-name>")) {
+        events.push(commandEvent(content, ts));
+      } else if (!isSystemText(content)) {
+        events.push({ kind: "prompt", ts, text: truncate(content, 6000) });
+      }
+    } else if (Array.isArray(content)) {
+      const texts = [];
+      let images = 0;
+      for (const block of content) {
+        if (block.type === "tool_result") {
+          const text = Array.isArray(block.content) ? block.content.map((c) => (c.type === "text" ? c.text : c.type === "image" ? "[imagen]" : "")).join("\n") : String(block.content ?? "");
+          events.push({ kind: "result", ts, toolUseId: block.tool_use_id, isError: Boolean(block.is_error), text: truncate(text, 4000) });
+        } else if (block.type === "text" && block.text?.includes("<command-name>")) {
+          events.push(commandEvent(block.text, ts));
+        } else if (block.type === "text" && block.text && !isSystemText(block.text)) {
+          texts.push(block.text);
+        } else if (block.type === "image") {
+          images++;
+        }
+      }
+      if (texts.length || images) events.push({ kind: "prompt", ts, text: truncate(texts.join("\n\n"), 6000), images });
+    }
+  } else if (rec.type === "assistant") {
+    for (const block of rec.message?.content ?? []) {
+      if (block.type === "text" && block.text?.trim()) events.push({ kind: "text", ts, text: truncate(block.text, 12000) });
+      if (block.type === "tool_use") {
+        events.push({
+          kind: "tool",
+          ts,
+          id: block.id,
+          name: block.name,
+          title: truncate(toolTitle(block.name, block.input), 200),
+          detail: truncate(toolDetail(block.name, block.input), 4000),
+          agentId: agentsByToolUse?.get(block.id),
+        });
+      }
+    }
+  } else if (rec.type === "system" && rec.subtype === "compact_boundary") {
+    events.push({ kind: "notice", ts, text: "Contexto compactado" });
+  }
+  return events;
+}
+
+/** Returns timeline events after `since` (byte offset), or the tail of the file when `since` is omitted. */
+export function readSessionEvents(id, { since, agent } = {}) {
+  const session = findSessionFile(id);
+  if (!session) return null;
+  const subagents = listSubagents(session.file);
+  const file = agent ? path.join(session.file.replace(/\.jsonl$/, ""), "subagents", `agent-${agent}.jsonl`) : session.file;
+  if (agent && (!/^[\w-]+$/.test(agent) || !fs.existsSync(file))) return null;
+
+  const agentsByToolUse = new Map();
+  const subDir = path.join(session.file.replace(/\.jsonl$/, ""), "subagents");
+  for (const s of subagents) {
+    try {
+      const info = JSON.parse(fs.readFileSync(path.join(subDir, `agent-${s.id}.meta.json`), "utf8"));
+      if (info.toolUseId) agentsByToolUse.set(info.toolUseId, s.id);
+    } catch {}
+  }
+
+  const size = fs.statSync(file).size;
+  const start = since !== undefined ? Math.min(Number(since), size) : Math.max(0, size - TAIL_BYTES);
+  const { lines, rest } = splitLines(readFrom(file, start, size));
+  if (since === undefined && start > 0) lines.shift();
+  const events = [];
+  for (const line of lines) {
+    const rec = parse(line);
+    if (rec) events.push(...toEvents(rec, agentsByToolUse));
+  }
+  return {
+    session: summarize(session),
+    events: since === undefined ? events.slice(-600) : events,
+    cursor: size - rest.length,
+    truncated: since === undefined && start > 0,
+  };
+}
+
+/** Sessions whose PRs, branch, worktree or mentions point at the given task. */
+export function sessionsForTask(task, sessions = listSessions()) {
+  const prUrls = new Set();
+  const prNumbers = new Set();
+  for (const r of task.repos ?? []) {
+    if (r.pr) {
+      prUrls.add(r.pr);
+      prNumbers.add(r.pr.split("/").pop());
+    }
+  }
+  for (const pr of task.relatedPrs ?? []) prNumbers.add(String(pr).split("/").pop());
+  const branches = new Set((task.repos ?? []).map((r) => r.branch).filter((b) => b && !["main", "develop", "master"].includes(b)));
+  return sessions.filter(
+    (s) =>
+      (task.sessionIds ?? []).includes(s.id) ||
+      s.prLinks.some((url) => prUrls.has(url) || prNumbers.has(url.split("/").pop())) ||
+      (s.gitBranch && branches.has(s.gitBranch)) ||
+      s.mentions.includes(task.id) ||
+      (s.cwd ?? "").includes(`/.worktrees/${task.id}/`),
+  );
+}
+
+export function sessionIdFromPath(relPath) {
+  const parts = relPath.split(path.sep);
+  if (parts.length < 2) return null;
+  return parts[1].replace(/\.jsonl$/, "");
+}
+
+export function sessionCwd(id) {
+  const session = findSessionFile(id);
+  return session ? readMeta(session.file).firstCwd : null;
+}