@polymorphism-tech/morph-spec 8.38.0 → 8.41.0

package/src/dashboard/app/styles/index.css

@@ -1,47 +1,187 @@
-@import "tailwindcss";
-@import "@xyflow/react/dist/style.css";
-
-:root {
-  --tier-1: #ef4444;
-  --tier-2: #f97316;
-  --tier-3: #3b82f6;
-  --tier-4: #8b5cf6;
-  --gate-color: #fbbf24;
-}
-
-/* React Flow dark theme overrides */
-.react-flow {
-  background: #030712;
-}
-
-.react-flow__minimap {
-  background: #111827;
-}
-
-.react-flow__minimap-mask {
-  fill: #1f2937;
-}
-
-.react-flow__controls {
-  background: #111827;
-  border: 1px solid #374151;
-}
-
-.react-flow__controls-button {
-  background: #111827;
-  border-bottom: 1px solid #374151;
-  color: #9ca3af;
-}
-
-.react-flow__controls-button:hover {
-  background: #1f2937;
-  color: #f9fafb;
-}
-
-.react-flow__edge-path {
-  stroke: #4b5563;
-}
-
-.react-flow__node {
-  border-radius: 0.5rem;
-}
+@import "tailwindcss";
+@import "@xyflow/react/dist/style.css";
+@import "@fontsource-variable/geist";
+@import "@fontsource-variable/geist-mono";
+@import "@fontsource-variable/source-serif-4";
+
+/*
+ * One token system for the whole app. The phase scale is the only palette of
+ * meaning: the rail, graphs, chips and the document tree all read it, so a
+ * colour always says the same thing. `static`: the phase colours are read as
+ * `var(--color-phase-${id})`, a name Tailwind cannot see in the source.
+ */
+@theme static {
+  --font-sans: "Geist Variable", ui-sans-serif, system-ui, sans-serif;
+  --font-mono: "Geist Mono Variable", ui-monospace, monospace;
+  --font-serif: "Source Serif 4 Variable", ui-serif, Georgia, serif;
+
+  --color-ink: #050505;
+  --color-shell: #0c0e12;
+  --color-core: #12151b;
+  --color-raised: #181c24;
+  --color-hair: rgb(255 255 255 / 0.08);
+  --color-hair-strong: rgb(255 255 255 / 0.14);
+  --color-fg: #e8ecf1;
+  --color-dim: #8d97a5;
+  --color-faint: #5c6573;
+
+  --color-phase-proposal: #7aa2f7;
+  --color-phase-uiux: #bb9af7;
+  --color-phase-plan: #e0af68;
+  --color-phase-implement: #73daca;
+  --color-phase-review: #f7768e;
+
+  --color-ok: #9ece6a;
+  --color-warn: #ff9e64;
+  --color-bad: #f7768e;
+
+  --ease-fluid: cubic-bezier(0.32, 0.72, 0, 1);
+
+  /* The graph pages were written against Tailwind's gray scale; re-tinting the
+     scale to these neutrals puts them in the same room as the rest. */
+  --color-gray-50: #f3f5f8;
+  --color-gray-100: #e8ecf1;
+  --color-gray-200: #d6dce4;
+  --color-gray-300: #b8c0cc;
+  --color-gray-400: #8d97a5;
+  --color-gray-500: #6b7482;
+  --color-gray-600: #4a5260;
+  --color-gray-700: #2a303b;
+  --color-gray-800: #1b1f27;
+  --color-gray-900: #12151b;
+  --color-gray-950: #07080a;
+}
+
+html { color-scheme: dark; }
+html, body, #root { height: 100%; }
+
+body {
+  background: var(--color-ink);
+  color: var(--color-fg);
+  font-family: var(--font-sans);
+  font-feature-settings: "ss01", "cv11";
+  -webkit-font-smoothing: antialiased;
+}
+
+/* The ambient glow: fixed and inert, never on a scrolling layer. */
+.ambient {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: 0;
+  background:
+    radial-gradient(40rem 28rem at 12% -8%, rgb(187 154 247 / 0.10), transparent 70%),
+    radial-gradient(36rem 26rem at 96% 108%, rgb(115 218 202 / 0.08), transparent 70%);
+}
+
+/* Double bezel: an outer tray holding an inner plate with a lit top edge. */
+.bezel {
+  border-radius: 1.25rem;
+  padding: 0.3rem;
+  background: rgb(255 255 255 / 0.025);
+  box-shadow: inset 0 0 0 1px var(--color-hair);
+}
+.bezel > .bezel-core {
+  border-radius: calc(1.25rem - 0.3rem);
+  background: var(--color-core);
+  box-shadow: inset 0 1px 0 rgb(255 255 255 / 0.06), 0 0 0 1px rgb(255 255 255 / 0.03);
+}
+
+.fluid { transition-timing-function: var(--ease-fluid); transition-duration: 420ms; }
+
+/* A single orchestrated entrance per page. */
+@keyframes rise {
+  from { opacity: 0; transform: translateY(10px); }
+  to { opacity: 1; transform: none; }
+}
+.rise { animation: rise 640ms var(--ease-fluid) both; }
+.rise-2 { animation: rise 640ms var(--ease-fluid) 80ms both; }
+.rise-3 { animation: rise 640ms var(--ease-fluid) 160ms both; }
+
+@media (prefers-reduced-motion: reduce) {
+  .rise, .rise-2, .rise-3 { animation: none; }
+  .fluid { transition-duration: 0ms; }
+}
+
+:focus-visible { outline: 2px solid var(--color-phase-proposal); outline-offset: 2px; border-radius: 6px; }
+
+/* Long-form reading: serif, measured, generous leading. */
+.prose-morph {
+  font-family: var(--font-serif);
+  font-size: 1.02rem;
+  line-height: 1.65;
+  color: #d9dee6;
+  max-width: 75ch;
+}
+.prose-morph h1, .prose-morph h2, .prose-morph h3, .prose-morph h4 {
+  font-family: var(--font-sans);
+  color: var(--color-fg);
+  letter-spacing: -0.01em;
+  line-height: 1.25;
+  scroll-margin-top: 1.5rem;
+}
+.prose-morph h1 { font-size: 1.75rem; font-weight: 600; margin: 0 0 1.25rem; }
+.prose-morph h2 { font-size: 1.3rem; font-weight: 600; margin: 2.25rem 0 0.75rem; }
+.prose-morph h3 { font-size: 1.08rem; font-weight: 600; margin: 1.75rem 0 0.5rem; }
+.prose-morph h4 { font-size: 0.98rem; font-weight: 600; margin: 1.25rem 0 0.4rem; }
+.prose-morph p, .prose-morph ul, .prose-morph ol, .prose-morph blockquote, .prose-morph table, .prose-morph pre { margin: 0 0 1rem; }
+.prose-morph ul { list-style: disc; padding-left: 1.4rem; }
+.prose-morph ol { list-style: decimal; padding-left: 1.4rem; }
+.prose-morph li { margin: 0.25rem 0; }
+.prose-morph li::marker { color: var(--color-faint); }
+.prose-morph a { color: var(--color-phase-proposal); text-decoration: underline; text-underline-offset: 3px; text-decoration-color: rgb(122 162 247 / 0.4); }
+.prose-morph strong { color: var(--color-fg); font-weight: 600; }
+.prose-morph blockquote { border-left: 2px solid var(--color-hair-strong); padding-left: 1rem; color: var(--color-dim); }
+.prose-morph hr { border: 0; border-top: 1px solid var(--color-hair); margin: 2rem 0; }
+.prose-morph code {
+  font-family: var(--font-mono);
+  font-size: 0.84em;
+  background: rgb(255 255 255 / 0.06);
+  border-radius: 5px;
+  padding: 0.1em 0.35em;
+}
+.prose-morph pre {
+  font-family: var(--font-mono);
+  font-size: 0.8rem;
+  line-height: 1.55;
+  background: var(--color-ink);
+  border-radius: 0.75rem;
+  box-shadow: inset 0 0 0 1px var(--color-hair);
+  padding: 0.9rem 1rem;
+  overflow-x: auto;
+  max-width: 100%;
+}
+.prose-morph pre code { background: none; padding: 0; font-size: inherit; }
+.prose-morph table { display: block; overflow-x: auto; border-collapse: collapse; font-family: var(--font-sans); font-size: 0.86rem; }
+.prose-morph th, .prose-morph td { border-bottom: 1px solid var(--color-hair); padding: 0.4rem 0.75rem; text-align: left; vertical-align: top; }
+.prose-morph th { color: var(--color-dim); font-weight: 500; }
+
+.prose-morph-sm { font-size: 0.95rem; line-height: 1.6; }
+.prose-morph-sm h1 { font-size: 1.35rem; }
+.prose-morph-sm h2 { font-size: 1.12rem; margin-top: 1.75rem; }
+.prose-morph-sm h3 { font-size: 1rem; }
+
+/* React Flow, re-skinned to the tokens. */
+.react-flow { background: transparent; }
+.react-flow__minimap { background: var(--color-shell); border-radius: 0.75rem; }
+.react-flow__minimap-mask { fill: rgb(255 255 255 / 0.04); }
+.react-flow__controls { background: var(--color-shell); border-radius: 0.75rem; overflow: hidden; box-shadow: inset 0 0 0 1px var(--color-hair); }
+.react-flow__controls-button { background: transparent; border-bottom: 1px solid var(--color-hair); color: var(--color-dim); }
+.react-flow__controls-button:hover { background: var(--color-raised); color: var(--color-fg); }
+.react-flow__edge-path { stroke: #3a4250; }
+.react-flow__node { border-radius: 0.6rem; }
+.react-flow__attribution { background: transparent; opacity: 0.45; }
+.react-flow__attribution a { color: var(--color-faint); }
+
+/* The one ambient motion: a slow sheen on the current phase of an active feature. */
+@keyframes sheen {
+  from { transform: translateX(-100%); }
+  to { transform: translateX(100%); }
+}
+.rail-sheen {
+  background: linear-gradient(90deg, transparent, rgb(255 255 255 / 0.45), transparent);
+  animation: sheen 2.4s var(--ease-fluid) infinite;
+}
+@media (prefers-reduced-motion: reduce) {
+  .rail-sheen { animation: none; display: none; }
+}

package/src/dashboard/index.html

@@ -1,12 +1,14 @@
-<!DOCTYPE html>
-<html lang="en" class="dark bg-gray-950">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>morph-spec Dashboard</title>
-  </head>
-  <body class="dark bg-gray-950 text-gray-100">
-    <div id="root"></div>
-    <script type="module" src="/app/main.jsx"></script>
-  </body>
-</html>
+<!DOCTYPE html>
+<html lang="pt-BR" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>morph-spec</title>
+    <!-- Inline, so the browser's /favicon.ico request never 404s in the console. -->
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%23030712'/%3E%3Cpath d='M8 23V9l8 8 8-8v14' fill='none' stroke='%233b82f6' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/app/main.jsx"></script>
+  </body>
+</html>

package/src/dashboard/package.json

@@ -1,24 +1,32 @@
-{
-  "name": "morph-spec-dashboard",
-  "private": true,
-  "version": "0.1.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "preview": "vite preview"
-  },
-  "dependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-router-dom": "^7.0.0",
-    "@xyflow/react": "^12.0.0",
-    "@dagrejs/dagre": "^1.1.0"
-  },
-  "devDependencies": {
-    "@vitejs/plugin-react": "^4.4.0",
-    "vite": "^6.0.0",
-    "@tailwindcss/vite": "^4.0.0",
-    "tailwindcss": "^4.0.0"
-  }
-}
+{
+  "name": "morph-spec-dashboard",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@dagrejs/dagre": "^1.1.0",
+    "@fontsource-variable/geist": "^5.3.0",
+    "@fontsource-variable/geist-mono": "^5.3.0",
+    "@fontsource-variable/source-serif-4": "^5.3.0",
+    "@phosphor-icons/react": "^2.1.10",
+    "@xyflow/react": "^12.0.0",
+    "github-slugger": "^2.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-markdown": "^10.1.0",
+    "react-router-dom": "^7.0.0",
+    "rehype-slug": "^6.0.0",
+    "remark-gfm": "^4.0.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@vitejs/plugin-react": "^4.4.0",
+    "tailwindcss": "^4.0.0",
+    "vite": "^6.0.0"
+  }
+}

package/src/dashboard/scanner/activity-scanner.js

@@ -0,0 +1,351 @@
+/**
+ * The harness event stream (`.morph/logs/events.jsonl`, schema v2 of
+ * framework/hooks/shared/telemetry-logger.js) told as a feed a person can read.
+ *
+ * Reading and summing are NOT done here: `loadTelemetryAllTrees` gathers every
+ * tree's log plus the finish backups, and `aggregateCost` is the one place
+ * tokens are added up (only `delta` can be summed; a v1 stream yields `null`,
+ * which the UI shows as unknown — never 0). This module only decides what each
+ * event means in words, and which ones are worth a line.
+ */
+
+import { statSync, openSync, readSync, closeSync } from 'fs';
+import { join, resolve } from 'path';
+import { loadTelemetryAllTrees, aggregateCost, dedupeEvents } from '../../lib/telemetry/telemetry-reader.js';
+import { isFailedToolCall } from '../../../framework/hooks/shared/telemetry-logger.js';
+
+/** Kinds a person follows by default; the rest are one click away. */
+export const DEFAULT_KINDS = ['prompt', 'question', 'skill', 'dispatch', 'handback', 'task', 'verify', 'gate', 'failure'];
+export const ALL_KINDS = [...DEFAULT_KINDS, 'write', 'read', 'command', 'tool'];
+
+const GATE_COMMAND = /\bmorph-spec\s+(approve|gate-check|gate-decision|advance|score|finish)\b/;
+const MORPH_PERSONA = /^morph-(.+)$/;
+const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);
+const SILENT_EVENTS = new Set(['ToolBatch', 'SessionUsage', 'AgentUsage']);
+
+function shortPath(p) {
+  if (typeof p !== 'string') return null;
+  const norm = p.replace(/\\/g, '/');
+  const feat = norm.indexOf('/.morph/features/');
+  if (feat !== -1) return norm.slice(feat + '/.morph/features/'.length).split('/').slice(1).join('/');
+  const morph = norm.indexOf('/.morph/');
+  if (morph !== -1) return norm.slice(morph + 1);
+  return norm.split('/').slice(-3).join('/');
+}
+
+function clip(text, max = 280) {
+  if (typeof text !== 'string') return null;
+  const flat = text.trim();
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+function nodesSummary(nodes) {
+  if (!nodes || typeof nodes !== 'object') return [];
+  return Object.entries(nodes).map(([name, n]) => ({ name, status: typeof n === 'string' ? n : n?.status ?? null }));
+}
+
+/**
+ * One event → one feed line, or null when the event is bookkeeping.
+ *
+ * @returns {null | {
+ *   id: string, ts: string, feature: string|null, phase: string|null,
+ *   kind: string, title: string, detail: string|null, status: 'ok'|'fail'|null,
+ *   refs: { persona?: string, skill?: string, task?: string, path?: string },
+ *   nodes?: Array<{name: string, status: string|null}>
+ * }}
+ */
+export function describeEvent(e) {
+  if (!e || typeof e !== 'object' || SILENT_EVENTS.has(e.event)) return null;
+  const base = {
+    id: e.eventId || `${e.ts}:${e.event}:${e.tool || ''}:${e.task || ''}`,
+    ts: e.ts || null,
+    feature: e.feature || null,
+    phase: e.phase || null,
+    agent: e.agentType || null,
+    status: null,
+    detail: null,
+    refs: {},
+  };
+  const line = (kind, title, extra = {}) => ({ ...base, kind, title, ...extra, refs: { ...base.refs, ...(extra.refs || {}) } });
+
+  if (e.event === 'UserPromptSubmit') {
+    // Hand-backs, task notifications and reminders arrive through the same door
+    // as a person's prompt, wrapped in a tag. A slash command is the one tagged
+    // prompt a person typed.
+    const text = typeof e.prompt === 'string' ? e.prompt.trim() : '';
+    const command = /^<command-name>\/?([^<]+)<\/command-name>/.exec(text);
+    if (command) return line('prompt', `Você rodou /${command[1].trim()}`);
+    if (text.startsWith('<')) return null;
+    return line('prompt', 'Você escreveu', { detail: clip(text) });
+  }
+  if (e.event === 'TaskStart') return line('task', `${e.task} começou`, { refs: { task: e.task } });
+  if (e.event === 'TaskEnd') {
+    const done = e.status === 'done';
+    return line('task', done ? `${e.task} concluída` : `${e.task} terminou (${e.status ?? 'sem status'})`, {
+      status: done ? 'ok' : null, refs: { task: e.task },
+    });
+  }
+  if (e.event === 'Verify') {
+    const ok = e.status === 'pass';
+    const scope = e.task ? e.task : 'feature inteira';
+    return line('verify', `verify ${scope} ${ok ? 'passou' : 'falhou'}`, {
+      status: ok ? 'ok' : 'fail', nodes: nodesSummary(e.nodes), refs: e.task ? { task: e.task } : {},
+      detail: e.persisted === false && e.reason ? `não carimbou: ${e.reason}` : null,
+    });
+  }
+  if (e.event !== 'PostToolUse' && e.event !== 'PostToolUseFailure') return null;
+
+  const failed = isFailedToolCall(e);
+  const tool = e.tool;
+  if (tool === 'Agent' || tool === 'Task') {
+    const m = MORPH_PERSONA.exec(e.persona || '');
+    return line('dispatch', `Despachou ${e.persona || 'sub-agent'}`, {
+      detail: e.desc || clip(e.prompt, 160), refs: m ? { persona: m[1] } : {},
+    });
+  }
+  if (tool === 'SubagentHandback') return line('handback', `${e.agentType || 'Sub-agent'} devolveu o relatório`);
+  if (tool === 'Skill') return line('skill', `Carregou a skill ${e.skill}`, { refs: { skill: e.skill } });
+  if (tool === 'AskUserQuestion') return line('question', 'Perguntou a você');
+  if (SHELL_TOOLS.has(tool)) {
+    const gate = GATE_COMMAND.exec(e.command || '');
+    if (gate) {
+      return line('gate', `morph-spec ${gate[1]}`, { detail: clip(e.command, 200), status: failed ? 'fail' : 'ok' });
+    }
+    if (failed) {
+      return line('failure', `Comando falhou (exit ${e.exitCode ?? '?'})`, { detail: clip(e.command, 200), status: 'fail' });
+    }
+    return line('command', tool, { detail: clip(e.command, 200) });
+  }
+  if (tool === 'Write' || tool === 'Edit') {
+    return line('write', `${tool === 'Write' ? 'Escreveu' : 'Editou'} ${shortPath(e.target)}`, { refs: { path: shortPath(e.target) } });
+  }
+  if (tool === 'Read') {
+    const what = e.kind && e.kind !== 'code' ? ` (${e.kind})` : '';
+    return line('read', `Leu ${shortPath(e.target)}${what}`, { refs: { path: shortPath(e.target) } });
+  }
+  if (failed) return line('failure', `${tool} falhou`, { status: 'fail' });
+  return line('tool', tool || e.event);
+}
+
+// The same event array is fed again on every request until the log changes:
+// describing ~100k events once, not per page, is the difference that matters.
+const described = new WeakMap();
+
+function describeAll(events) {
+  if (!Array.isArray(events)) return [];
+  if (!described.has(events)) {
+    const lines = [];
+    for (const e of events) {
+      const d = describeEvent(e);
+      if (d) lines.push(d);
+    }
+    lines.sort((a, b) => (b.ts || '').localeCompare(a.ts || ''));
+    described.set(events, lines);
+  }
+  return described.get(events);
+}
+
+/**
+ * The feed, newest first, filtered and paginated by a `before` timestamp cursor.
+ *
+ * @param {Object[]} events - raw events, any order
+ * @param {{ feature?: string, kinds?: string[], before?: string, limit?: number }} [opts]
+ */
+export function buildFeed(events, { feature, kinds = DEFAULT_KINDS, before, limit = 100 } = {}) {
+  const wanted = new Set(kinds);
+  const lines = describeAll(events).filter((l) => wanted.has(l.kind) && (!feature || l.feature === feature));
+  const start = before ? lines.findIndex((l) => (l.ts || '') < before) : 0;
+  const page = start === -1 ? [] : lines.slice(start, start + limit);
+  const last = page[page.length - 1];
+  return { items: page, next: page.length === limit && last ? last.ts : null, total: lines.length };
+}
+
+/**
+ * What the feature list shows as "the last thing that happened" in each
+ * feature: the newest line a person follows by default (a dispatch, a verify, a
+ * task — not a Read or a shell command), plus `ts`, the newest event of ANY kind,
+ * which is what says an agent is working right now.
+ *
+ * @param {Object[]} events
+ * @returns {Record<string, {ts: string, title: string|null, kind: string|null, status: string|null, titleTs: string|null}>}
+ */
+const lastByLines = new WeakMap();
+
+export function lastActivityByFeature(events) {
+  const lines = describeAll(events);
+  if (lastByLines.has(lines)) return lastByLines.get(lines);
+  const wanted = new Set(DEFAULT_KINDS);
+  const out = {};
+  for (const line of lines) {
+    if (!line.feature) continue;
+    const entry = (out[line.feature] ||= { ts: line.ts, title: null, kind: null, status: null, titleTs: null });
+    if (entry.title === null && wanted.has(line.kind)) {
+      Object.assign(entry, { title: line.title, kind: line.kind, status: line.status, titleTs: line.ts });
+    }
+  }
+  lastByLines.set(lines, out);
+  return out;
+}
+
+/** Every event of the project across its trees and finish backups. */
+export function loadProjectEvents(projectDir) {
+  return dedupeEvents(loadTelemetryAllTrees(projectDir).flatMap((t) => t.events));
+}
+
+const LIVE_LOG = join('.morph', 'logs', 'events.jsonl');
+
+function eventKey(e) {
+  return e.eventId ? `id:${e.eventId}` : `raw:${JSON.stringify(e)}`;
+}
+
+function fileSize(path) {
+  try { return statSync(path).size; } catch { return -1; }
+}
+
+/**
+ * The project's events kept in memory and followed as they are appended.
+ *
+ * A running agent appends one line to its tree's `events.jsonl` per tool call.
+ * Re-reading every log (≈100k events, seconds) on each append would block the
+ * dev server for the whole run, so the store remembers how far it read each
+ * live log and parses only the bytes after that. Anything it cannot follow
+ * that way — a log that shrank (SessionStart rotated it), a log it has never
+ * seen (a new worktree), an archive or backup — falls back to a full reload
+ * through `loadTelemetryAllTrees`, the same reader as always. Copies of one
+ * event are still dropped by `eventId`.
+ *
+ * Every update yields a NEW events array, so everything memoized per array
+ * (described lines, per-feature cost) follows the change.
+ *
+ * @param {string} projectDir
+ * @param {{ loadTrees?: Function }} [deps] - test seam, defaults to loadTelemetryAllTrees
+ */
+export function createEventStore(projectDir, { loadTrees = loadTelemetryAllTrees } = {}) {
+  let events = null;
+  let seen = new Set();
+  let offsets = new Map(); // live log path -> bytes consumed (up to the last newline)
+  let pending = new Set();
+  let fullReload = true;
+  const costs = new Map();
+
+  function reload() {
+    const trees = loadTrees(projectDir);
+    const next = new Map();
+    // Sizes before the read: a line appended in between is read twice and
+    // deduplicated, never skipped.
+    for (const t of trees) {
+      if (t.tree === 'finish-backup') continue;
+      const path = join(t.path, LIVE_LOG);
+      next.set(path, Math.max(0, fileSize(path)));
+    }
+    events = dedupeEvents(trees.flatMap((t) => t.events));
+    seen = new Set(events.map(eventKey));
+    offsets = next;
+    fullReload = false;
+    pending.clear();
+    costs.clear();
+  }
+
+  /** Parse the bytes appended to `path` since the last read; false when it cannot follow. */
+  function tail(path) {
+    const from = offsets.get(path);
+    const size = fileSize(path);
+    if (from === undefined || size < from) return false;
+    if (size === from) return true;
+    const fd = openSync(path, 'r');
+    let text;
+    try {
+      const buf = Buffer.alloc(size - from);
+      readSync(fd, buf, 0, buf.length, from);
+      text = buf.toString('utf8');
+    } finally {
+      closeSync(fd);
+    }
+    const end = text.lastIndexOf('\n');
+    if (end === -1) return true; // a line still being written
+    offsets.set(path, from + Buffer.byteLength(text.slice(0, end + 1), 'utf8'));
+    const fresh = [];
+    for (const raw of text.slice(0, end).split('\n')) {
+      const trimmed = raw.trim();
+      if (!trimmed) continue;
+      let e;
+      try { e = JSON.parse(trimmed); } catch { continue; }
+      if (!e || typeof e !== 'object') continue;
+      const key = eventKey(e);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      fresh.push(e);
+    }
+    if (fresh.length) {
+      const last = events[events.length - 1]?.ts || '';
+      const prevLines = described.get(events);
+      const merged = events.concat(fresh);
+      events = fresh.every((e) => (e.ts || '') >= last) ? merged : dedupeEvents(merged);
+      // Carry the described lines over instead of describing 100k events again.
+      if (prevLines) {
+        const byTsDesc = (a, b) => (b.ts || '').localeCompare(a.ts || '');
+        const added = fresh.map(describeEvent).filter(Boolean).sort(byTsDesc);
+        const top = prevLines[0]?.ts || '';
+        described.set(events, added.every((l) => (l.ts || '') >= top)
+          ? [...added, ...prevLines]
+          : [...added, ...prevLines].sort(byTsDesc));
+      }
+      costs.clear();
+    }
+    return true;
+  }
+
+  function current() {
+    if (fullReload || events === null) {
+      reload();
+    } else if (pending.size) {
+      const paths = [...pending];
+      pending.clear();
+      for (const p of paths) {
+        if (!tail(p)) { reload(); break; }
+      }
+    }
+    return events;
+  }
+
+  return {
+    events: current,
+    /**
+     * Something under `.morph/logs` changed. A known live log is tailed on the
+     * next read; anything else (rotation archive, new tree, backup) reloads.
+     */
+    changed(path) {
+      const known = path && [...offsets.keys()].find((p) => resolve(p) === resolve(path));
+      if (known) pending.add(known);
+      else fullReload = true;
+    },
+    reset() { fullReload = true; },
+    /** Loaded and not waiting for a full reload: reading it now is cheap. */
+    ready() { return events !== null && !fullReload; },
+    /** `featureCost`, memoized until the events change. */
+    cost(feature) {
+      const all = current();
+      if (!costs.has(feature)) costs.set(feature, featureCost(all, feature));
+      return costs.get(feature);
+    },
+  };
+}
+
+/**
+ * What the feature cost, straight from `aggregateCost`. `sessionUsage` and
+ * `agentUsage` stay `null` when the stream has no summable sample.
+ */
+export function featureCost(events, feature) {
+  const c = aggregateCost(events, { feature });
+  return {
+    sessionUsage: c.sessionUsage,
+    agentUsage: c.agentUsage,
+    legacyUsageSamples: c.sessionUsageLegacySamples,
+    dispatches: c.dispatches,
+    bytesTotal: c.bytesTotal,
+    bytesByKind: c.bytesByKind,
+    taskDurationSeconds: c.taskDurationSeconds,
+    tasks: c.tasks,
+    events: c.total,
+  };
+}