@phnx-labs/agents-cli 1.20.89 → 1.20.91

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

@@ -0,0 +1,85 @@
+export type PresenceStatus = 'connected' | 'disconnected';
+export type PresenceLocation = 'local' | 'ssh';
+/** A session as OBSERVED by one tick's active scan — the pure reconcile input. */
+export interface ObservedSession {
+    sessionId: string;
+    agent: string;
+    /** `local` when the session runs on this box, `ssh` when it's on a peer. */
+    location: PresenceLocation;
+    /** The device/host the session runs on (this box's hostname, or the peer). */
+    device: string;
+    /** Transport the session's provenance reports (`local` | `ssh` | ...). */
+    transport: string;
+    /** True for an interactive (terminal/tmux) session — a drop is reconnect-worthy;
+     *  false for a headless remote continuation, where a drop means keep-alive. */
+    interactive: boolean;
+}
+export interface PresenceRecord {
+    sessionId: string;
+    agent: string;
+    location: PresenceLocation;
+    device: string;
+    transport: string;
+    interactive: boolean;
+    /** ms of the last tick this session was observed active. */
+    lastSeenMs: number;
+    status: PresenceStatus;
+}
+/** What the tick should do about a session that just flipped `disconnected`. */
+export type PresenceAction = 'reconnect-nudge' | 'keep-alive' | 'none';
+export interface PresenceTransition {
+    record: PresenceRecord;
+    from: PresenceStatus;
+    to: PresenceStatus;
+    action: PresenceAction;
+}
+/** A `disconnected` record older than this is pruned — the session is gone for
+ *  good, not merely between clients. Kept generous so a long reconnect window
+ *  (the reconnect loop's own bounded backoff) never drops a record mid-recovery. */
+export declare const PRESENCE_TTL_MS: number;
+/** `presence.json` under the watchdog state dir. `dir` is the watchdog state dir
+ *  (the tick passes its own, overridable in tests); default is the real one. */
+export declare function presenceFilePath(dir?: string): string;
+export declare function loadPresence(dir?: string): Record<string, PresenceRecord>;
+export declare function savePresence(map: Record<string, PresenceRecord>, dir?: string): void;
+/** The subset of an `ActiveSession` the presence adapter reads (structural, so
+ *  this module doesn't import the heavy active-session graph). */
+export interface ActiveSessionLike {
+    sessionId?: string;
+    kind: string;
+    /** 'terminal' (interactive) | 'headless' | 'teams' | 'cloud' | ... */
+    context: string;
+    /** Set for a peer session by the fleet fan-out (`gatherRemoteActive`). */
+    machine?: string;
+    provenance?: {
+        transport?: string;
+    };
+}
+/**
+ * Map this tick's active sessions to presence observations. A session on a peer
+ * carries `machine` (from the fleet fan-out) → `location: 'ssh'`; a local one →
+ * `'local'`. `interactive` is true only for a `terminal` context (a tmux/terminal
+ * session whose drop is reconnect-worthy) — headless/teams/cloud are not.
+ * Sessions with no id are skipped (they can't be tracked or addressed).
+ */
+export declare function observedFromActive(sessions: ActiveSessionLike[], selfHost?: string): ObservedSession[];
+/** The action for a session that just flipped to `disconnected`: an interactive
+ *  session wants a reconnect nudge; a headless remote wants keep-alive; a local
+ *  headless that vanished is simply gone (no action). */
+export declare function actionFor(record: PresenceRecord): PresenceAction;
+/**
+ * Pure state machine. Given the prior store, the sessions observed THIS tick, and
+ * `nowMs`, return the next store plus the set of status transitions.
+ *
+ * - observed now                 -> `connected`, lastSeen = now (record refreshed)
+ * - tracked but absent now       -> `disconnected` (lastSeen kept from prior tick)
+ * - `disconnected` older than TTL -> pruned (gone for good)
+ *
+ * `transitions` carries only sessions whose status actually changed, each with
+ * the action the tick should take — so the caller never re-nudges a session that
+ * was already disconnected last tick.
+ */
+export declare function reconcilePresence(prev: Record<string, PresenceRecord>, observed: ObservedSession[], nowMs: number): {
+    next: Record<string, PresenceRecord>;
+    transitions: PresenceTransition[];
+};

package/dist/lib/session/presence.js

@@ -0,0 +1,150 @@
+/**
+ * RUSH-2007 Layer C — per-session presence tracking, folded into the `agents
+ * watchdog` tick (NOT a revived daemon).
+ *
+ * Each tick the watchdog observes the active sessions across the fleet
+ * (`gatherRemoteActive` + the local scan). This module persists one record per
+ * session — `{location, device, transport, lastSeen, status}` — and DERIVES
+ * `connected` / `disconnected` by diffing consecutive observations: a session
+ * present this tick is `connected`; one that was tracked but is now absent (its
+ * peer went unreachable, or the interactive client dropped) flips to
+ * `disconnected` while its record — and the transition — is surfaced so the tick
+ * can act (an interactive drop is a reconnect-nudge candidate; a headless remote
+ * is a keep-alive). The store is honest across a crash: it only reflects what the
+ * last scan actually saw, never an asserted state.
+ *
+ * Store: `~/.agents/.cache/state/watchdog/presence.json` — sibling of the tick's
+ * existing `nudges/flags/last-tick` files. Best-effort: an unreadable/corrupt
+ * file degrades to an empty store, never throws into the tick loop.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getRuntimeStateDir } from '../state.js';
+/** A `disconnected` record older than this is pruned — the session is gone for
+ *  good, not merely between clients. Kept generous so a long reconnect window
+ *  (the reconnect loop's own bounded backoff) never drops a record mid-recovery. */
+export const PRESENCE_TTL_MS = 30 * 60_000; // 30 minutes
+/** `presence.json` under the watchdog state dir. `dir` is the watchdog state dir
+ *  (the tick passes its own, overridable in tests); default is the real one. */
+export function presenceFilePath(dir) {
+    return path.join(dir ?? path.join(getRuntimeStateDir(), 'watchdog'), 'presence.json');
+}
+export function loadPresence(dir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(presenceFilePath(dir), 'utf8');
+    }
+    catch {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* corrupt — degrade to empty, never throw into the tick */
+    }
+    return {};
+}
+export function savePresence(map, dir) {
+    try {
+        const file = presenceFilePath(dir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(map), 'utf8');
+    }
+    catch {
+        /* best-effort; a failed write just re-derives next tick */
+    }
+}
+/**
+ * Map this tick's active sessions to presence observations. A session on a peer
+ * carries `machine` (from the fleet fan-out) → `location: 'ssh'`; a local one →
+ * `'local'`. `interactive` is true only for a `terminal` context (a tmux/terminal
+ * session whose drop is reconnect-worthy) — headless/teams/cloud are not.
+ * Sessions with no id are skipped (they can't be tracked or addressed).
+ */
+export function observedFromActive(sessions, selfHost = os.hostname()) {
+    const out = [];
+    for (const s of sessions) {
+        if (!s.sessionId)
+            continue;
+        const location = s.machine ? 'ssh' : 'local';
+        out.push({
+            sessionId: s.sessionId,
+            agent: s.kind,
+            location,
+            device: s.machine ?? selfHost,
+            transport: s.provenance?.transport ?? location,
+            interactive: s.context === 'terminal',
+        });
+    }
+    return out;
+}
+/** The action for a session that just flipped to `disconnected`: an interactive
+ *  session wants a reconnect nudge; a headless remote wants keep-alive; a local
+ *  headless that vanished is simply gone (no action). */
+export function actionFor(record) {
+    if (record.status !== 'disconnected')
+        return 'none';
+    if (record.interactive)
+        return 'reconnect-nudge';
+    if (record.location === 'ssh')
+        return 'keep-alive';
+    return 'none';
+}
+/**
+ * Pure state machine. Given the prior store, the sessions observed THIS tick, and
+ * `nowMs`, return the next store plus the set of status transitions.
+ *
+ * - observed now                 -> `connected`, lastSeen = now (record refreshed)
+ * - tracked but absent now       -> `disconnected` (lastSeen kept from prior tick)
+ * - `disconnected` older than TTL -> pruned (gone for good)
+ *
+ * `transitions` carries only sessions whose status actually changed, each with
+ * the action the tick should take — so the caller never re-nudges a session that
+ * was already disconnected last tick.
+ */
+export function reconcilePresence(prev, observed, nowMs) {
+    const next = {};
+    const transitions = [];
+    const observedIds = new Set(observed.map((o) => o.sessionId));
+    // 1. Everything observed this tick is connected.
+    for (const o of observed) {
+        const before = prev[o.sessionId];
+        const record = {
+            sessionId: o.sessionId,
+            agent: o.agent,
+            location: o.location,
+            device: o.device,
+            transport: o.transport,
+            interactive: o.interactive,
+            lastSeenMs: nowMs,
+            status: 'connected',
+        };
+        next[o.sessionId] = record;
+        if (before && before.status === 'disconnected') {
+            transitions.push({ record, from: 'disconnected', to: 'connected', action: 'none' });
+        }
+    }
+    // 2. Tracked-but-absent sessions flip to disconnected (or prune past TTL).
+    for (const [id, before] of Object.entries(prev)) {
+        if (observedIds.has(id))
+            continue;
+        if (nowMs - before.lastSeenMs > PRESENCE_TTL_MS)
+            continue; // prune: gone for good
+        const record = { ...before, status: 'disconnected' };
+        next[id] = record;
+        if (before.status === 'connected') {
+            transitions.push({
+                record,
+                from: 'connected',
+                to: 'disconnected',
+                action: actionFor(record),
+            });
+        }
+    }
+    return { next, transitions };
+}

package/dist/lib/session/relative-time.d.ts

@@ -5,3 +5,17 @@
  * `remote.ts`, so a back-import would cycle.
  */
 export declare function formatRelativeTime(isoTimestamp: string): string;
+/**
+ * Parse a time filter string (relative like '7d' or an ISO timestamp) into epoch
+ * milliseconds. Backs `--since` on `sessions`, `cost`, `teams`, and `output`, and
+ * `--unused` on `secrets list`.
+ *
+ * It lives here, in a module with no imports, rather than in `discover.ts` where
+ * it started: `discover.ts` loads `../sqlite.js`, so importing this one function
+ * from there pulls `node:sqlite` into the caller's module graph and Node prints
+ * `ExperimentalWarning: SQLite …` on stderr. That is invisible in a command that
+ * already touches the session DB, and a broken contract in one that doesn't —
+ * `monitors --json` asserts a clean stderr. `discover.ts` re-exports it, so
+ * existing importers are unaffected.
+ */
+export declare function parseTimeFilter(input: string): number;

package/dist/lib/session/relative-time.js

@@ -30,3 +30,39 @@ export function formatRelativeTime(isoTimestamp) {
         ? label
         : `${label} '${String(d.getFullYear()).slice(-2)}`;
 }
+/**
+ * Parse a time filter string (relative like '7d' or an ISO timestamp) into epoch
+ * milliseconds. Backs `--since` on `sessions`, `cost`, `teams`, and `output`, and
+ * `--unused` on `secrets list`.
+ *
+ * It lives here, in a module with no imports, rather than in `discover.ts` where
+ * it started: `discover.ts` loads `../sqlite.js`, so importing this one function
+ * from there pulls `node:sqlite` into the caller's module graph and Node prints
+ * `ExperimentalWarning: SQLite …` on stderr. That is invisible in a command that
+ * already touches the session DB, and a broken contract in one that doesn't —
+ * `monitors --json` asserts a clean stderr. `discover.ts` re-exports it, so
+ * existing importers are unaffected.
+ */
+export function parseTimeFilter(input) {
+    // Units: m=minute, h=hour, d=day, w=week, mo=month(30d), y=year(365d). `mo`
+    // must precede the single-letter alternatives so "1mo" isn't read as "1m"+"o".
+    const relativeMatch = input.match(/^(\d+)(mo|[mhdwy])$/i);
+    if (relativeMatch) {
+        const value = parseInt(relativeMatch[1], 10);
+        const unit = relativeMatch[2].toLowerCase();
+        if (unit === 'm')
+            return Date.now() - value * 60_000;
+        if (unit === 'h')
+            return Date.now() - value * 3_600_000;
+        if (unit === 'd')
+            return Date.now() - value * 86_400_000;
+        if (unit === 'w')
+            return Date.now() - value * 7 * 86_400_000;
+        if (unit === 'mo')
+            return Date.now() - value * 30 * 86_400_000;
+        if (unit === 'y')
+            return Date.now() - value * 365 * 86_400_000;
+    }
+    const ts = new Date(input).getTime();
+    return Number.isNaN(ts) ? 0 : ts;
+}

package/dist/lib/session/remote-list.d.ts

@@ -16,6 +16,16 @@ export declare function remoteListCommand(forwardedArgs: string[], os?: string):
  * testing without a live tailnet.
  */
 export declare function parseRemoteList(stdout: string, machine: string): SessionMeta[];
+export declare function parseRemoteListPayload(stdout: string, machine: string, safeResolver?: boolean): {
+    sessions: SessionMeta[];
+    valid: boolean;
+};
+/** Convert one completed peer process into the exact aggregation result. This
+ * is the production parent/peer seam and is exercised with real child output. */
+export declare function remoteListCaptureResult(code: number | null, stdout: string, machine: string, display: string, safeResolver?: boolean): {
+    sessions: SessionMeta[];
+    unreachable?: string;
+};
 export interface RemoteListResult {
     sessions: SessionMeta[];
     /** How many peer machines we attempted to reach (drives the empty-fleet tip). */

package/dist/lib/session/remote-list.js

@@ -61,15 +61,52 @@ export function parseRemoteList(stdout, machine) {
     }
     if (!Array.isArray(parsed))
         return [];
+    return parsed.flatMap((value) => value && typeof value === 'object' && !Array.isArray(value)
+        ? [{ ...value, machine, _remote: true }]
+        : []);
+}
+/** Strict parser used at the live peer boundary. A successful process with
+ * malformed/non-array JSON is an incomplete source, not an empty machine. */
+const SAFE_RESOLVER_KEYS = new Set([
+    'id', 'shortId', 'agent', 'origin', 'timestamp', 'lastActivity', 'project',
+    'version', 'label', 'topic', 'machine',
+]);
+function isSafeResolverRow(value) {
+    if (typeof value.id !== 'string' || typeof value.shortId !== 'string'
+        || typeof value.agent !== 'string' || typeof value.timestamp !== 'string')
+        return false;
+    return Object.keys(value).every(key => SAFE_RESOLVER_KEYS.has(key));
+}
+export function parseRemoteListPayload(stdout, machine, safeResolver = false) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return { sessions: [], valid: false };
+    }
+    if (!Array.isArray(parsed))
+        return { sessions: [], valid: false };
     const out = [];
     for (const x of parsed) {
-        if (x && typeof x === 'object' && !Array.isArray(x)) {
-            // `_remote` marks these as living on the peer's disk (not a local mirror),
-            // so the picker routes read/resume back over SSH instead of the local FS.
-            out.push({ ...x, machine, _remote: true });
+        if (!x || typeof x !== 'object' || Array.isArray(x))
+            return { sessions: [], valid: false };
+        if (safeResolver && !isSafeResolverRow(x)) {
+            return { sessions: [], valid: false };
         }
+        // `_remote` marks these as living on the peer's disk (not a local mirror),
+        // so the picker routes read/resume back over SSH instead of the local FS.
+        out.push({ ...x, machine, _remote: true });
     }
-    return out;
+    return { sessions: out, valid: true };
+}
+/** Convert one completed peer process into the exact aggregation result. This
+ * is the production parent/peer seam and is exercised with real child output. */
+export function remoteListCaptureResult(code, stdout, machine, display, safeResolver = false) {
+    if (code !== 0)
+        return { sessions: [], unreachable: display };
+    const parsed = parseRemoteListPayload(stdout, machine, safeResolver);
+    return parsed.valid ? { sessions: parsed.sessions } : { sessions: [], unreachable: display };
 }
 /** Run one remote `agents sessions … --json` and capture stdout. Resolves
  * `{ code: null }` on spawn error or timeout (host treated as dead). */
@@ -95,11 +132,12 @@ function sshCapture(target, remoteCmd, timeoutMs) {
 }
 async function fetchByTarget(target, machine, display, forwardedArgs, os) {
     const { code, stdout } = await sshCapture(target, remoteListCommand(forwardedArgs, os), REMOTE_TIMEOUT_MS);
-    if (code !== 0) {
+    const safeResolver = forwardedArgs.includes('--resolve-safe-v1');
+    const result = remoteListCaptureResult(code, stdout, machine, display, safeResolver);
+    if (result.unreachable) {
         process.stderr.write(chalk.gray(`  ${display}: unreachable or no agents CLI — skipped\n`));
-        return { sessions: [], unreachable: display };
     }
-    return { sessions: parseRemoteList(stdout, machine) };
+    return result;
 }
 /**
  * Gather listing sessions from other machines. With an explicit `hosts` list
@@ -122,7 +160,7 @@ export async function gatherRemoteList(forwardedArgs, hosts) {
             reg = await loadDevices();
         }
         catch {
-            return { sessions: [], deviceCount: 0, unreachable: [] };
+            return { sessions: [], deviceCount: 0, unreachable: ['device registry'] };
         }
         for (const d of Object.values(reg)) {
             if (d.tailscale?.online !== true)

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

@@ -11,6 +11,13 @@ import type { SessionEvent, SessionMeta } from './types.js';
  * Return absPath relative to cwd; fall back to ~/… then absolute.
  */
 export declare function relativeToCwd(absPath: string, cwd?: string): string;
+/**
+ * Display form for a touched path: cwd-relative first; then collapse any
+ * `.agents/worktrees/<slug>` segment (in-cwd OR outside) to `⧉ <slug>/…` so
+ * group labels stay on one line instead of `~/src/…/.agents/worktrees/<slug>/…`;
+ * else home-collapse.
+ */
+export declare function displayPath(absPath: string, cwd?: string): string;
 /**
  * Wrap a filesystem path label in an OSC 8 `file://` hyperlink when the terminal
  * supports it. Degrades to the plain label otherwise.

package/dist/lib/session/render.js

@@ -13,6 +13,7 @@ import { cleanSessionPrompt, extractSessionTopic } from './prompt.js';
 import { renderMarkdown } from '../markdown.js';
 import { redactSecrets } from '../redact.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from './digest.js';
+import { extractArtifacts, extractHooks, extractLinks, extractSkills } from './highlights.js';
 import { extractTodoProgressFromEvents } from './state.js';
 // ── Path helpers ──────────────────────────────────────────────────────────────
 /**
@@ -29,6 +30,31 @@ export function relativeToCwd(absPath, cwd) {
     }
     return absPath;
 }
+/**
+ * Display form for a touched path: cwd-relative first; then collapse any
+ * `.agents/worktrees/<slug>` segment (in-cwd OR outside) to `⧉ <slug>/…` so
+ * group labels stay on one line instead of `~/src/…/.agents/worktrees/<slug>/…`;
+ * else home-collapse.
+ */
+export function displayPath(absPath, cwd) {
+    const rel = relativeToCwd(absPath, cwd);
+    const norm = rel.replace(/\\/g, '/');
+    const wt = norm.match(/(^|\/)\.agents\/worktrees\/([^/]+)/);
+    if (wt) {
+        const after = norm.slice(norm.indexOf(wt[0]) + wt[0].length).replace(/^\//, '');
+        return after ? `⧉ ${wt[2]}/${after}` : `⧉ ${wt[2]}`;
+    }
+    return rel;
+}
+/** One checklist line with a status marker: `[x] done` / `[>] doing` / `[ ] todo`. */
+function renderTodoMarker(item) {
+    const text = item.content;
+    if (item.status === 'completed')
+        return chalk.green('[x]') + ' ' + chalk.gray(text);
+    if (item.status === 'in_progress')
+        return chalk.yellow('[>]') + ' ' + chalk.white(text);
+    return chalk.gray('[ ]') + ' ' + chalk.white(text);
+}
 /** Best-effort feature-detect for OSC 8 hyperlink support in the current TTY. */
 function supportsHyperlinks() {
     return Boolean(process.stdout.isTTY &&
@@ -387,11 +413,12 @@ function pickDistinct(samples, max) {
     return result.length > 0 ? result : samples.slice(0, max);
 }
 // ── File grouping ─────────────────────────────────────────────────────────────
-/** Group file paths by their parent directory, relative to cwd. */
+/** Group file paths by their parent directory, in display form (cwd-relative,
+ * worktree-collapsed, home-collapsed). */
 function groupByParentDir(paths, cwd) {
     const groups = new Map();
     for (const p of paths) {
-        const rel = relativeToCwd(p, cwd);
+        const rel = displayPath(p, cwd);
         const slashIdx = rel.lastIndexOf('/');
         const dir = slashIdx >= 0 ? rel.slice(0, slashIdx) : '.';
         const base = slashIdx >= 0 ? rel.slice(slashIdx + 1) : rel;
@@ -454,17 +481,17 @@ const OP_MARK = { created: '+', modified: '~', deleted: '−' };
  * create/modify/delete lifecycle, plus a `+N ~N −N` summary. Replaces the old
  * flat "Modified" list. Returns true if anything was rendered.
  */
-function renderChangesSection(lines, events, cwd) {
+function renderChangesSection(lines, allChanges, cwd) {
     // In-project changes only; edits outside cwd (e.g. /tmp) keep their own
     // "External edits" section so they don't clutter the project's changeset.
     const inCwd = (p) => !cwd || !p.startsWith('/') || p.startsWith(cwd + '/');
-    const changes = classifyFileChanges(events).filter(ch => inCwd(ch.path));
+    const changes = allChanges.filter(ch => inCwd(ch.path));
     if (changes.length === 0)
         return false;
     const c = changeCounts(changes);
     const opByRel = new Map();
     for (const ch of changes)
-        opByRel.set(relativeToCwd(ch.path, cwd), ch.op);
+        opByRel.set(displayPath(ch.path, cwd), ch.op);
     const summary = [
         c.created ? chalk.green(`+${c.created}`) : '',
         c.modified ? chalk.yellow(`~${c.modified}`) : '',
@@ -528,8 +555,8 @@ export function renderSummary(events, cwd) {
     const filesModifiedExternal = new Set();
     // Commands with timestamps
     const cmdList = [];
-    // Plan items
-    const todoItems = extractTodoProgressFromEvents(events)?.items.map(item => item.content) ?? [];
+    // Plan items (checklist entries keep their status for [x]/[>]/[ ] markers)
+    const todoItems = extractTodoProgressFromEvents(events)?.items ?? [];
     let exitPlanContent = null;
     let planFilePath = null;
     // Subagent spawns
@@ -559,7 +586,7 @@ export function renderSummary(events, cwd) {
                     }
                     else {
                         (isInsideCwd(p) || !cwd ? filesModifiedAbs : filesModifiedExternal).add(p);
-                        recentActivity.push({ kind: 'edit', label: relativeToCwd(p, cwd), ts, absPath: p });
+                        recentActivity.push({ kind: 'edit', label: displayPath(p, cwd), ts, absPath: p });
                     }
                 }
             }
@@ -624,11 +651,11 @@ export function renderSummary(events, cwd) {
         filesReadAbs.delete(p);
     for (const p of filesModifiedExternal)
         filesReadAbs.delete(p);
-    // Build abs→rel mapping for linkPath
+    // Build abs→display mapping for linkPath
     const buildAbsMap = (absSet) => {
         const m = new Map();
         for (const abs of absSet) {
-            const rel = relativeToCwd(abs, cwd);
+            const rel = displayPath(abs, cwd);
             m.set(rel, abs);
         }
         return m;
@@ -668,22 +695,27 @@ export function renderSummary(events, cwd) {
         }
         lines.push('');
     }
-    // 3. Plan
+    // 3. Plan — the plan document (ExitPlanMode text / plan file) AND the live
+    // checklist. Both render: the checklist used to be hidden whenever plan text
+    // existed, which read as "this session had no todos".
     if (todoItems.length > 0 || exitPlanContent || planFilePath) {
         lines.push(chalk.bold('Plan'));
         if (planFilePath) {
             const home = process.env.HOME ?? '';
-            const displayPath = home && planFilePath.startsWith(home) ? planFilePath.replace(home, '~') : planFilePath;
-            lines.push('  ' + chalk.cyan(displayPath));
+            const planPathDisplay = home && planFilePath.startsWith(home) ? planFilePath.replace(home, '~') : planFilePath;
+            lines.push('  ' + chalk.cyan(planPathDisplay));
         }
         if (exitPlanContent) {
             const planLines = exitPlanContent.split('\n').slice(0, 10);
             for (const l of planLines)
                 lines.push('  ' + l);
         }
-        else if (todoItems.length > 0) {
+        if (todoItems.length > 0) {
             for (const item of todoItems.slice(0, 20)) {
-                lines.push('  · ' + item);
+                lines.push('  ' + renderTodoMarker(item));
+            }
+            if (todoItems.length > 20) {
+                lines.push('  ' + chalk.gray(`… (${todoItems.length - 20} more)`));
             }
         }
         lines.push('');
@@ -698,6 +730,30 @@ export function renderSummary(events, cwd) {
         }
         lines.push('');
     }
+    // 4b. Highlights — what the session USED (skills, hooks) and the references
+    // it mentioned (links). Shared extraction with the picker preview so the two
+    // renders never disagree.
+    const skills = extractSkills(events);
+    if (skills.length > 0) {
+        const shown = skills.map(s => chalk.white(s.name) + (s.count > 1 ? chalk.gray(` ×${s.count}`) : ''));
+        lines.push(chalk.bold('Skills') + chalk.gray(` (${skills.length})`) + '  ' + shown.join(chalk.gray(' · ')));
+        lines.push('');
+    }
+    const hooks = extractHooks(events);
+    if (hooks.length > 0) {
+        const shown = hooks.map(h => chalk.white(h.name) + (h.count > 1 ? chalk.gray(` ×${h.count}`) : '') + (h.failed ? chalk.red(` (${h.failed} failed)`) : ''));
+        lines.push(chalk.bold('Hooks') + chalk.gray(` (${hooks.length})`) + '  ' + shown.join(chalk.gray(' · ')));
+        lines.push('');
+    }
+    const links = extractLinks(events);
+    if (links.length > 0) {
+        // Width-capped like the picker's Dirs line: a link-heavy session must not
+        // wrap the summary pane.
+        const shown = links.slice(0, 6).map(l => chalk.blue(linkUrl(l.url, l.label)));
+        const more = links.length > 6 ? chalk.gray(` · +${links.length - 6} more`) : '';
+        lines.push(chalk.bold('Links') + chalk.gray(` (${links.length})`) + '  ' + shown.join(chalk.gray(' · ')) + more);
+        lines.push('');
+    }
     // 5. Errors (moved up from the bottom: it describes failed attempts, not the
     // session's final state. Sitting at the bottom previously made early errors
     // look recent, which confused readers.)
@@ -713,8 +769,22 @@ export function renderSummary(events, cwd) {
         lines.push('');
     }
     // 6. Changes — files grouped by directory with create/modify/delete lifecycle
-    // (replaces the old flat "Modified" + "External edits" lists).
-    renderChangesSection(lines, events, cwd);
+    // (replaces the old flat "Modified" + "External edits" lists). Classified
+    // once here and shared with the Artifacts section below.
+    const allChanges = classifyFileChanges(events);
+    renderChangesSection(lines, allChanges, cwd);
+    // 6a. Artifacts — documents the session PRODUCED (`.agents/artifacts|plans|
+    // reports`, other *.md/*.html creations), named and clickable. These drown in
+    // the Changeset's source churn, so they get their own section.
+    const artifacts = extractArtifacts(allChanges);
+    if (artifacts.length > 0) {
+        lines.push(chalk.bold('Artifacts') + chalk.gray(` (${artifacts.length})`));
+        for (const a of artifacts) {
+            const tag = a.bucket === 'docs' ? '' : chalk.gray(` (${a.bucket})`);
+            lines.push('  ' + chalk.green('+') + ' ' + chalk.cyan(linkPath(a.path, a.basename)) + tag);
+        }
+        lines.push('');
+    }
     // 6b. Catch-up signals: last test/build verdict, then the tool histogram.
     renderTestsLine(lines, events);
     renderToolsSection(lines, computeSummaryStats(events));

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

@@ -18,7 +18,7 @@ export declare const SESSION_AGENTS: SessionAgentId[];
 export declare function isSessionTrackedAgent(agent: string): agent is SessionAgentId;
 /** A single normalized event within a session (message, tool call, thinking, etc.). */
 export interface SessionEvent {
-    type: 'message' | 'tool_use' | 'tool_result' | 'thinking' | 'error' | 'init' | 'result' | 'usage' | 'attachment';
+    type: 'message' | 'tool_use' | 'tool_result' | 'thinking' | 'error' | 'init' | 'result' | 'usage' | 'attachment' | 'hook';
     agent: SessionAgentId;
     timestamp: string;
     role?: 'user' | 'assistant';
@@ -49,6 +49,9 @@ export interface SessionEvent {
     name?: string;
     mediaType?: string;
     sizeBytes?: number;
+    hookName?: string;
+    /** Lifecycle event the hook fired on (SessionStart, PreToolUse, …). */
+    hookEvent?: string;
 }
 /** A displayable file attachment discovered in a session transcript. */
 export interface SessionAttachment {

package/dist/lib/startup/command-registry.d.ts

@@ -70,6 +70,7 @@ export declare const loadDrive: ModuleLoader;
 export declare const loadFactory: ModuleLoader;
 export declare const loadUsage: ModuleLoader;
 export declare const loadCost: ModuleLoader;
+export declare const loadPerf: ModuleLoader;
 export declare const loadOutput: ModuleLoader;
 export declare const loadBudget: ModuleLoader;
 export declare const loadAlias: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -48,6 +48,7 @@ export const loadDrive = async () => (await import('../../commands/drive.js')).r
 export const loadFactory = async () => (await import('../../commands/factory.js')).registerFactoryCommands;
 export const loadUsage = async () => (await import('../../commands/usage.js')).registerUsageCommand;
 export const loadCost = async () => (await import('../../commands/cost.js')).registerCostCommand;
+export const loadPerf = async () => (await import('../../commands/perf.js')).registerPerfCommand;
 export const loadOutput = async () => (await import('../../commands/output.js')).registerOutputCommand;
 export const loadBudget = async () => (await import('../../commands/budget.js')).registerBudgetCommand;
 export const loadAlias = async () => (await import('../../commands/alias.js')).registerAliasCommand;
@@ -162,6 +163,7 @@ export const COMMAND_LOADERS = {
     factory: [loadFactory],
     usage: [loadUsage],
     cost: [loadCost],
+    perf: [loadPerf],
     output: [loadOutput],
     budget: [loadBudget],
     alias: [loadAlias],