Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
perf(agents): skip session-title reads of unchanged transcripts
enes6ae9ebb8377d
diff --git a/CLAUDE.md b/CLAUDE.mdindex c1507d84f..793b54d8c 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2354,6 +2354,11 @@ command-bearing opens; this does not add a human-confirm dialog or change mobileover `pty.readSessionName`. `TerminalNode` polls it (~4 s) **only once this node's own sessionIdis known** and **while the title still auto-tracks** (`data.titleAuto`, default true on agentnodes), and adopts it as the `title`. `term.onTitleChange` now feeds the `session` chip only.+ **A poll of an unchanged transcript reads no bytes**: the local read is gated on the resolved+ path's (size, mtime) (`titleCache`, bounded at 500, a failed tail read never cached), and the+ remote one (`main/remote-title-reader.ts`) on the remote context tail's `offsetFor` for the SAME+ path — that offset is the file size at the tail's last read, so a remote `/rename` lands within+ the tail's idle backoff (≤ 10 s); an untracked session (offset unknown) always reads.- **title → session (write):** the moment the user renames the node by hand (header rename box /✦ AI-name / sidebar / command palette → all funnel through `applyManualTitle` or`renameSession`), `titleAuto` flips to **false** (polling stops overwriting) and the chosen namediff --git a/src/core/transcript-reader.test.ts b/src/core/transcript-reader.test.tsindex 3d8d2e588..dbf7c3841 100644--- a/src/core/transcript-reader.test.ts+++ b/src/core/transcript-reader.test.ts@@ -1,5 +1,5 @@import fs from 'fs'-import { afterEach, describe, expect, it, vi } from 'vitest'+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'import {parseTranscriptLines,pickSessionName,@@ -312,3 +312,46 @@ describe('readChatWindow — byte windows read from a real file', () => {expect(await readChatWindow('/nonexistent/nt/x.jsonl', { before: null, maxBytes: 65536 })).toBeUndefined()})})++// The title poll runs every 4–15 s per agent node, and each poll used to read + parse a 128 KB+// tail. The name can only change when the transcript does, so an unchanged (size, mtime) must+// answer from the cache without touching the file's bytes — while a /rename (the file grows)+// must still be picked up on the next poll.+describe('readSessionName — unchanged transcripts are not re-read', () => {+ const sid = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'+ const custom = (t: string) => JSON.stringify({ type: 'custom-title', customTitle: t, sessionId: sid })+ let home: string+ let file: string++ beforeEach(() => {+ home = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-title-cache-'))+ vi.spyOn(os, 'homedir').mockReturnValue(home)+ const dir = path.join(home, '.claude', 'projects', '-proj')+ fs.mkdirSync(dir, { recursive: true })+ file = path.join(dir, `${sid}.jsonl`)+ fs.writeFileSync(file, custom('First') + '\n')+ })++ afterEach(() => {+ vi.restoreAllMocks()+ fs.rmSync(home, { recursive: true, force: true })+ })++ // readSmallTail reads a small file with readFile and a large one with open+read — spy on both,+ // so "no tail read" holds whichever branch the fixture size lands on.+ it('does not re-read an unchanged transcript', async () => {+ const readFile = vi.spyOn(fs.promises, 'readFile')+ const open = vi.spyOn(fs.promises, 'open')+ expect(await readSessionName(sid)).toBe('First')+ const reads = readFile.mock.calls.length + open.mock.calls.length+ expect(reads).toBeGreaterThan(0)+ expect(await readSessionName(sid)).toBe('First')+ expect(readFile.mock.calls.length + open.mock.calls.length).toBe(reads)+ })++ it('re-reads after the transcript changes (e.g. /rename)', async () => {+ expect(await readSessionName(sid)).toBe('First')+ fs.appendFileSync(file, custom('Second') + '\n')+ expect(await readSessionName(sid)).toBe('Second')+ })+})diff --git a/src/core/transcript-reader.ts b/src/core/transcript-reader.tsindex b18d64ce8..338f75c97 100644--- a/src/core/transcript-reader.ts+++ b/src/core/transcript-reader.ts@@ -472,6 +472,13 @@ export function setRemoteTranscriptReader(remoteReader = fn}+// Title polls hit this every 4–15 s per agent node. The name can only change when the transcript+// does, so (size, mtime) gates the 128 KB tail read. Keyed by the RESOLVED path (the account is+// already folded into it). Bounded: oldest entries go first. A failed tail read is not cached — a+// transient error must not pin a null title until the file next changes.+const TITLE_CACHE_MAX = 500+const titleCache = new Map<string, { size: number; mtimeMs: number; name: string | null }>()+export async function readSessionName(sessionId: string,accountId?: string@@ -486,9 +493,17 @@ export async function readSessionName(// Stale cache entries are healed inside resolveTranscriptPath (access-checked per hit).const p = await resolveTranscriptPath(sessionId, accountId)if (!p) return null+ const st = await fs.promises.stat(p).catch(() => null)+ const hit = st ? titleCache.get(p) : undefined+ if (st && hit && hit.size === st.size && hit.mtimeMs === st.mtimeMs) return hit.nameconst tail = await readSmallTail(p, TITLE_TAIL_BYTES)- if (!tail) return null- return pickSessionName(tail)+ const name = tail ? pickSessionName(tail) : null+ if (st && tail !== undefined) {+ titleCache.delete(p)+ titleCache.set(p, { size: st.size, mtimeMs: st.mtimeMs, name })+ if (titleCache.size > TITLE_CACHE_MAX) titleCache.delete(titleCache.keys().next().value!)+ }+ return name}// Durable resolver by working directory: Claude stores a project's transcripts underdiff --git a/src/main/index.ts b/src/main/index.tsindex d4ebed12f..7b45cefbd 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -235,6 +235,7 @@ import {import { createRemoteContextTail } from './remote-context-tail'import { createRemoteSubagentTail } from './remote-subagent-tail'import { RemoteFile, type RemoteFileRef } from './remote-ssh/remote-file'+import { createRemoteTitleReader } from './remote-title-reader'import {checkMasterArgs,childArgs,@@ -2465,12 +2466,19 @@ app.whenReady().then(async () => {// project's agent runs on the remote host, so its transcript is NOT under the local// `~/.claude/projects` — without this, `/rename` never reached the node title on remote nodes// (and the poll re-scanned the local root every 4s for nothing). Returning null for an unknown- // sessionId keeps every local node on the local reader.- setRemoteTranscriptReader(async (sessionId) => {- const ref = remoteTranscriptBySession.get(sessionId)- if (!ref) return null- return { text: await remoteFile.readTail(ref, TITLE_TAIL_BYTES) }- })+ // sessionId keeps every local node on the local reader. The ssh tail read is skipped while the+ // remote context tail's offset for the SAME path has not moved (the file has not grown); a+ // tail tracking a different path answers "unknown", which always reads.+ setRemoteTranscriptReader(+ createRemoteTitleReader({+ refFor: (sessionId) => remoteTranscriptBySession.get(sessionId),+ offsetFor: (sessionId) =>+ remoteContextTail.pathFor(sessionId) === remoteTranscriptBySession.get(sessionId)?.path+ ? remoteContextTail.offsetFor(sessionId)+ : null,+ readTail: (ref) => remoteFile.readTail(ref, TITLE_TAIL_BYTES)+ })+ )// toolUseIds whose remote subagent file resolution was cancelled (PostToolUse / node close// arrived before the file appeared) — checked by the async resolver to avoid a late track.// Bounded by `remoteSubagentResolving`: a cancel flag is only added (and only matters) while adiff --git a/src/main/remote-title-reader.test.ts b/src/main/remote-title-reader.test.tsnew file mode 100644index 000000000..6b80f5d82--- /dev/null+++ b/src/main/remote-title-reader.test.ts@@ -0,0 +1,31 @@+import { describe, it, expect, vi } from 'vitest'+import { createRemoteTitleReader } from './remote-title-reader'++const ref = { path: '/h/.claude/projects/x/s1.jsonl', controlPath: '/cp', conn: {} } as never++describe('createRemoteTitleReader', () => {+ it('returns null for a session that is not remote', async () => {+ const r = createRemoteTitleReader({ refFor: () => undefined, offsetFor: () => null, readTail: vi.fn() })+ expect(await r('s1')).toBeNull()+ })++ it('reuses the last tail while the tail-tracked offset has not moved', async () => {+ let offset: number | null = 100+ const readTail = vi.fn().mockResolvedValue('tail-A')+ const r = createRemoteTitleReader({ refFor: () => ref, offsetFor: () => offset, readTail })+ expect(await r('s1')).toEqual({ text: 'tail-A' })+ expect(await r('s1')).toEqual({ text: 'tail-A' })+ expect(readTail).toHaveBeenCalledTimes(1)+ offset = 200+ readTail.mockResolvedValue('tail-B')+ expect(await r('s1')).toEqual({ text: 'tail-B' })+ expect(readTail).toHaveBeenCalledTimes(2)+ })++ it('always reads when the offset is unknown (tail not tracking it)', async () => {+ const readTail = vi.fn().mockResolvedValue('t')+ const r = createRemoteTitleReader({ refFor: () => ref, offsetFor: () => null, readTail })+ await r('s1'); await r('s1')+ expect(readTail).toHaveBeenCalledTimes(2)+ })+})diff --git a/src/main/remote-title-reader.ts b/src/main/remote-title-reader.tsnew file mode 100644index 000000000..43ae27ceb--- /dev/null+++ b/src/main/remote-title-reader.ts@@ -0,0 +1,28 @@+import type { RemoteFileRef } from './remote-ssh/remote-file'++/** Remote session-title reader: a 128 KB tail read over ssh per poll, per remote agent node,+ * skipped while the remote context tail reports the file has not grown (its read offset IS the+ * file size at its last read). Unknown offset ⇒ always read. Bounded by live remote sessions:+ * an entry goes when its session stops being remote or stops being tracked by the tail. */+export function createRemoteTitleReader(deps: {+ refFor(sessionId: string): RemoteFileRef | undefined+ offsetFor(sessionId: string): number | null+ readTail(ref: RemoteFileRef): Promise<string>+}): (sessionId: string) => Promise<{ text: string } | null> {+ const cache = new Map<string, { offset: number; path: string; text: string }>()+ return async (sessionId) => {+ const ref = deps.refFor(sessionId)+ if (!ref) {+ // Not a remote session — null is the signal for core to use the local reader.+ cache.delete(sessionId)+ return null+ }+ const offset = deps.offsetFor(sessionId)+ const hit = cache.get(sessionId)+ if (offset !== null && hit && hit.offset === offset && hit.path === ref.path) return { text: hit.text }+ const text = await deps.readTail(ref)+ if (offset !== null) cache.set(sessionId, { offset, path: ref.path, text })+ else cache.delete(sessionId)+ return { text }+ }+}