@phnx-labs/agents-cli 1.20.89 → 1.20.91

package/dist/lib/session/favorites.js

@@ -0,0 +1,101 @@
+/**
+ * Favorited (starred) sessions — the durable "keep this one handy" mark a human
+ * puts on a session, deliberately kept OUT of the session index.
+ *
+ * `sessions.db` is a rebuildable CACHE: a reindex or a schema bump throws its
+ * rows away and re-derives them from the transcripts on disk. A favorite is not
+ * derivable from a transcript — it is a human's choice — so a column there would
+ * be silently lost on the next rebuild. It lives in `~/.agents/.history/` instead,
+ * next to the actor sidecars, which is never pruned.
+ *
+ * One flat set of session ids. The id is the transcript's own uuid, so it is
+ * stable and machine-independent — but the file is NOT synced today: session sync
+ * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Favorites
+ * are therefore per-machine; carrying them across the fleet would mean adding
+ * them to the sync manifest, which this does not do.
+ *
+ * Reads are memoized against the file's mtime — the picker asks `isFavorite` once
+ * per rendered row, and re-reading a JSON file per row on every keystroke is the
+ * kind of cost that makes a TUI feel broken.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getHistoryDir } from '../state.js';
+export function favoritesFilePath() {
+    return path.join(getHistoryDir(), 'favorites.json');
+}
+/** Memoized parse, invalidated by the file's mtime+size (another process — or
+ *  another machine's sync — can rewrite it under us). */
+let cache = null;
+function statKey(file) {
+    try {
+        const st = fs.statSync(file);
+        return `${st.mtimeMs}:${st.size}`;
+    }
+    catch {
+        return 'absent';
+    }
+}
+/** Drop the memoized read. Tests that write the file directly need this; nothing
+ *  in the CLI does, because every mutation here refreshes the cache itself. */
+export function clearFavoritesCache() {
+    cache = null;
+}
+/**
+ * Every favorited session id. Empty (never throws) when the file is absent,
+ * unreadable, or malformed — a corrupt favorites file must not take down
+ * `agents sessions`.
+ */
+export function listFavorites() {
+    const file = favoritesFilePath();
+    const key = statKey(file);
+    if (cache && cache.key === key)
+        return cache.ids;
+    let ids = new Set();
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (Array.isArray(parsed?.sessionIds)) {
+            ids = new Set(parsed.sessionIds.filter((id) => typeof id === 'string' && id.length > 0));
+        }
+    }
+    catch {
+        // absent / unreadable / malformed — an empty set is the honest answer
+    }
+    cache = { key, ids };
+    return ids;
+}
+export function isFavorite(sessionId) {
+    if (!sessionId)
+        return false;
+    return listFavorites().has(sessionId);
+}
+/** Atomic write (tmp + rename) so a concurrent reader never sees a half file. */
+function writeFavorites(ids) {
+    const file = favoritesFilePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const body = { version: 1, sessionIds: [...ids].sort() };
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(body, null, 2) + '\n');
+    fs.renameSync(tmp, file);
+    cache = { key: statKey(file), ids };
+}
+/**
+ * Set (or clear) the favorite mark on a session. Returns the resulting state, so
+ * a caller can report it without a second read. A no-op write is skipped, which
+ * keeps the file's mtime — and every other process's memoized read — untouched.
+ */
+export function setFavorite(sessionId, on) {
+    const ids = new Set(listFavorites());
+    if (ids.has(sessionId) === on)
+        return on;
+    if (on)
+        ids.add(sessionId);
+    else
+        ids.delete(sessionId);
+    writeFavorites(ids);
+    return on;
+}
+/** Flip the mark; returns the new state (`true` = now favorited). */
+export function toggleFavorite(sessionId) {
+    return setFavorite(sessionId, !isFavorite(sessionId));
+}

package/dist/lib/session/highlights.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Session highlight extractors.
+ *
+ * Pure derivations over a session's `SessionEvent[]` that power the "what did
+ * this session use and produce" sections of both renders of a session — the
+ * picker quick preview (`sessions-picker.ts`) and the full summary
+ * (`render.ts`). One module, two consumers, so the panes never drift.
+ *
+ * Skills/hooks/links are no-I/O. `extractRepos` touches the filesystem (a
+ * bounded `.git` walk over a handful of candidate dirs) and is the only
+ * non-pure function here.
+ */
+import type { SessionEvent } from './types.js';
+import { type FileChange } from './digest.js';
+export interface SkillUse {
+    name: string;
+    count: number;
+}
+/**
+ * Skills invoked during the session, from `Skill` tool calls. Claude and Kimi
+ * both name the tool `Skill` and carry the skill id in `args.skill` (plugin
+ * skills surface here too — a plugin-provided skill is invoked through the
+ * same tool). Sorted by count desc, then name.
+ */
+export declare function extractSkills(events: SessionEvent[]): SkillUse[];
+export interface HookUse {
+    /** Hook name as configured, e.g. `SessionStart:startup`. */
+    name: string;
+    /** Lifecycle event, e.g. `SessionStart`. */
+    event?: string;
+    /** How many times it fired. */
+    count: number;
+    /** How many firings failed (non-`hook_success` records). */
+    failed: number;
+}
+/**
+ * Hooks that fired during the session, folded from `hook` events (parsed from
+ * Claude's `hook_success`/`hook_error`/… attachment records; other harnesses
+ * don't record firings in their transcripts, so they yield an empty list).
+ * Sorted by count desc, then name.
+ */
+export declare function extractHooks(events: SessionEvent[]): HookUse[];
+export type LinkKind = 'linear' | 'jira' | 'github' | 'gitlab' | 'other';
+export interface SessionLink {
+    kind: LinkKind;
+    url: string;
+    /** Short display label: `RUSH-2076`, `PR#1755`, `owner/repo#123`, host. */
+    label: string;
+}
+/**
+ * Links mentioned in user/assistant messages, classified (Linear/Jira/GitHub/
+ * GitLab), deduped by URL AND by label (a session that quotes the same PR in
+ * five messages shows it once), first-seen order. Capped so a link-heavy
+ * session can't flood the pane.
+ */
+export declare function extractLinks(events: SessionEvent[]): SessionLink[];
+export type ArtifactBucket = 'artifacts' | 'plans' | 'reports' | 'docs';
+export interface ProducedArtifact {
+    /** Absolute (or session-relative) path of the created file. */
+    path: string;
+    basename: string;
+    bucket: ArtifactBucket;
+}
+/**
+ * Documents/files the session CREATED, from the already-classified changes
+ * (callers classify once — this never re-derives). Keeps the ones a human
+ * browses later: anything under `.agents/artifacts|plans|reports/`, plus other
+ * `*.md`/`*.html` creations. Source/config churn (the bulk of `+N`) stays in
+ * the Changes line.
+ */
+export declare function extractArtifacts(changes: FileChange[]): ProducedArtifact[];
+/**
+ * Repos the session worked in, from the directories its file paths live under
+ * (a bounded `.git` walk-up; a `.git` FILE counts too — that's the worktree
+ * layout). Names are repo dir basenames, first-seen order, capped.
+ *
+ * Relative paths resolve against the SESSION's cwd only — when it is unknown
+ * (e.g. kimi rows carry no cwd today) they are skipped: resolving them against
+ * the viewer's process cwd attributes the session to whatever repo the CLI
+ * happens to run in, which is a wrong answer, not a degraded one.
+ */
+export declare function extractRepos(events: SessionEvent[], cwd?: string): string[];

package/dist/lib/session/highlights.js

@@ -0,0 +1,251 @@
+/**
+ * Session highlight extractors.
+ *
+ * Pure derivations over a session's `SessionEvent[]` that power the "what did
+ * this session use and produce" sections of both renders of a session — the
+ * picker quick preview (`sessions-picker.ts`) and the full summary
+ * (`render.ts`). One module, two consumers, so the panes never drift.
+ *
+ * Skills/hooks/links are no-I/O. `extractRepos` touches the filesystem (a
+ * bounded `.git` walk over a handful of candidate dirs) and is the only
+ * non-pure function here.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { isNoisePath } from './digest.js';
+/**
+ * Skills invoked during the session, from `Skill` tool calls. Claude and Kimi
+ * both name the tool `Skill` and carry the skill id in `args.skill` (plugin
+ * skills surface here too — a plugin-provided skill is invoked through the
+ * same tool). Sorted by count desc, then name.
+ */
+export function extractSkills(events) {
+    const counts = new Map();
+    for (const e of events) {
+        if (e.type !== 'tool_use' || e._local)
+            continue;
+        if (e.tool !== 'Skill')
+            continue;
+        const name = e.args?.skill ?? e.args?.name;
+        if (typeof name !== 'string' || !name.trim())
+            continue;
+        const key = name.trim();
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([name, count]) => ({ name, count }))
+        .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+/**
+ * Hooks that fired during the session, folded from `hook` events (parsed from
+ * Claude's `hook_success`/`hook_error`/… attachment records; other harnesses
+ * don't record firings in their transcripts, so they yield an empty list).
+ * Sorted by count desc, then name.
+ */
+export function extractHooks(events) {
+    const byName = new Map();
+    for (const e of events) {
+        if (e.type !== 'hook')
+            continue;
+        const name = e.hookName?.trim() || e.hookEvent?.trim() || 'hook';
+        const existing = byName.get(name);
+        if (existing) {
+            existing.count++;
+            if (e.success === false)
+                existing.failed++;
+        }
+        else {
+            byName.set(name, {
+                name,
+                event: e.hookEvent,
+                count: 1,
+                failed: e.success === false ? 1 : 0,
+            });
+        }
+    }
+    return [...byName.values()].sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+/** Bare URL scan over message text; trailing punctuation stripped. Backticks
+ * and ellipses excluded so markdown-wrapped or truncated URLs don't leak in. */
+const URL_RE = /https?:\/\/[^\s"'`()<>\]\\…]+/g;
+/** A routable host: dotted domain (optionally :port). localhost/IPs-of-one-segment
+ * and markdown garbage (`…`) are not Links-section material. */
+const HOST_RE = /^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}(:\d+)?$/i;
+function classifyLink(url) {
+    let m;
+    // Linear: https://linear.app/<workspace>/issue/RUSH-2076/slug
+    if ((m = url.match(/https?:\/\/linear\.app\/[\w-]+\/issue\/([A-Z]{2,6}-\d+)/))) {
+        return { kind: 'linear', url, label: m[1] };
+    }
+    // Jira: https://<host>.atlassian.net/browse/PROJ-123 (or /jira/browse/)
+    if ((m = url.match(/https?:\/\/[\w.-]*(?:atlassian\.net|jira[\w.-]*)\/browse\/([A-Z]{2,10}-\d+)/))) {
+        return { kind: 'jira', url, label: m[1] };
+    }
+    // GitHub: PR / issue / repo
+    if ((m = url.match(/https?:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/pull\/(\d+)/))) {
+        return { kind: 'github', url, label: `PR#${m[2]}` };
+    }
+    if ((m = url.match(/https?:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/issues\/(\d+)/))) {
+        return { kind: 'github', url, label: `${m[1]}#${m[2]}` };
+    }
+    if ((m = url.match(/https?:\/\/github\.com\/([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/))) {
+        return { kind: 'github', url, label: m[1] };
+    }
+    // GitLab: MR / issue
+    if ((m = url.match(/https?:\/\/(gitlab\.com|[\w.-]*gitlab[\w.-]*)\/(.+?)\/-\/merge_requests\/(\d+)/))) {
+        return { kind: 'gitlab', url, label: `${m[2]}!${m[3]}` };
+    }
+    if ((m = url.match(/https?:\/\/(gitlab\.com|[\w.-]*gitlab[\w.-]*)\/(.+?)\/-\/issues\/(\d+)/))) {
+        return { kind: 'gitlab', url, label: `${m[2]}#${m[3]}` };
+    }
+    const host = url.match(/^https?:\/\/([^/?]+)/)?.[1];
+    if (!host || !HOST_RE.test(host))
+        return undefined;
+    return { kind: 'other', url, label: host };
+}
+const MAX_LINKS = 12;
+/**
+ * Links mentioned in user/assistant messages, classified (Linear/Jira/GitHub/
+ * GitLab), deduped by URL AND by label (a session that quotes the same PR in
+ * five messages shows it once), first-seen order. Capped so a link-heavy
+ * session can't flood the pane.
+ */
+export function extractLinks(events) {
+    const seenUrl = new Set();
+    const seenLabel = new Set();
+    const out = [];
+    for (const e of events) {
+        if (e.type !== 'message' || !e.content)
+            continue;
+        // Harness-injected scaffolding (bash wrappers, system reminders) carries
+        // URLs that aren't conversation references — same exclusion the rest of
+        // the pipeline applies.
+        if (e._synthetic)
+            continue;
+        for (const raw of e.content.match(URL_RE) ?? []) {
+            const url = raw.replace(/[.,;:)\]`]+$/, '');
+            if (seenUrl.has(url))
+                continue;
+            seenUrl.add(url);
+            const link = classifyLink(url);
+            if (!link || seenLabel.has(link.label))
+                continue;
+            seenLabel.add(link.label);
+            out.push(link);
+            if (out.length >= MAX_LINKS)
+                return out;
+        }
+    }
+    return out;
+}
+const ARTIFACT_EXT_RE = /\.(md|markdown|html?)$/i;
+const MAX_ARTIFACTS = 12;
+/**
+ * Documents/files the session CREATED, from the already-classified changes
+ * (callers classify once — this never re-derives). Keeps the ones a human
+ * browses later: anything under `.agents/artifacts|plans|reports/`, plus other
+ * `*.md`/`*.html` creations. Source/config churn (the bulk of `+N`) stays in
+ * the Changes line.
+ */
+export function extractArtifacts(changes) {
+    const out = [];
+    for (const ch of changes) {
+        if (ch.op !== 'created')
+            continue;
+        const p = ch.path;
+        if (isNoisePath(p))
+            continue;
+        const norm = p.replace(/\\/g, '/');
+        let bucket;
+        if (/\/\.agents\/artifacts\//.test(norm))
+            bucket = 'artifacts';
+        else if (/\/\.agents\/plans\//.test(norm) || /\/plans\/[^/]+\.md$/i.test(norm))
+            bucket = 'plans';
+        else if (/\/\.agents\/reports\//.test(norm))
+            bucket = 'reports';
+        else if (ARTIFACT_EXT_RE.test(norm))
+            bucket = 'docs';
+        if (!bucket)
+            continue;
+        out.push({ path: p, basename: path.posix.basename(norm), bucket });
+        if (out.length >= MAX_ARTIFACTS)
+            break;
+    }
+    return out;
+}
+// ── Repos ─────────────────────────────────────────────────────────────────────
+/** Candidate dirs to probe for a `.git` root, and the walk depth per dir. */
+const MAX_REPO_PROBES = 12;
+const REPO_WALK_DEPTH = 6;
+/** A walk-up that lands here overshot the workspace — never a "repo worked in". */
+function isOvershotRoot(dir) {
+    return dir === '/' || dir === os.tmpdir() || dir === os.homedir();
+}
+function repoRootFrom(dir) {
+    let cur = dir;
+    for (let i = 0; i < REPO_WALK_DEPTH; i++) {
+        try {
+            if (fs.existsSync(path.join(cur, '.git'))) {
+                return isOvershotRoot(cur) ? undefined : cur;
+            }
+        }
+        catch {
+            return undefined;
+        }
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            return undefined;
+        cur = parent;
+    }
+    return undefined;
+}
+/**
+ * Repos the session worked in, from the directories its file paths live under
+ * (a bounded `.git` walk-up; a `.git` FILE counts too — that's the worktree
+ * layout). Names are repo dir basenames, first-seen order, capped.
+ *
+ * Relative paths resolve against the SESSION's cwd only — when it is unknown
+ * (e.g. kimi rows carry no cwd today) they are skipped: resolving them against
+ * the viewer's process cwd attributes the session to whatever repo the CLI
+ * happens to run in, which is a wrong answer, not a degraded one.
+ */
+export function extractRepos(events, cwd) {
+    const candidates = [];
+    const seenCand = new Set();
+    const addCandidate = (p) => {
+        if (!p || isNoisePath(p))
+            return;
+        // DotAgents internals (the `.system` registry repo, run archives) are
+        // infrastructure, not "repos the user works in".
+        if (p.includes('/.agents/.system/') || p.includes('/.agents/.history/'))
+            return;
+        if (!path.isAbsolute(p) && !cwd)
+            return;
+        const abs = path.isAbsolute(p) ? p : path.resolve(cwd, p);
+        const dir = path.dirname(abs);
+        if (seenCand.has(dir))
+            return;
+        seenCand.add(dir);
+        candidates.push(dir);
+    };
+    for (const e of events) {
+        if (e.type !== 'tool_use' || e._local)
+            continue;
+        const p = e.path || e.args?.file_path || e.args?.path || '';
+        if (typeof p === 'string' && p)
+            addCandidate(p);
+        if (candidates.length >= MAX_REPO_PROBES)
+            break;
+    }
+    const repos = [];
+    const seenRoot = new Set();
+    for (const dir of candidates) {
+        const root = repoRootFrom(dir);
+        if (!root || seenRoot.has(root))
+            continue;
+        seenRoot.add(root);
+        repos.push(path.basename(root));
+    }
+    return repos;
+}

package/dist/lib/session/host-link.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Host link — whether anything is still on the other end of a live session.
+ *
+ * Every liveness signal the scan already has answers "is the AGENT process
+ * alive". None of them answer "is anyone still driving it", and those come apart
+ * in exactly the two ways a user notices:
+ *
+ *   - **The host program died and took the agent with it.** VS Code / the editor
+ *     window crashes or the SSH connection drops, so the agent process dies with
+ *     its parent, but the window never got to run its teardown — its slice of
+ *     `live-terminals.json` is left behind, stale, still naming a dead pid. Today
+ *     that entry is filtered out at read time, so the session simply VANISHES
+ *     from `--active` instead of reporting that it fell over. That is `host-gone`.
+ *
+ *   - **The host program died and the agent survived it.** The agent was hosted
+ *     in tmux (or otherwise reparented), so it keeps running with zero clients
+ *     attached: still burning tokens, or sitting on a question nobody will ever
+ *     answer, with no window anywhere showing it. That is `no-client`.
+ *
+ * Both are DERIVED, never asserted — from the agent pid, the owning window's
+ * keepalive, and tmux's own attached-client count. A deliberately backgrounded
+ * session (`agents sessions detach`) is excluded by construction: it is supposed
+ * to have no client, so calling it orphaned would be a false alarm on the one
+ * case the user asked for.
+ */
+/** How a session is connected to the client that should be driving it. */
+export type HostLink = 
+/** A client is attached, or nothing indicates otherwise. The normal case. */
+'connected'
+/** Alive, but nothing is viewing it — the host window is gone and the agent outlived it. */
+ | 'no-client'
+/** The host window is gone AND the agent process died with it — an unclean exit. */
+ | 'host-gone';
+/**
+ * How long an IDE window's registry slice may go without a refresh before we
+ * treat that window as gone. The Factory extension force-republishes its slice
+ * every 4 minutes (`KEEPALIVE_FORCE_MS` in `apps/factory/src/vscode/foreman.registry.ts`)
+ * and on every terminal open/close, so a slice this old means the window is no
+ * longer running — it is not merely quiet. Deliberately the same 10 minutes the
+ * extension itself uses to garbage-collect a peer window's slice, so the CLI and
+ * the extension agree on when a window is dead.
+ */
+export declare const HOST_HEARTBEAT_STALE_MS: number;
+export interface HostLinkInput {
+    /** The agent process is still alive (already pid-reuse-checked by the caller). */
+    pidAlive: boolean;
+    /**
+     * When the owning IDE window last refreshed its slice of the live-terminals
+     * registry. Absent for a session no IDE window owns (a bare terminal, a team
+     * spawn, a cloud task) — those have no window whose death we could observe.
+     */
+    windowHeartbeatMs?: number;
+    /**
+     * Clients attached to this session's tmux session (`#{session_attached}`).
+     * Absent when the session is not tmux-hosted, which is NOT the same as zero:
+     * zero is a positive "nobody is looking", absent is "we cannot tell".
+     */
+    tmuxClients?: number;
+    /** The session was deliberately backgrounded — `presence` is `background`/`parked`. */
+    deliberatelyDetached?: boolean;
+    nowMs?: number;
+}
+/**
+ * Classify a live row's host link. Pure — every signal is passed in, so the
+ * whole decision table is unit-testable without a process table, a tmux server,
+ * or a running editor.
+ */
+export declare function classifyHostLink(input: HostLinkInput): HostLink;

package/dist/lib/session/host-link.js

@@ -0,0 +1,64 @@
+/**
+ * Host link — whether anything is still on the other end of a live session.
+ *
+ * Every liveness signal the scan already has answers "is the AGENT process
+ * alive". None of them answer "is anyone still driving it", and those come apart
+ * in exactly the two ways a user notices:
+ *
+ *   - **The host program died and took the agent with it.** VS Code / the editor
+ *     window crashes or the SSH connection drops, so the agent process dies with
+ *     its parent, but the window never got to run its teardown — its slice of
+ *     `live-terminals.json` is left behind, stale, still naming a dead pid. Today
+ *     that entry is filtered out at read time, so the session simply VANISHES
+ *     from `--active` instead of reporting that it fell over. That is `host-gone`.
+ *
+ *   - **The host program died and the agent survived it.** The agent was hosted
+ *     in tmux (or otherwise reparented), so it keeps running with zero clients
+ *     attached: still burning tokens, or sitting on a question nobody will ever
+ *     answer, with no window anywhere showing it. That is `no-client`.
+ *
+ * Both are DERIVED, never asserted — from the agent pid, the owning window's
+ * keepalive, and tmux's own attached-client count. A deliberately backgrounded
+ * session (`agents sessions detach`) is excluded by construction: it is supposed
+ * to have no client, so calling it orphaned would be a false alarm on the one
+ * case the user asked for.
+ */
+/**
+ * How long an IDE window's registry slice may go without a refresh before we
+ * treat that window as gone. The Factory extension force-republishes its slice
+ * every 4 minutes (`KEEPALIVE_FORCE_MS` in `apps/factory/src/vscode/foreman.registry.ts`)
+ * and on every terminal open/close, so a slice this old means the window is no
+ * longer running — it is not merely quiet. Deliberately the same 10 minutes the
+ * extension itself uses to garbage-collect a peer window's slice, so the CLI and
+ * the extension agree on when a window is dead.
+ */
+export const HOST_HEARTBEAT_STALE_MS = 10 * 60_000;
+/**
+ * Classify a live row's host link. Pure — every signal is passed in, so the
+ * whole decision table is unit-testable without a process table, a tmux server,
+ * or a running editor.
+ */
+export function classifyHostLink(input) {
+    const now = input.nowMs ?? Date.now();
+    // A session detached on purpose has no client BY DESIGN. It is the one case
+    // that looks identical to an orphan from the outside, so it is excluded first —
+    // otherwise every `agents sessions detach` would raise a false alarm.
+    if (input.deliberatelyDetached)
+        return 'connected';
+    const windowGone = input.windowHeartbeatMs !== undefined && now - input.windowHeartbeatMs >= HOST_HEARTBEAT_STALE_MS;
+    // The host window stopped keeping its registry slice alive AND the agent it
+    // owned is dead: the pair went down together without teardown.
+    if (windowGone && !input.pidAlive)
+        return 'host-gone';
+    if (!input.pidAlive)
+        return 'connected'; // a plain dead pid is `closed`, not an orphan
+    // Alive with tmux reporting zero attached clients: nobody is watching it. This
+    // is the authoritative signal — tmux knows exactly how many clients it has.
+    if (input.tmuxClients === 0)
+        return 'no-client';
+    // Alive, not tmux-hosted (or tmux says someone is attached), but the window
+    // that owned it is gone. The agent outlived its editor.
+    if (windowGone)
+        return 'no-client';
+    return 'connected';
+}

package/dist/lib/session/parse.js

@@ -66,6 +66,10 @@ function sanitizeEvent(e) {
         e.model = sanitizeForTerminal(e.model);
     if (e.mediaType)
         e.mediaType = sanitizeForTerminal(e.mediaType);
+    if (e.hookName)
+        e.hookName = sanitizeForTerminal(e.hookName);
+    if (e.hookEvent)
+        e.hookEvent = sanitizeForTerminal(e.hookEvent);
     if (e.args)
         e.args = sanitizeArgsDeep(e.args);
 }
@@ -484,7 +488,25 @@ export function parseClaudeContent(content) {
                 content: raw.subtype || 'success',
             });
         }
-        // Skip: permission-mode, attachment, and other line types
+        else if (type === 'attachment') {
+            // Hook firings are recorded as attachments: `hook_success` / `hook_error` /
+            // `hook_blocked` per firing, plus a derivative `hook_additional_context`
+            // record for the SAME firing (shared toolUseID) — skip the derivative or
+            // every firing counts twice.
+            const att = raw.attachment;
+            const attType = att?.type;
+            if (typeof attType === 'string' && attType.startsWith('hook_') && attType !== 'hook_additional_context') {
+                events.push({
+                    type: 'hook',
+                    agent: 'claude',
+                    timestamp,
+                    hookName: typeof att.hookName === 'string' ? att.hookName : undefined,
+                    hookEvent: typeof att.hookEvent === 'string' ? att.hookEvent : undefined,
+                    success: attType === 'hook_success',
+                });
+            }
+        }
+        // Skip: permission-mode, non-hook attachments, and other line types
     }
     return events;
 }