@vale-dinap/lucidly 0.2.0 → 0.4.0

package/dist/core/engine.js

@@ -1,6 +1,6 @@
 const MAX_PATCH_LINES = 2000;
 const zeroUsage = () => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, responses: 0 });
-import { extractPlan, firstLine, hasDeviationCue, hasIntent, intentTitle, isSubstantivePrompt, isReply, endsWithQuestion, issueSummary, matchStep, sentences, similarity, stripMarkdown, tokens, truncate, } from "./text.js";
+import { extractPlan, firstLine, hasDeviationCue, hasIntent, intentTitle, isSubstantivePrompt, isHousekeeping, isReply, endsWithQuestion, lastQuestion, issueSummary, matchStep, sentences, similarity, stripMarkdown, tokens, truncate, } from "./text.js";
 const MAX_CHUNK = 256 * 1024;
 const MAX_CONTEXT_ITEMS = 12;
 /**
@@ -17,6 +17,8 @@ export class Engine {
     seq = 0;
     /** The main agent's last words asked the user something. */
     agentAsked = false;
+    /** ...and the question itself. */
+    agentQuestion;
     goalCtx = new Map();
     units = new Map();
     calls = new Map();
@@ -159,7 +161,9 @@ export class Engine {
                 row.diff = n.diff;
             if (n.files?.length && (n.kind === 'edit' || n.kind === 'write'))
                 row.files = n.files;
-            if (n.kind === 'command' && text) {
+            if (n.via)
+                row.via = n.via;
+            if ((n.kind === 'command' || n.via === 'command') && text) {
                 row.command = text.replace(/^(?:\$|PS>)\s?/, '');
                 if (n.detail)
                     row.short = n.detail.replace(/^\$\s?/, '');
@@ -429,7 +433,10 @@ export class Engine {
         }
         // A message sent while the agent is still in its turn is an interjection, not a new task.
         const midTurn = this.run.status === 'working';
-        this.run.status = 'working';
+        // /compact, /model...: no turn follows them, so the session (and its task) stays as it was.
+        const housekeeping = isHousekeeping(text);
+        if (!housekeeping)
+            this.run.status = 'working';
         const cur = this.currentGoal();
         // After the turn, a short message continues the task only if it answers the agent
         // ("yes", "go ahead", or anything after a question); "all done, pushed" is a new card.
@@ -440,18 +447,84 @@ export class Engine {
             this.addChunk(g.id, 'prompt', raw ?? text, ts, 'Prompt');
             return;
         }
-        this.setStatus(cur.id, 'active', ts);
+        if (!midTurn && !housekeeping)
+            return this.startRound(cur, text, ts, raw);
+        if (!housekeeping)
+            return this.interject(cur, text, ts, raw);
+        // A housekeeping command (/compact...) is a note where the task stands, not a message to the agent.
         const target = cur.unit ?? cur.current ?? cur.id;
         const n = this.newNode('activity', target, `You: ${truncate(text, 80)}`, { kind: 'user', status: 'done', startedAt: ts });
         this.addChunk(n.id, 'prompt', raw ?? text, ts, 'User reply');
         cur.lastTextChunk = null;
     }
+    /**
+     * A reply that continues a task after its turn ended starts a new round of it. The reply sits
+     * on the task itself, after the steps so far (and before a plan's steps still to come), keeping
+     * how the round before it ended; the work that follows goes into a step of its own.
+     */
+    startRound(g, text, ts, raw) {
+        const goal = this.touch(g.id);
+        const round = {
+            ...(goal.outcome ? { outcome: goal.outcome } : {}),
+            ...(g.interrupted ? { interrupted: true } : {}),
+            ...(this.agentAsked ? { asked: true } : {}),
+        };
+        this.closeSubtask(g, ts);
+        // The next action picks the next unfinished plan step, or starts a new step (see onToolStart).
+        g.current = null;
+        g.unit = null;
+        g.pending = null;
+        g.lastTextChunk = null;
+        g.interrupted = false;
+        this.userNode(g, text, ts, raw, { round });
+        delete goal.outcome;
+        delete goal.asked;
+        delete goal.question;
+        this.setStatus(g.id, 'active', ts);
+    }
+    /**
+     * A message sent while the agent works: like every message of yours, a node of its own on the
+     * task, after the steps so far. The work that follows goes into a new step, except that a plan
+     * step under way stays the current one until the plan moves on.
+     */
+    interject(g, text, ts, raw) {
+        this.closeSubtask(g, ts);
+        const step = g.current ? this.nodes.get(g.current) : undefined;
+        if (step && step.origin !== 'plan') {
+            if (step.status === 'active')
+                this.setStatus(step.id, 'done', ts);
+            g.current = null;
+            g.unit = null;
+        }
+        g.pending = null;
+        g.lastTextChunk = null;
+        this.userNode(g, text, ts, raw, {});
+        this.setStatus(g.id, 'active', ts);
+    }
+    /** A message of yours on the task itself: after the steps so far, before a plan's steps not started. */
+    userNode(g, text, ts, raw, extra) {
+        const goal = this.touch(g.id);
+        const n = this.newNode('activity', g.id, `You: ${truncate(text, 80)}`, { kind: 'user', status: 'done', startedAt: ts, ...extra });
+        const rest = goal.children.filter((c) => c !== n.id);
+        let at = rest.length;
+        while (at > 0) {
+            const c = this.nodes.get(rest[at - 1]);
+            if (!(c?.type === 'step' && (c.status === 'pending' || c.tentative)))
+                break;
+            at--;
+        }
+        rest.splice(at, 0, n.id);
+        goal.children = rest;
+        this.addChunk(n.id, 'prompt', raw ?? text, ts, 'User reply');
+    }
     // ───────────────────────────── narration
     onText(text, ts, scope) {
         if (!text.trim())
             return;
-        if (!scope)
+        if (!scope) {
             this.agentAsked = endsWithQuestion(text);
+            this.agentQuestion = this.agentAsked ? lastQuestion(text) : undefined;
+        }
         if (scope) {
             const n = this.scopes.get(scope);
             if (n) {
@@ -854,6 +927,7 @@ export class Engine {
                 tool: ev.tool,
                 detail: ev.detail,
                 files: ev.files,
+                ...(ev.via ? { via: ev.via } : {}),
                 status: 'active',
                 startedAt: ev.ts,
             });
@@ -862,7 +936,9 @@ export class Engine {
         if (ev.spawnsAgent)
             this.scopes.set(ev.callId, node.id);
         this.calls.set(ev.callId, { node: node.id, unit, tool: ev.tool, label: ev.label });
-        this.addChunk(node.id, 'tool', ev.raw ?? ev.detail ?? ev.label, ev.ts, ev.label);
+        const chunk = this.addChunk(node.id, 'tool', ev.raw ?? ev.detail ?? ev.label, ev.ts, ev.label);
+        if (ev.parts?.length && ev.parts.every((p) => p.text.length <= MAX_CHUNK))
+            this.chunks[chunk].parts = ev.parts;
         this.bump(unit, 'actions');
         this.addContext(unit, ev);
         const held = ev.spawnsAgent ? this.orphans.get(ev.callId) : undefined;
@@ -1023,6 +1099,17 @@ export class Engine {
             if (g.plan.length === 0 || isLastPlanned || !g.plan.includes(g.current))
                 this.setStatus(g.current, 'done', ts);
         }
+        if (this.agentAsked && !interrupted) {
+            goal.asked = true;
+            if (this.agentQuestion)
+                goal.question = this.agentQuestion;
+            else
+                delete goal.question;
+        }
+        else {
+            delete goal.asked;
+            delete goal.question;
+        }
         // The agent finished its turn: the task is done, unless it was cut short. A follow-up
         // reply reopens it (see onPrompt).
         this.setStatus(g.id, interrupted ? 'waiting' : 'done', ts);

package/dist/core/summary.js

@@ -0,0 +1,41 @@
+/** Nothing new for this long: a run said to be working has gone quiet (as in the web UI). */
+export const QUIET_MS = 5 * 60 * 1000;
+/** A finished run stays 'done' (rather than 'rest') this long. */
+const RECENT_MS = 30 * 60 * 1000;
+export function runSummary(run, nodes, now = Date.now()) {
+    const get = (id) => id === undefined ? undefined : nodes instanceof Map ? nodes.get(id) : nodes[id];
+    const kids = (n) => (n?.children ?? []).map(get).filter((c) => !!c);
+    // Like the UI's descendants(): children, and inside subtasks, theirs.
+    const below = (n, f, acc = []) => {
+        for (const c of kids(n)) {
+            if (f(c))
+                acc.push(c);
+            if (c.type === 'subtask')
+                below(c, f, acc);
+        }
+        return acc;
+    };
+    const openIssue = (s) => below(s, (c) => c.type === 'blocker' && c.status === 'open').length > 0 || (s.stats?.errors ?? 0) - (s.stats?.recovered ?? 0) > 0;
+    const age = run.updatedAt ? now - Date.parse(run.updatedAt) : Infinity;
+    const stale = age > QUIET_MS;
+    const all = nodes instanceof Map ? [...nodes.values()] : Object.values(nodes);
+    const agents = stale ? 0 : all.filter((n) => n.type === 'subtask' && n.origin === 'subagent' && n.status === 'active').length;
+    const out = (state, question) => ({ state, ...(question !== undefined ? { question } : {}), agents, updatedAt: run.updatedAt });
+    const g = get(run.currentGoal) ?? get(run.goals[run.goals.length - 1]);
+    if (run.status === 'working') {
+        if (stale)
+            return out('quiet');
+        const step = get(run.currentStep);
+        return out(step && openIssue(step) ? 'bad' : 'work');
+    }
+    if (g?.status === 'waiting')
+        return out('paused');
+    const ask = g ? below(g, (c) => c.type === 'activity' && c.kind === 'ask' && c.status === 'active')[0] : undefined;
+    if (ask)
+        return out('you', String(ask.title ?? '').replace(/^Ask:\s*/, ''));
+    if (g?.asked)
+        return out('you', g.question ?? '');
+    return out(age < RECENT_MS ? 'done' : 'rest');
+}
+/** The states that want you: a tab you're not looking at flashes when it turns one of these. */
+export const ATTENTION = new Set(['you', 'bad', 'done']);

package/dist/core/text.js

@@ -132,6 +132,10 @@ export function extractPlan(text, requireCue = false) {
     const cue = PLAN_CUE.test(lead);
     if ((!best.numbered || requireCue) && !cue)
         return null;
+    // Bullets that all open with a bold label ("**Rows:** the spotlight...") describe things, they
+    // aren't steps to take.
+    if (!best.numbered && best.items.every((s) => /^\*\*[^*]{1,60}?(?::\*\*|\*\*:)/.test(s.trim())))
+        return null;
     const items = best.items.map(cleanItem).filter((s) => s.length > 1);
     if (items.length < 2)
         return null;
@@ -200,6 +204,10 @@ const HOUSEKEEPING = /^\/(compact|clear|model|config|cost|context|status|help|me
  * A short message that answers the agent rather than giving it something new: an approval,
  * a choice, or anything at all when the agent's last words asked a question.
  */
+/** A slash command that manages the session (/compact, /model...) rather than asking for anything. */
+export function isHousekeeping(text) {
+    return HOUSEKEEPING.test(text.trim());
+}
 export function isReply(text, agentAsked) {
     const t = text.trim();
     // Housekeeping commands never start a task; any other slash command is a new request.
@@ -215,6 +223,11 @@ export function isReply(text, agentAsked) {
 export function endsWithQuestion(text) {
     return /\?\s*(\*+|_+|\)|")?\s*$/.test(text.trim());
 }
+/** The question the agent's words end with: their last sentence, without its formatting. */
+export function lastQuestion(text) {
+    const q = sentences(text).at(-1);
+    return q && /\?\W*$/.test(q) ? truncate(q.replace(/(?<=\?)\W*$/, ''), 200) : undefined;
+}
 export function isSubstantivePrompt(text) {
     const t = text.trim();
     const words = t.split(/\s+/).filter(Boolean).length;

package/dist/server/server.js

@@ -8,7 +8,7 @@ import { readFile, readdir, stat } from 'node:fs/promises';
 import { extname, normalize, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { RunSession } from "./session.js";
-import { ClaudeSessionSource, findSession, listSessions } from "../sources/claude-sessions.js";
+import { ClaudeSessionSource, LIVE_MS, findSession, listSessions } from "../sources/claude-sessions.js";
 const WEB_DIR = fileURLToPath(new URL('../../web/', import.meta.url));
 const SRC_DIR = fileURLToPath(new URL('../', import.meta.url));
 const STARTED = Date.now();
@@ -33,7 +33,6 @@ async function codeChangedSince(t) {
     return false;
 }
 const MAX_BODY = 512 * 1024 * 1024;
-const LIVE_MS = 3 * 60 * 1000;
 const TYPES = {
     '.html': 'text/html; charset=utf-8',
     '.js': 'text/javascript; charset=utf-8',
@@ -43,11 +42,19 @@ const TYPES = {
     '.png': 'image/png',
     '.ico': 'image/x-icon',
 };
+/** How often tab states are refreshed regardless of new events (they change with time too). */
+const TICK_MS = 15_000;
+/** A run no page has shown or listed for this long is closed (when it can be opened again). */
+export const IDLE_CLOSE_MS = 10 * 60 * 1000;
 export class LucidlyServer {
     runs = new Map();
     byKey = new Map();
     seq = 0;
     server = null;
+    watchers = new Set();
+    /** Open event streams per run, ended when the run closes. */
+    streams = new Map();
+    ticker = null;
     port = 0;
     cwd;
     wantPort;
@@ -69,6 +76,8 @@ export class LucidlyServer {
                         s.off('error', fail);
                         this.server = s;
                         this.port = s.address().port;
+                        this.ticker = setInterval(() => this.tick(), TICK_MS);
+                        this.ticker.unref();
                         ok();
                     });
                 });
@@ -82,6 +91,8 @@ export class LucidlyServer {
         throw new Error(`No free port from ${this.wantPort}`);
     }
     async close() {
+        if (this.ticker)
+            clearInterval(this.ticker);
         for (const r of this.runs.values())
             r.close();
         this.server?.closeAllConnections?.();
@@ -111,8 +122,66 @@ export class LucidlyServer {
         r.close();
         this.runs.delete(id);
         this.byKey.delete(r.key);
+        for (const res of this.streams.get(id) ?? [])
+            res.end();
+        this.streams.delete(id);
+        // Tabs holding it hear that it's gone.
+        for (const w of this.watchers)
+            if (w.runs.has(id))
+                this.pushTabs(w);
         return true;
     }
+    /** Whether some page (other than `except`) shows the run, or has it in a tab. */
+    watched(run, except) {
+        if (run.shownBy(except))
+            return true;
+        for (const w of this.watchers)
+            if (w.client !== except && w.runs.has(run.id))
+                return true;
+        return false;
+    }
+    /**
+     * A tab closed (or switched to another session) on page `client`: the run stops, unless another
+     * tab or page still has it.
+     */
+    release(id, client) {
+        const run = this.runs.get(id);
+        if (!run)
+            return { closed: false };
+        if (client)
+            for (const w of this.watchers)
+                if (w.client === client)
+                    w.runs.delete(id);
+        if (this.watched(run, client))
+            return { closed: false };
+        return { closed: this.closeRun(id) };
+    }
+    /** Tells a page's tabs what changed in the states of their runs. */
+    pushTabs(w, now = Date.now()) {
+        const changed = {};
+        for (const id of w.runs) {
+            const run = this.runs.get(id);
+            const s = run ? run.summary(now) : { gone: true };
+            const json = JSON.stringify(s);
+            if (w.last.get(id) === json)
+                continue;
+            w.last.set(id, json);
+            changed[id] = s;
+        }
+        if (Object.keys(changed).length)
+            w.send({ runs: changed });
+    }
+    /** States that change with time alone (working → quiet, done → rest), and closing idle runs. */
+    tick(now = Date.now()) {
+        for (const w of this.watchers)
+            this.pushTabs(w, now);
+        for (const run of [...this.runs.values()]) {
+            if (this.watched(run))
+                run.lastWatched = now;
+            else if (run.reopenable && now - run.lastWatched > IDLE_CLOSE_MS)
+                this.closeRun(run.id);
+        }
+    }
     // ───────────────────────────── HTTP
     hostOk(req) {
         const host = (req.headers.host ?? '').toLowerCase();
@@ -152,10 +221,13 @@ export class LucidlyServer {
             if (!run)
                 return send(res, 404, { error: 'no such run' });
             const [, , action, arg] = m;
-            if (!action && req.method === 'DELETE')
-                return send(res, 200, { closed: this.closeRun(run.id) });
+            // With the page's id: only if no other tab or page has the run (see release).
+            if (!action && req.method === 'DELETE') {
+                const client = url.searchParams.get('client');
+                return send(res, 200, client ? this.release(run.id, client) : { closed: this.closeRun(run.id) });
+            }
             if (action === 'stream')
-                return this.stream(req, res, run);
+                return this.stream(req, res, run, url.searchParams.get('client') ?? undefined);
             if (action === 'raw' && arg) {
                 if (!run.engine.nodes.has(arg))
                     return send(res, 404, { error: 'no such node' });
@@ -183,6 +255,14 @@ export class LucidlyServer {
         if (path === '/api/runs' && req.method === 'GET') {
             return send(res, 200, { runs: [...this.runs.values()].map((r) => r.info()) });
         }
+        // A page's session tabs: the states of the runs they hold, live (event "tabs").
+        if (path === '/api/tabs/stream' && req.method === 'GET') {
+            const client = url.searchParams.get('client');
+            if (!client)
+                return send(res, 400, { error: 'client required' });
+            const ids = (url.searchParams.get('runs') ?? '').split(',').filter(Boolean);
+            return this.tabStream(req, res, client, ids);
+        }
         if (path === '/api/sessions' && req.method === 'GET') {
             const all = url.searchParams.get('scope') === 'all';
             const sessions = await listSessions({ cwd: all ? undefined : this.cwd, limit: all ? 60 : 30 });
@@ -223,21 +303,44 @@ export class LucidlyServer {
         }
         return send(res, 404, { error: 'not found' });
     }
-    stream(req, res, run) {
-        res.writeHead(200, {
-            'content-type': 'text/event-stream; charset=utf-8',
-            'cache-control': 'no-store',
-            connection: 'keep-alive',
-            'x-accel-buffering': 'no',
-        });
-        res.write('retry: 2000\n\n');
+    stream(req, res, run, client) {
+        sseHead(res);
+        let set = this.streams.get(run.id);
+        if (!set)
+            this.streams.set(run.id, (set = new Set()));
+        set.add(res);
         const unsubscribe = run.subscribe((event, data) => {
             res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
-        });
+        }, client);
         const ping = setInterval(() => res.write(': ping\n\n'), 15000);
         req.on('close', () => {
             clearInterval(ping);
             unsubscribe();
+            this.streams.get(run.id)?.delete(res);
+        });
+    }
+    tabStream(req, res, client, ids) {
+        sseHead(res);
+        // A page has one tab stream: a new one (its tabs changed) replaces the old.
+        for (const w of this.watchers)
+            if (w.client === client)
+                this.watchers.delete(w);
+        const w = { client, runs: new Set(ids), last: new Map(), send: (data) => res.write(`event: tabs\ndata: ${JSON.stringify(data)}\n\n`) };
+        this.watchers.add(w);
+        const offs = ids.map((id) => this.runs.get(id)?.onChange(() => this.pushTabs(w))).filter((f) => !!f);
+        this.pushTabs(w);
+        const ping = setInterval(() => res.write(': ping\n\n'), 15000);
+        req.on('close', () => {
+            clearInterval(ping);
+            for (const off of offs)
+                off();
+            this.watchers.delete(w);
+            const now = Date.now();
+            for (const id of ids) {
+                const run = this.runs.get(id);
+                if (run)
+                    run.lastWatched = now;
+            }
         });
     }
     async static(res, path) {
@@ -261,6 +364,15 @@ export class LucidlyServer {
         res.end(body);
     }
 }
+function sseHead(res) {
+    res.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-store',
+        connection: 'keep-alive',
+        'x-accel-buffering': 'no',
+    });
+    res.write('retry: 2000\n\n');
+}
 function send(res, status, body) {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
     res.end(JSON.stringify(body));

package/dist/server/session.js

@@ -3,9 +3,12 @@
  * State lives in memory; saving writes the event log, loading replays it.
  */
 import { Engine } from "../core/engine.js";
+import { runSummary } from "../core/summary.js";
 export const SAVE_FORMAT = 'lucidly-run';
 export const SAVE_VERSION = 1;
 const FLUSH_MS = 120;
+/** Listeners to a run's summary (session tabs) hear about changes at most this often. */
+const CHANGE_MS = 250;
 export class RunSession {
     id;
     key;
@@ -14,8 +17,13 @@ export class RunSession {
     engine = new Engine();
     events = [];
     source;
-    subs = new Set();
+    /** Live subscribers, each with the page (client id) it belongs to, when it said. */
+    subs = new Map();
     timer = null;
+    changeTimer = null;
+    changeSubs = new Set();
+    /** When a page last showed or listed this run (for closing runs nobody looks at any more). */
+    lastWatched = Date.now();
     constructor(id, source, opts = {}) {
         this.id = id;
         this.source = source;
@@ -35,16 +43,22 @@ export class RunSession {
         this.engine.applyAll(evs);
         if (this.subs.size && !this.timer)
             this.timer = setTimeout(() => this.flush(), FLUSH_MS);
+        if (this.changeSubs.size && !this.changeTimer)
+            this.changeTimer = setTimeout(() => {
+                this.changeTimer = null;
+                for (const f of this.changeSubs)
+                    f();
+            }, CHANGE_MS);
     }
     flush() {
         this.timer = null;
         const patch = this.engine.takePatch();
         if (!patch)
             return;
-        for (const s of this.subs)
+        for (const s of this.subs.keys())
             s('patch', patch);
     }
-    subscribe(send) {
+    subscribe(send, client) {
         // Bring existing subscribers up to date first, so the new snapshot and their state agree.
         if (this.timer) {
             clearTimeout(this.timer);
@@ -53,9 +67,35 @@ export class RunSession {
         else {
             this.engine.takePatch();
         }
-        this.subs.add(send);
+        this.subs.set(send, client);
+        this.lastWatched = Date.now();
         send('snapshot', this.engine.snapshot());
-        return () => this.subs.delete(send);
+        return () => {
+            this.subs.delete(send);
+            this.lastWatched = Date.now();
+        };
+    }
+    /** Calls `f` (throttled) whenever new events arrive. */
+    onChange(f) {
+        this.changeSubs.add(f);
+        return () => this.changeSubs.delete(f);
+    }
+    /** Whether a page other than `except` has this run open (its full stream). */
+    shownBy(except) {
+        for (const c of this.subs.values())
+            if (c === undefined || c !== except)
+                return true;
+        return false;
+    }
+    /** Whether it can be opened again from its file (so closing it loses nothing). */
+    get reopenable() {
+        return !!this.source?.path;
+    }
+    /** The run's state for its tab, and its name: the session's title, or else its first request. */
+    summary(now = Date.now()) {
+        const r = this.engine.run;
+        const first = r.goals.length ? this.engine.nodes.get(r.goals[0])?.title : undefined;
+        return { ...runSummary(r, this.engine.nodes, now), title: r.title ?? first ?? this.label };
     }
     info() {
         const r = this.engine.run;
@@ -69,6 +109,7 @@ export class RunSession {
             eventCount: r.eventCount,
             updatedAt: r.updatedAt,
             subscribers: this.subs.size,
+            ...(this.source?.path ? { path: this.source.path } : {}),
         };
     }
     save() {
@@ -95,7 +136,10 @@ export class RunSession {
     close() {
         if (this.timer)
             clearTimeout(this.timer);
+        if (this.changeTimer)
+            clearTimeout(this.changeTimer);
         this.source?.stop();
         this.subs.clear();
+        this.changeSubs.clear();
     }
 }

package/dist/sources/claude-sessions.js

@@ -15,6 +15,8 @@ export function projectsDir() {
 export function encodeCwd(cwd) {
     return cwd.replace(/[^a-zA-Z0-9]/g, '-');
 }
+/** A session written to within this long counts as live (the agent is, or was just, at work). */
+export const LIVE_MS = 3 * 60 * 1000;
 async function readSlice(path, start, length) {
     const fh = await open(path, 'r');
     try {
@@ -26,9 +28,20 @@ async function readSlice(path, start, length) {
         await fh.close();
     }
 }
+// Descriptions by path, reused while the file is unchanged: the session list refreshes every few
+// seconds while it is open, and only the sessions written to since are read again.
+const described = new Map();
 /** Cheap metadata: read the head for cwd/first prompt and the tail for the latest title. */
 export async function describeSession(path) {
     const st = await stat(path);
+    const known = described.get(path);
+    if (known && known.mtime === st.mtimeMs && known.size === st.size)
+        return known;
+    const info = await readDescription(path, st);
+    described.set(path, info);
+    return info;
+}
+async function readDescription(path, st) {
     const info = {
         id: basename(path, '.jsonl'),
         path,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vale-dinap/lucidly",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "See what your AI agent is doing, at a glance.",
   "keywords": [
     "claude",