@oddessentials/agent-guild 1.17.0 → 1.19.0

package/src/manager/session-history.mjs

@@ -10,18 +10,26 @@ import { fileURLToPath } from 'node:url';
 import { resolveCommand, buildSpawnSpec, runSpec } from './command-resolver.mjs';
 import { toIso } from './usage.mjs';
 import { antigravityUserConversation } from '../report/hooks.mjs';
-import { ANTIGRAVITY_ID, transcriptFile, readAntigravityTranscript, historyError } from './antigravity-transcript.mjs';
+import { ANTIGRAVITY_ID, transcriptFile, transcriptMessage, historyError } from './antigravity-transcript.mjs';
+import {
+  JSONL_READERS, DOCKER_VISIBLE, GROK_TURN_ACTIVITY, readJsonlPage, readAntigravityTranscript, readDockerConversation, checkedFile,
+  claudePrompt, codexMessage, grokPromptChunk, zstdDecoder,
+} from './history-transcripts.mjs';
 
 export const HISTORY_TTL_MS = 5 * 1000;
 export const DEFAULT_LIMIT = 100;
 export const MAX_LIMIT = 500;
 const HEAD_BYTES = 256 * 1024;
+const TAIL_BYTES = 256 * 1024;
 const MAX_TITLE = 120;
 const MAX_ID = 200;
 const MAX_WALK_DEPTH = 4;
 
 export class HistoryError extends Error {}
 
+export const DETAIL_SOURCES = new Set(['claude', 'codex', 'antigravity', 'grok', 'docker']);
+const TRANSCRIPT_ROOTS = { claude: 'projects', codex: 'sessions', grok: 'sessions' };
+
 const TAG_RE = /^<[a-z][a-z0-9_-]*[\s>]/i;
 
 function shortPath(file) {
@@ -29,18 +37,17 @@ function shortPath(file) {
   return file.startsWith(home) ? `~${file.slice(home.length)}` : file;
 }
 
-/** One line of prompt text, or null for an empty or tool-inserted (`<tag>…`) message. */
-function promptTitle(text) {
+/** One line of prompt text, or null for an empty one. */
+function lineTitle(text) {
   if (typeof text !== 'string') return null;
   const clean = text.replace(/\s+/g, ' ').trim();
-  if (!clean || TAG_RE.test(clean)) return null;
-  return clean.slice(0, MAX_TITLE);
+  return clean ? clean.slice(0, MAX_TITLE) : null;
 }
 
-function contentText(content) {
-  if (typeof content === 'string') return content;
-  if (!Array.isArray(content)) return '';
-  return content.map((part) => (typeof part === 'string' ? part : part && typeof part.text === 'string' ? part.text : '')).filter(Boolean).join('\n');
+/** For text with no marker saying who wrote it: null also for a tool-inserted (`<tag>…`) message. */
+function promptTitle(text) {
+  const title = lineTitle(text);
+  return title && !TAG_RE.test(title) ? title : null;
 }
 
 function parseLines(text) {
@@ -56,7 +63,7 @@ async function readHead(file, bytes = HEAD_BYTES) {
   if (file.endsWith('.zst')) {
     if (typeof zlib.createZstdDecompress !== 'function') return null;
     const source = fs.createReadStream(file);
-    const inflate = source.pipe(zlib.createZstdDecompress());
+    const inflate = source.pipe(zstdDecoder());
     const chunks = [];
     let size = 0;
     try {
@@ -79,6 +86,21 @@ async function readHead(file, bytes = HEAD_BYTES) {
   }
 }
 
+/** The whole records in the last bytes of a file, and the offset the first of them starts at. */
+async function readTail(file, size, bytes = TAIL_BYTES) {
+  if (size <= HEAD_BYTES) return { text: '', start: size };
+  const length = Math.min(bytes, size - HEAD_BYTES);
+  const handle = await fs.promises.open(file, 'r');
+  try {
+    const { bytesRead, buffer } = await handle.read(Buffer.alloc(length), 0, length, size - length);
+    const data = buffer.subarray(0, bytesRead);
+    const first = data.indexOf(10) + 1;
+    return { text: data.subarray(first).toString('utf8'), start: size - length + first };
+  } finally {
+    await handle.close();
+  }
+}
+
 async function readDir(dir) {
   try {
     return await fs.promises.readdir(dir, { withFileTypes: true });
@@ -127,7 +149,7 @@ export class FileMemo {
     const known = this.entries.get(file);
     if (known && known.size === stat.size && known.mtimeMs === stat.mtimeMs) return known.entry;
     let entry = null;
-    try { entry = await parse(); } catch { /* unreadable or not a transcript */ }
+    try { entry = await parse(known && known.size <= stat.size ? known.entry : null); } catch { /* unreadable or not a transcript */ }
     this.entries.set(file, { size: stat.size, mtimeMs: stat.mtimeMs, entry });
     return entry;
   }
@@ -155,22 +177,51 @@ export function claudeConfigDir(env = process.env) {
   return (env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude')).normalize('NFC');
 }
 
-function claudeEntry(id, text, stat) {
+/** Claude Code's title records in whole lines of `text`, which starts at offset `base`, and where those lines end. */
+function claudeTitles(text, base) {
+  const titles = { custom: null, ai: null, end: base };
+  let at = base;
+  for (const line of text.split('\n').slice(0, -1)) {
+    let record = null;
+    try { record = JSON.parse(line); } catch { /* a foreign line */ }
+    if (record?.type === 'custom-title' && typeof record.customTitle === 'string' && record.customTitle.trim()) titles.custom = { text: record.customTitle, at };
+    if (record?.type === 'ai-title' && typeof record.aiTitle === 'string' && record.aiTitle.trim()) titles.ai = { text: record.aiTitle, at };
+    at += Buffer.byteLength(line) + 1;
+  }
+  titles.end = at;
+  return titles;
+}
+
+/**
+ * The newest title record by position in the file. Only the start and end are
+ * read; a title found earlier still counts while it lies in the unread middle
+ * of a file that has only grown.
+ */
+function newestTitle(head, tail, before, key) {
+  const kept = before?.titles?.[key];
+  const unread = kept && kept.at >= head.end && kept.at < tail.start ? kept : null;
+  return [head[key], unread, tail[key]].filter(Boolean).reduce((newest, title) => (title.at > newest.at ? title : newest), { at: -1, text: null });
+}
+
+function claudeEntry(id, text, tail, stat, before) {
   let cwd = null;
   let startedAt = null;
-  let title = null;
+  let prompt = null;
   let seenUser = false;
-  for (const record of parseLines(text)) {
+  const records = parseLines(text);
+  for (const record of records) {
     if (!record || typeof record !== 'object') continue;
     if (cwd === null && typeof record.cwd === 'string') cwd = record.cwd;
     if (startedAt === null && record.timestamp) startedAt = record.timestamp;
-    if (record.type === 'custom-title' && typeof record.customTitle === 'string' && record.customTitle.trim()) title = record.customTitle;
     if (record.type !== 'user' || record.isSidechain === true) continue;
     seenUser = true;
-    if (title === null) title = promptTitle(contentText(record.message?.content));
+    prompt ??= lineTitle(claudePrompt(record));
   }
   if (cwd === null && !seenUser) return null;
-  return cleanEntry({ id, title, cwd, startedAt, updatedAt: stat.mtime });
+  const head = claudeTitles(text, 0), end = { ...claudeTitles(tail.text, tail.start), start: tail.start };
+  const custom = newestTitle(head, end, before, 'custom'), ai = newestTitle(head, end, before, 'ai');
+  const titles = { custom: custom.text === null ? null : custom, ai: ai.text === null ? null : ai };
+  return { ...cleanEntry({ id, title: titles.custom?.text ?? titles.ai?.text ?? prompt, cwd, startedAt, updatedAt: stat.mtime }), titles };
 }
 
 /** Sessions under `<dir>/projects/<folder>/<id>.jsonl`; sub-agent transcripts sit in sub-folders and are not listed. */
@@ -188,8 +239,8 @@ export async function listClaudeSessions(dir, memo = new FileMemo()) {
       if (!stat) continue;
       seen.add(file);
       const id = item.name.slice(0, -'.jsonl'.length);
-      const entry = await memo.entry(file, stat, async () => claudeEntry(id, await readHead(file), stat));
-      if (entry) entries.push(entry);
+      const entry = await memo.entry(file, stat, async (before) => claudeEntry(id, await readHead(file), await readTail(file, stat.size), stat, before));
+      if (entry) entries.push({ ...entry, file });
     }
   }
   memo.prune(root, seen);
@@ -202,18 +253,6 @@ export function codexHome(env = process.env) {
   return env.CODEX_HOME || path.join(os.homedir(), '.codex');
 }
 
-function codexPrompt(record) {
-  const payload = record?.payload;
-  if (!payload || typeof payload !== 'object') return null;
-  if (record.type === 'event_msg') {
-    if (payload.type === 'user_message') return promptTitle(payload.message);
-    if (payload.type === 'item_completed' && payload.item?.type === 'UserMessage') return promptTitle(contentText(payload.item.content));
-    return null;
-  }
-  if (record.type === 'response_item' && payload.type === 'message' && payload.role === 'user') return promptTitle(contentText(payload.content));
-  return null;
-}
-
 function codexEntry(text, stat) {
   const records = parseLines(text);
   const meta = records.find((r) => r?.type === 'session_meta')?.payload;
@@ -223,7 +262,8 @@ function codexEntry(text, stat) {
   if (meta.parent_thread_id || (meta.thread_source && meta.thread_source !== 'user')) return null;
   let title = null;
   for (const record of records) {
-    title = codexPrompt(record);
+    const message = codexMessage(record);
+    title = message?.role === 'user' ? lineTitle(message.text) : null;
     if (title) break;
   }
   return cleanEntry({ id, title, cwd: meta.cwd, startedAt: meta.timestamp ?? records[0]?.timestamp, updatedAt: stat.mtime });
@@ -238,11 +278,25 @@ async function walk(dir, depth, onFile) {
   }
 }
 
+async function codexThreadNames(dir, memo) {
+  const file = path.join(dir, 'session_index.jsonl');
+  const stat = await statFile(file);
+  if (!stat) return new Map();
+  return (await memo.entry(file, stat, async () => {
+    const names = new Map();
+    for (const record of parseLines(await fs.promises.readFile(file, 'utf8'))) {
+      if (typeof record?.id === 'string' && typeof record.thread_name === 'string' && record.thread_name.trim()) names.set(record.id, record.thread_name);
+    }
+    return names;
+  })) ?? new Map();
+}
+
 /** Rollouts under `<dir>/sessions/YYYY/MM/DD/rollout-*.jsonl`, uncompressed or zstd-compressed. Sub-agent threads are skipped. */
 export async function listCodexSessions(dir, memo = new FileMemo()) {
   const root = path.join(dir, 'sessions');
   const entries = [];
   const seen = new Set();
+  const names = await codexThreadNames(dir, memo);
   await walk(root, MAX_WALK_DEPTH, async (file, name) => {
     if (!/^rollout-.*\.jsonl(\.zst)?$/.test(name)) return;
     const stat = await statFile(file);
@@ -252,7 +306,7 @@ export async function listCodexSessions(dir, memo = new FileMemo()) {
       const head = await readHead(file);
       return head === null ? null : codexEntry(head, stat);
     });
-    if (entry) entries.push(entry);
+    if (entry) entries.push({ ...entry, title: cleanEntry({ id: entry.id, title: names.get(entry.id) }).title ?? entry.title, file });
   });
   memo.prune(root, seen);
   return dedupe(entries);
@@ -299,8 +353,7 @@ function antigravityEntry(id, text, stat) {
   let first;
   try { first = JSON.parse((text ?? '').split('\n', 1)[0]); } catch { return null; }
   if (!antigravityUserConversation(first) || typeof first.content !== 'string') return null;
-  const request = first.content.match(/<USER_REQUEST>([\s\S]*?)<\/USER_REQUEST>/)?.[1];
-  return cleanEntry({ id, title: promptTitle(request), startedAt: first.created_at, updatedAt: stat.mtime });
+  return cleanEntry({ id, title: lineTitle(transcriptMessage(first)?.text), startedAt: first.created_at, updatedAt: stat.mtime });
 }
 
 /** Legacy fallback. Multiple cache paths for one id cannot identify a launch folder. */
@@ -358,7 +411,7 @@ export async function listAntigravitySessions(dir, memo = new FileMemo(), { plat
       const workspaces = summary ? antigravityWorkspaces(summary.workspace_uris, platform) : [];
       const cwd = workspaces.length === 1 ? workspaces[0] : workspaces.length ? null : folders.get(entry.id) ?? null;
       const title = promptTitle(summary?.title) || promptTitle(summary?.preview) || entry.title;
-      entries.push({ ...entry, title, cwd, ...(withStatus ? { workspaces: workspaces.length ? workspaces : cwd ? [cwd] : [] } : {}) });
+      entries.push({ ...entry, title, cwd, file, ...(withStatus ? { workspaces: workspaces.length ? workspaces : cwd ? [cwd] : [] } : {}) });
     }
   }
   memo.prune(root, seen);
@@ -393,21 +446,19 @@ async function loadSqlite() {
   return sqlite;
 }
 
-// A session's title, else its first user message; the newest message dates it. A sub-agent's session has a parent.
+// A session's title, else the first message its preview shows if that is the user's; the newest message dates it.
+// A sub-agent's session has a parent. No JSON function reads a row larger than $max.
 const DOCKER_SESSIONS_SQL = `
   select s.id, s.title, s.created_at, s.working_dir,
-    (select i.message_json from session_items i where i.session_id = s.id and i.item_type = 'message' order by i.position limit 1) as first_message,
-    (select max(json_extract(i.message_json, '$.created_at')) from session_items i where i.session_id = s.id) as updated_at
+    (select case when visible and json_extract(message_json, '$.role') = 'user' then json_extract(message_json, '$.content') end
+      from (select position, message_json, ${DOCKER_VISIBLE} as visible from session_items i where i.session_id = s.id and i.item_type = 'message')
+      where visible is not 0 order by position limit 1) as first_prompt,
+    (select max(case when octet_length(i.message_json) <= $max then json_extract(i.message_json, '$.created_at') end)
+      from session_items i where i.session_id = s.id) as updated_at
   from sessions s where s.parent_id is null order by s.created_at desc limit ${MAX_LIMIT}`;
 
 function dockerEntry(row) {
-  let title = typeof row.title === 'string' && row.title.trim() ? row.title : null;
-  if (!title && typeof row.first_message === 'string') {
-    try {
-      const message = JSON.parse(row.first_message);
-      if (message?.role === 'user') title = promptTitle(contentText(message.content));
-    } catch { /* not a message */ }
-  }
+  const title = typeof row.title === 'string' && row.title.trim() ? row.title : lineTitle(row.first_prompt);
   return cleanEntry({ id: row.id, title, cwd: row.working_dir, startedAt: row.created_at, updatedAt: row.updated_at ?? row.created_at });
 }
 
@@ -419,7 +470,7 @@ export async function listDockerSessions(dir) {
   let db = null;
   try {
     db = new DatabaseSync(file, { readOnly: true });
-    return dedupe(db.prepare(DOCKER_SESSIONS_SQL).all().map(dockerEntry).filter(Boolean));
+    return dedupe(db.prepare(DOCKER_SESSIONS_SQL).all({ max: HEAD_BYTES }).map(dockerEntry).filter(Boolean));
   } catch (err) {
     throw new HistoryError(`${shortPath(file)} could not be read: ${err.message}`);
   } finally {
@@ -441,19 +492,22 @@ async function grokBucketCwd(bucket) {
   return (await readText(path.join(bucket, '.cwd')))?.trim() || null;
 }
 
+/** The first prompt Grok Build shows, its chunks joined as the preview joins them. */
 function grokPrompt(text) {
-  const parts = [];
-  let promptId;
+  let turn = null;
+  const title = () => (turn && !turn.hidden ? lineTitle(turn.parts.join('')) : null);
   for (const record of parseLines(text)) {
-    const update = record?.params?.update;
-    if (update?.sessionUpdate !== 'user_message_chunk' || update.content?.type !== 'text') continue;
-    if (update.content._meta?.bash_command || update._meta?.host_turn === true) continue;
-    const id = record.params._meta?.promptId ?? null;
-    if (parts.length && id !== promptId) break;
-    promptId = id;
-    parts.push(update.content.text);
+    const chunk = grokPromptChunk(record);
+    if (turn && (chunk ? chunk.key !== turn.key : GROK_TURN_ACTIVITY.has(record?.params?.update?.sessionUpdate))) {
+      if (title()) return title();
+      turn = null;
+    }
+    if (!chunk) continue;
+    turn ??= { key: chunk.key, hidden: false, parts: [] };
+    if (chunk.hidden) turn.hidden = true;
+    else if (chunk.text !== null) turn.parts.push(chunk.text);
   }
-  return promptTitle(parts.join(''));
+  return title();
 }
 
 async function grokEntry(folder, summary, stat, bucketCwd) {
@@ -492,7 +546,7 @@ export async function listGrokSessions(dir, memo = new FileMemo()) {
       if (!stat) continue;
       seen.add(file);
       const entry = await memo.entry(file, stat, async () => grokEntry(folder, JSON.parse(await readText(file)), stat, cwd));
-      if (entry) entries.push(entry);
+      if (entry) entries.push({ ...entry, file: path.join(folder, 'updates.jsonl') });
     }
   }
   memo.prune(root, seen);
@@ -526,9 +580,11 @@ export class SessionHistory {
    * @param {object} [opts.env]
    * @param {number} [opts.ttlMs]
    * @param {object} [opts.readers]  session listers by source, replaceable in tests
+   * @param {ReturnType<import('./card-names.mjs').createCardNames>|null} [opts.names]  the names given to cards, by tool session id
    */
-  constructor({ registry, env = process.env, platform = process.platform, ttlMs = HISTORY_TTL_MS, readers = {} } = {}) {
+  constructor({ registry, env = process.env, platform = process.platform, ttlMs = HISTORY_TTL_MS, readers = {}, names = null } = {}) {
     this.registry = registry;
+    this.names = names;
     this.env = env;
     this.platform = platform;
     this.ttlMs = ttlMs;
@@ -550,20 +606,33 @@ export class SessionHistory {
     const n = Math.min(MAX_LIMIT, Math.max(1, Math.floor(Number(limit)) || DEFAULT_LIMIT));
     const snapshot = await this.snapshot(provider, account);
     const search = typeof query === 'string' ? query.trim().toLowerCase().slice(0, 500) : '';
-    const sessions = snapshot.sessions.filter((entry) =>
-      (!cwd || (entry.workspaces ?? [entry.cwd]).some((folder) => sameHistoryFolder(folder, cwd, this.platform)))
-      && (!search || [entry.id, entry.title, ...(entry.workspaces ?? [entry.cwd])].join('\n').toLowerCase().includes(search)));
+    const sessions = snapshot.sessions.map(({ file, titles, ...entry }) => ({ ...entry, name: this.names?.get(provider.id, account.id, entry.id) ?? null }))
+      .filter((entry) =>
+        (!cwd || (entry.workspaces ?? [entry.cwd]).some((folder) => sameHistoryFolder(folder, cwd, this.platform)))
+        && (!search || [entry.id, entry.name, entry.title, ...(entry.workspaces ?? [entry.cwd])].join('\n').toLowerCase().includes(search)));
     return { ...snapshot, total: sessions.length, sessions: sessions.slice(0, n) };
   }
 
   async detail(provider, account, id, cursor) {
-    if (provider.history !== 'antigravity') throw historyError(400, 'history_detail_unsupported', 'This tool has no conversation preview.');
-    if (!ANTIGRAVITY_ID.test(id)) throw historyError(400, 'bad_history_id', 'Invalid conversation id.');
+    const source = provider.history;
+    if (!DETAIL_SOURCES.has(source)) throw historyError(400, 'history_detail_unsupported', 'This tool has no conversation preview.');
+    if (typeof id !== 'string' || cleanEntry({ id })?.id !== id || (source === 'antigravity' && !ANTIGRAVITY_ID.test(id))) {
+      throw historyError(400, 'bad_history_id', 'Invalid conversation id.');
+    }
     // Revalidate membership, even if the client still has an older list open.
     const snapshot = await this._read(provider, account);
-    if (!snapshot.sessions.some((s) => s.id === id)) throw historyError(404, 'history_unavailable', 'This conversation transcript is unavailable.');
+    const entry = snapshot.sessions.find((s) => s.id === id);
+    if (!entry) throw historyError(404, 'history_unavailable', 'This conversation transcript is unavailable.');
     const env = { ...this.env, ...provider.env, ...account.env };
-    return readAntigravityTranscript(antigravityDir(env, this.platform), id, cursor);
+    const dir = SessionHistory.sourceDir(source, env, this.platform);
+    if (source === 'docker') return readDockerConversation({ dir, id, cursor, loadSqlite });
+    if (source === 'antigravity') return readAntigravityTranscript(dir, id, cursor);
+    if (typeof entry.file !== 'string') throw historyError(404, 'history_unavailable', 'This conversation transcript is unavailable.');
+    const root = path.join(dir, TRANSCRIPT_ROOTS[source]);
+    // Codex may have compressed or decompressed the rollout since it was listed.
+    const other = entry.file.endsWith('.zst') ? entry.file.slice(0, -4) : `${entry.file}.zst`;
+    const file = await checkedFile(root, entry.file).catch((err) => (source === 'codex' ? checkedFile(root, other) : Promise.reject(err)));
+    return readJsonlPage({ source, id, file, cursor, ...JSONL_READERS[source] });
   }
 
   snapshot(provider, account) {

package/src/manager/session-manager.mjs

@@ -64,9 +64,16 @@ export class SessionManager extends EventEmitter {
    * @param {string|null} [opts.shimDir]  folder with the agent-guild-report launchers, put first on PATH
    * @param {import('./self-update.mjs').SelfUpdate|null} [opts.selfUpdate]  the manager's own upgrade
    * @param {import('./github.mjs').GitHub|null} [opts.github]
+   * @param {ReturnType<import('./card-names.mjs').createCardNames>|null} [opts.cardNames]  names given to cards, by tool session id
    */
-  constructor({ registry, baseEnv, getApiUrl, sessionDefaults = {}, shimDir = null, selfUpdate = null, github = null, sessionHooks = null, store = null }) {
+  constructor({ registry, baseEnv, getApiUrl, sessionDefaults = {}, shimDir = null, selfUpdate = null, github = null, sessionHooks = null, store = null, cardNames = null }) {
     super();
+    this.cardNames = cardNames;
+    /** Each card's latest choice of name for the tool session it holds, in the order the choices were made. */
+    this.nameChoices = new WeakMap();
+    this.nameOrder = 0;
+    /** Tool session → the order of the newest choice written to the store for it. */
+    this.namesWritten = new Map();
     this.registry = registry;
     this.baseEnv = baseEnv;
     this.getApiUrl = getApiUrl;
@@ -144,11 +151,12 @@ export class SessionManager extends EventEmitter {
     if (!current) throw httpError(404, `unknown provider "${provider.id}"`, 'unknown_provider');
     const signIn = this.registry.account(current, account);
     this.prepareAccount(provider, signIn, { hooksSupplied: hooks.args.length > 0 });
-    const sessionName = cleanName(name)
-      || (current.accounts.length > 1 ? `${provider.tool} · ${signIn.label}` : null)
-      || (runShell && this.registry.shellsFor(provider).shells.length > 1 ? `${provider.tool} · ${runShell.label}` : null);
+    const defaultName = (current.accounts.length > 1 ? `${provider.tool} · ${signIn.label}` : null)
+      || (runShell && this.registry.shellsFor(provider).shells.length > 1 ? `${provider.tool} · ${runShell.label}` : null)
+      || provider.tool;
+    const given = cleanName(name) || (resumeId ? this.cardNames?.get(provider.id, signIn.id, resumeId) : null) || null;
     const extraEnv = hooks.env ? { ...runShell?.env, ...hooks.env } : runShell?.env;
-    const options = { provider, cwd: workDir, cols, rows, name: sessionName, resume: resumeId, account: signIn, reporting: hooks.reporting, extraEnv };
+    const options = { provider, cwd: workDir, cols, rows, name: given ?? defaultName, defaultName, named: given !== null, resume: resumeId, account: signIn, reporting: hooks.reporting, extraEnv };
     if (runShell?.multiplexer) return this._withMultiplexerStart(provider.id, runShell.id, () => this._startMultiplexer(options, runShell, args || []));
     const spawnSpec = this.registry.spawnSpec(provider, args || [], resumeId, hooks.args, runShell);
     const session = this._spawn({ ...options, spawnSpec });
@@ -209,7 +217,7 @@ export class SessionManager extends EventEmitter {
     }
     this._track(session, { spawnSpec, mux, shell, card: {
       id, reportToken, provider: provider.id, account: account.id, shell: shell.id,
-      muxName, name: session.name, cwd: session.cwd, createdAt: session.createdAt,
+      muxName, name: session.name, defaultName: session.defaultName, named: session.named, cwd: session.cwd, createdAt: session.createdAt,
       // Herdr's request arguments belong to its client and must survive rebinding.
       // Tmux's request arguments belong to the already-running inner session.
       ...(shell.id === 'herdr' ? { args: [...args] } : {}),
@@ -247,13 +255,44 @@ export class SessionManager extends EventEmitter {
     this._saveCards();
     session.on('exit', () => this._checkMultiplexer(session, tracked));
     session.on('changed', () => {
-      if (card.name === session.name && (card.context?.compactions ?? 0) === session.context.compactions && (card.context?.resets ?? 0) === session.context.resets) return;
+      if (card.name === session.name && card.named === session.named && (card.context?.compactions ?? 0) === session.context.compactions && (card.context?.resets ?? 0) === session.context.resets) return;
       card.name = session.name;
+      card.named = session.named;
       card.context = { ...session.context };
       this._saveCards();
     });
   }
 
+  /**
+   * The store holds what a card last chose for the tool session it holds: its name, or none for its default. A
+   * card's choice is written once, when it is made: a rename, a new tool session, or the card's start. One whose
+   * write failed is written again on a later change, unless a newer choice for that tool session was written since,
+   * so a card shown again never puts back a name another card replaced. A card nobody named writes nothing.
+   */
+  _keepCardName(session) {
+    // The page's identity for the tool session a card holds; a resumed card knows it before the tool reports.
+    const toolSessionId = session.toolSessionId ?? session.resume;
+    if (!this.cardNames || session.task !== null || !toolSessionId || !session.nameChosen) return;
+    const account = session.account?.id ?? 'default';
+    const key = `${session.provider.id}\0${account}\0${toolSessionId}`;
+    const name = session.named ? session.name : null;
+    let choice = this.nameChoices.get(session);
+    if (choice?.key !== key || choice.name !== name) {
+      choice = { key, name, order: ++this.nameOrder, written: false };
+      this.nameChoices.set(session, choice);
+    }
+    if (choice.written) return;
+    if ((this.namesWritten.get(key) ?? 0) > choice.order) {
+      choice.written = true;
+      return;
+    }
+    // set() and delete() say whether the store now holds the choice; get() cannot tell an unreadable store from one without it.
+    const saved = name ? this.cardNames.set(session.provider.id, account, toolSessionId, name) : this.cardNames.delete(session.provider.id, account, toolSessionId);
+    if (!saved) return;
+    choice.written = true;
+    this.namesWritten.set(key, choice.order);
+  }
+
   _saveCards() {
     // A stopping manager leaves the file as it is, for the next one to bring the cards back.
     if (!this.store || this.restoring || this.closing) return;
@@ -309,12 +348,13 @@ export class SessionManager extends EventEmitter {
     const spawnSpec = this.registry.spawnSpec(provider, shell.id === 'herdr' ? card.args ?? [] : [], null, [], mux.named);
     const session = this._spawn({
       provider, spawnSpec: null, cwd: typeof card.cwd === 'string' ? card.cwd : os.homedir(), name: card.name, account,
+      defaultName: typeof card.defaultName === 'string' ? card.defaultName : undefined, named: card.named === true,
       id: card.id, reportToken: card.reportToken, dropEnv: mux.dropEnv, extraEnv: shell.env,
       createdAt: typeof card.createdAt === 'string' && !Number.isNaN(Date.parse(card.createdAt)) ? card.createdAt : undefined,
       context: card.context,
       multiplexer: { label: shell.label, attach: shell.multiplexer.attach.replaceAll('{name}', card.muxName), reattachable: true },
     });
-    this._track(session, { spawnSpec, mux, shell, card: { ...card, name: session.name, cwd: session.cwd, createdAt: session.createdAt } });
+    this._track(session, { spawnSpec, mux, shell, card: { ...card, name: session.name, defaultName: session.defaultName, named: session.named, cwd: session.cwd, createdAt: session.createdAt } });
   }
 
   /** Attach a stopped tmux or herdr session's card to its multiplexer session again, keeping its id and report token. */
@@ -711,7 +751,7 @@ export class SessionManager extends EventEmitter {
   }
 
   _spawn({
-    provider, description = this.registry.describe(provider), spawnSpec, cwd, cols, rows, name, resume = null, task = null, installKind = null, installPath = null, account = null,
+    provider, description = this.registry.describe(provider), spawnSpec, cwd, cols, rows, name, defaultName, named = false, resume = null, task = null, installKind = null, installPath = null, account = null,
     extraEnv = null, dropEnv = null, clone = null, reporting = null, multiplexer = null,
     id = newId(), reportToken = crypto.randomBytes(16).toString('hex'), createdAt, context = null, multiplexerInstall = null,
   }) {
@@ -731,6 +771,8 @@ export class SessionManager extends EventEmitter {
         cols: clampDimension(cols, 120, 2, 1000),
         rows: clampDimension(rows, 32, 1, 500),
         name,
+        defaultName,
+        named,
         reportToken,
         resume,
         task,
@@ -745,7 +787,9 @@ export class SessionManager extends EventEmitter {
       throw httpError(500, `could not start ${provider.tool}: ${err.message}`, 'spawn_failed');
     }
 
+    this._keepCardName(session);
     session.on('changed', () => {
+      this._keepCardName(session);
       if (this.sessions.has(id)) this.emit('event', { type: 'session.updated', session: session.toJSON() });
     });
     session.on('warning', (msg) => console.warn(`[session ${id}] ${msg}`));

package/src/manager/session.mjs

@@ -6,8 +6,7 @@ import { EventEmitter } from 'node:events';
 import crypto from 'node:crypto';
 import headless from '@xterm/headless';
 import serializeAddon from '@xterm/addon-serialize';
-import { killWindowsTree } from './command-resolver.mjs';
-import { loadPty } from './pty.mjs';
+import { loadPty, closeConsole, releasePty } from './pty.mjs';
 import { sessionLabel } from '../../web/activity-favicon.js';
 
 const { Terminal } = headless;
@@ -68,6 +67,8 @@ export class Session extends EventEmitter {
    * @param {number} opts.cols
    * @param {number} opts.rows
    * @param {string} [opts.name]
+   * @param {string} [opts.defaultName]  the name a card has when nobody named it
+   * @param {boolean} [opts.named]  the name was given, so it is kept for the tool session
    * @param {string|null} [opts.resume]  id of the tool's own session being resumed
    * @param {string|null} [opts.task]    "install" for a package install, "upgrade" for the manager's own, "clone" for a GitHub clone, else null
    * @param {{id: string, label: string}|null} [opts.account]  the tool sign-in the session runs under
@@ -84,7 +85,11 @@ export class Session extends EventEmitter {
     super();
     this.id = opts.id;
     this.provider = opts.provider;
-    this.name = cleanName(opts.name) || opts.provider.tool;
+    this.defaultName = cleanName(opts.defaultName) || opts.provider.tool;
+    this.name = cleanName(opts.name) || this.defaultName;
+    this.named = opts.named === true && this.name !== this.defaultName;
+    /** Someone gave or changed this card's name, its default included. */
+    this.nameChosen = opts.named === true;
     this.resume = opts.resume ?? null;
     this.task = opts.task ?? null;
     this.account = opts.account ?? null;
@@ -98,6 +103,7 @@ export class Session extends EventEmitter {
     this.activityIdleMs = opts.activityIdleMs ?? 2500;
     this.doneAgentLingerMs = opts.doneAgentLingerMs ?? 15000;
     this.killGraceMs = opts.killGraceMs ?? 4000;
+    this._killed = false;
     this.reportingTimeoutMs = opts.reportingTimeoutMs ?? 30000;
     this.reporting = REPORTING_STATES.has(opts.reporting?.state) ? { state: opts.reporting.state, reason: opts.reporting.reason ?? null } : null;
     this._reportingTimer = null;
@@ -198,6 +204,7 @@ export class Session extends EventEmitter {
       useConpty: true,
     });
     this.pty = proc;
+    this._killed = false;
     proc.onData((data) => { if (this.pty === proc) this._onData(data); });
     proc.onExit(({ exitCode, signal }) => { if (this.pty === proc) this._onExit(exitCode, signal); });
   }
@@ -244,6 +251,7 @@ export class Session extends EventEmitter {
 
   _onExit(exitCode, signal) {
     clearTimeout(this._killTimer);
+    if (process.platform === 'win32') releasePty(this.pty);
     this._resolveExited();
     if (this.disposed) return;
     this.exitedAt ??= new Date().toISOString();
@@ -412,16 +420,18 @@ export class Session extends EventEmitter {
 
   /**
    * End the process. On macOS and Linux: hang-up first, force after a grace
-   * period. On Windows: end the whole process tree at once, except for a
-   * multiplexer's client, whose server is its child there and must outlive
-   * it. node-pty's own Windows kill first asks a helper process for the
-   * console's process list, and when that helper fails it waits a fixed
-   * five seconds.
+   * period. On Windows: close the session's console, which ends every process
+   * attached to it; a multiplexer's server and anything started detached
+   * outlive it.
    */
   kill({ graceMs = this.killGraceMs } = {}) {
     if (this.status !== 'running') return;
     if (process.platform === 'win32') {
-      this._killWindowsTree();
+      // At most once per pty: node-pty 1.2.0-beta.15 closes the pseudoconsole again on a second close before the
+      // exit watcher runs, which corrupts this process's heap (microsoft/node-pty#983).
+      if (this._killed) return;
+      this._killed = true;
+      closeConsole(this.pty);
       return;
     }
     const force = () => { try { this.pty.kill('SIGKILL'); } catch { /* gone */ } };
@@ -431,15 +441,6 @@ export class Session extends EventEmitter {
     this._killTimer.unref?.();
   }
 
-  _killWindowsTree() {
-    const fallback = () => {
-      if (this.status === 'running') { try { this.pty.kill(); } catch { /* gone */ } }
-    };
-    const pid = this.pty.pid;
-    if (!pid) return fallback();
-    killWindowsTree(pid, (err) => { if (err) fallback(); }, { tree: !this.multiplexer });
-  }
-
   /**
    * Detach everything. A still-running process gets the normal hang-up and
    * is force-killed after the grace period if it ignores it.
@@ -461,6 +462,8 @@ export class Session extends EventEmitter {
     const clean = cleanName(name);
     if (!clean) return;
     this.name = clean;
+    this.named = clean !== this.defaultName;
+    this.nameChosen = true;
     this._changed();
   }
 

package/src/mcp/server.mjs

@@ -84,6 +84,13 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: { session_id: sessionId }, required: ['session_id'], additionalProperties: false },
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
   },
+  {
+    name: 'fireworks',
+    title: 'Fireworks over the Yard',
+    description: 'Launch fireworks over the Yard on every screen connected to Agent Guild. Use it to celebrate something the person cares about, such as tests, a build or a release that passed. Says how many pages saw them.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  },
 ];
 
 const INPUT_TOOL = {
@@ -309,6 +316,10 @@ export function createToolHandlers(client, { allowInput = false } = {}) {
       const { session } = await client.api(`/sessions/${checkId(id)}/stop`, { method: 'POST', session: id });
       return text({ stopped: true, session: summarize(session) });
     },
+    async fireworks() {
+      const { pages } = await client.api('/yard/fireworks', { method: 'POST' });
+      return text({ launched: true, pages, ...(pages ? {} : { message: 'No page is open to see them. The person can open Agent Guild and choose the Yard.' }) });
+    },
   };
   if (allowInput) {
     handlers.send_input = async ({ session_id: id, text: typed, submit = true }) => {