@phnx-labs/agents-cli 1.22.46 → 1.22.47

package/dist/lib/secrets/Agents CLI.app/Contents/Info.plist

@@ -8,6 +8,8 @@
   <string>Agents CLI</string>
   <key>CFBundleDisplayName</key>
   <string>Agents CLI</string>
+  <key>CFBundleIconFile</key>
+  <string>AppIcon</string>
   <key>CFBundleExecutable</key>
   <string>Agents CLI</string>
   <key>CFBundlePackageType</key>

package/dist/lib/secrets/Agents CLI.app/Contents/_CodeSignature/CodeResources

@@ -3,9 +3,21 @@
 <plist version="1.0">
 <dict>
 	<key>files</key>
-	<dict/>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<data>
+		DFq5H08EkhgWIC3UvGMR9B58BZw=
+		</data>
+	</dict>
 	<key>files2</key>
 	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			mBSjM6jlvN7J1jQowsvqTl7CHM0pur0e6qsHMuzk5k0=
+			</data>
+		</dict>
 		<key>embedded.provisionprofile</key>
 		<dict>
 			<key>hash2</key>

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

@@ -1,6 +1,7 @@
 import type { CloudTaskStatus } from '../cloud/types.js';
 import { type PidSessionEntry } from './pid-registry.js';
 import { type HookSessionIndex } from './hook-sessions.js';
+import { type UserPromptKind } from './prompt.js';
 import { type SessionState, type SessionActivity, type AwaitingReason, type StructuredQuestion, type TodoProgress, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
 import { type SessionAgentId, type SessionAttachment, type SessionMeta } from './types.js';
 import { type SessionProvenance } from './provenance.js';
@@ -99,6 +100,15 @@ export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'c
  | 'orphaned'
 /** The host window died and took the agent with it — an unclean exit, not a normal close. */
  | 'crashed' | 'unknown';
+/**
+ * Which rung of the recap ladder produced a row's shown {@link ActiveSession.title}
+ * (RUSH-3011), best-first:
+ *   - `label`  — a `/rename` or harness-set label (incl. an agent-generated
+ *                title, which lands in `label`); always wins.
+ *   - `last`   — the last assistant line from the transcript tail; agent-derived.
+ *   - `prompt` — the first-user-prompt topic; the last-resort fallback.
+ */
+export type RecapSource = 'label' | 'last' | 'prompt';
 export interface ActiveSession {
     context: ActiveContext;
     kind: string;
@@ -115,6 +125,30 @@ export interface ActiveSession {
     name?: string;
     /** First meaningful line of the initial prompt (extracted topic). */
     topic?: string;
+    /**
+     * The row's shown title — WHAT the session is, best-source-wins (RUSH-3011).
+     * The ladder ({@link deriveSessionRecap}): a `/rename` or harness `label` →
+     * the last agent line (`lastAgentLine`) → the first-prompt `topic`. A session
+     * whose agent did work shows an agent-derived line, not the stale first
+     * prompt. Folded on at the end of {@link getActiveSessions}; `recapSource`
+     * names which rung produced it.
+     */
+    title?: string;
+    /** Which ladder rung produced {@link title}. */
+    recapSource?: RecapSource;
+    /**
+     * The first user turn cleaned for a "You" line — a screenshot path folds to
+     * `[image]`, a pasted `$ cmd` to the command, a `/skill` install path to
+     * `/<name>`, so path noise never shows. See {@link classifyUserPrompt}.
+     */
+    userPromptClean?: string;
+    /** What kind of first turn {@link userPromptClean} was. */
+    userPromptKind?: UserPromptKind;
+    /**
+     * The most recent assistant line (from the transcript tail) — the free,
+     * always-current signal of what the agent last said/did. Ladder rung 3.
+     */
+    lastAgentLine?: string;
     /** Live preview: the latest turn (agent message or tool action), from the state engine. */
     preview?: string;
     /** Inferred activity: working / waiting_input / idle (from the transcript tail). */
@@ -787,6 +821,39 @@ export declare function sessionProcessIsLocal(s: Pick<ActiveSession, 'machine' |
  */
 export declare function sessionProcessHost(s: Pick<ActiveSession, 'machine' | 'offloadedFrom'>, self: string): string | undefined;
 export declare function foldHostLink(rows: ActiveSession[]): void;
+/**
+ * The recap ladder (RUSH-3011): compute a row's shown {@link ActiveSession.title}
+ * + {@link RecapSource} from the best available source, plus the cleaned first
+ * prompt (`userPromptClean`/`userPromptKind`) and the `lastAgentLine`. Pure over
+ * one row; exported for tests and folded in by {@link foldRecap}.
+ *
+ * Ladder, best-first: a `/rename`/harness `label` → the last assistant line →
+ * the first-prompt topic. The `last` rung is agent-derived, so a session that
+ * produced work stops showing its stale first prompt as the title. (`topic` is
+ * the row's already-extracted first line, so image detection here is
+ * path-based; a pure-attachment turn with no first-line text stays on `prompt`.)
+ */
+export declare function deriveSessionRecap(row: Pick<ActiveSession, 'label' | 'topic' | 'tail'>): {
+    title?: string;
+    recapSource?: RecapSource;
+    userPromptClean?: string;
+    userPromptKind?: UserPromptKind;
+    lastAgentLine?: string;
+};
+/** Fold the recap ladder onto every row (see {@link deriveSessionRecap}). */
+export declare function foldRecap(rows: ActiveSession[]): void;
+/**
+ * True when a crash-leaked orphan is genuinely DEAD and should be reaped from the
+ * reconnectable set rather than shown as resumable forever (RUSH-3011 / issue #3b).
+ *
+ * The gate is `abandoned` (no transcript write in {@link ABANDONED_STALE_MS}) AND
+ * a dead pid — exactly "past the stale threshold whose pid is gone". A live pid
+ * (an idle-but-unfinished session, the highest-risk state) is NEVER reaped, and
+ * neither is a recently-`closed`/`crashed` session that just exited (still
+ * resumable). `pidAlive` absent (a cloud row or an older peer that can't prove
+ * death) also stays un-reaped — reaping is fail-safe, never a guess.
+ */
+export declare function isReapableOrphan(row: Pick<ActiveSession, 'status' | 'pidAlive'>): boolean;
 /**
  * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,
  * when that orchestrator session is itself in the active set (it usually is — the

package/dist/lib/session/active.js

@@ -30,7 +30,7 @@ import { loadHookSessionIndex, resolveHookSessionRecord, readStateSessionRecord
 import { buildClaudeLabelMap, getAgentSessionDirs } from './discover.js';
 import { buildRunNameMap } from './run-names.js';
 import { latestSessionFileForCwd, findSessionsByShortIds, findSessionMachinesByIds, getSessionById } from './db.js';
-import { extractSessionTopic } from './prompt.js';
+import { extractSessionTopic, classifyUserPrompt } from './prompt.js';
 import { readSessionTailWithRaw } from './tail.js';
 import { parseSession } from './parse.js';
 import { computeTokPerSec } from './throughput.js';
@@ -1831,6 +1831,9 @@ export async function getActiveSessions(opts = {}) {
     // the EXECUTION host rather than the dispatcher (RUSH-2479).
     foldExecutionMachine(merged, recordedMachineLookup(merged), machineId());
     annotateOrchestratorLabels(merged);
+    // Last: derive the shown title (recap ladder) from label/tail/topic now that
+    // every row's live tail + label are resolved (RUSH-3011).
+    foldRecap(merged);
     return merged;
 }
 /**
@@ -2074,6 +2077,71 @@ export function foldHostLink(rows) {
         }
     }
 }
+/** One display line, trimmed and capped, or undefined when empty. */
+function recapLine(s, max = 120) {
+    const t = s?.replace(/\s+/g, ' ').trim();
+    if (!t)
+        return undefined;
+    return t.length > max ? t.slice(0, max - 1).trimEnd() + '…' : t;
+}
+/**
+ * The recap ladder (RUSH-3011): compute a row's shown {@link ActiveSession.title}
+ * + {@link RecapSource} from the best available source, plus the cleaned first
+ * prompt (`userPromptClean`/`userPromptKind`) and the `lastAgentLine`. Pure over
+ * one row; exported for tests and folded in by {@link foldRecap}.
+ *
+ * Ladder, best-first: a `/rename`/harness `label` → the last assistant line →
+ * the first-prompt topic. The `last` rung is agent-derived, so a session that
+ * produced work stops showing its stale first prompt as the title. (`topic` is
+ * the row's already-extracted first line, so image detection here is
+ * path-based; a pure-attachment turn with no first-line text stays on `prompt`.)
+ */
+export function deriveSessionRecap(row) {
+    const lastAgentLine = recapLine(row.tail?.length ? row.tail[row.tail.length - 1] : undefined);
+    const { clean: userPromptClean, kind: userPromptKind } = classifyUserPrompt(row.topic ?? '');
+    const label = recapLine(row.label);
+    const prompt = recapLine(userPromptClean || row.topic);
+    let title;
+    let recapSource;
+    if (label) {
+        title = label;
+        recapSource = 'label';
+    }
+    else if (lastAgentLine) {
+        title = lastAgentLine;
+        recapSource = 'last';
+    }
+    else if (prompt) {
+        title = prompt;
+        recapSource = 'prompt';
+    }
+    return { title, recapSource, userPromptClean: recapLine(userPromptClean), userPromptKind, lastAgentLine };
+}
+/** Fold the recap ladder onto every row (see {@link deriveSessionRecap}). */
+export function foldRecap(rows) {
+    for (const s of rows) {
+        const recap = deriveSessionRecap(s);
+        s.title = recap.title;
+        s.recapSource = recap.recapSource;
+        s.userPromptClean = recap.userPromptClean;
+        s.userPromptKind = recap.userPromptKind;
+        s.lastAgentLine = recap.lastAgentLine;
+    }
+}
+/**
+ * True when a crash-leaked orphan is genuinely DEAD and should be reaped from the
+ * reconnectable set rather than shown as resumable forever (RUSH-3011 / issue #3b).
+ *
+ * The gate is `abandoned` (no transcript write in {@link ABANDONED_STALE_MS}) AND
+ * a dead pid — exactly "past the stale threshold whose pid is gone". A live pid
+ * (an idle-but-unfinished session, the highest-risk state) is NEVER reaped, and
+ * neither is a recently-`closed`/`crashed` session that just exited (still
+ * resumable). `pidAlive` absent (a cloud row or an older peer that can't prove
+ * death) also stays un-reaped — reaping is fail-safe, never a guess.
+ */
+export function isReapableOrphan(row) {
+    return row.status === 'abandoned' && row.pidAlive === false;
+}
 /**
  * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,
  * when that orchestrator session is itself in the active set (it usually is — the

package/dist/lib/session/db.js

@@ -2112,8 +2112,10 @@ export function syncLabels(labelMap) {
             .prepare(`SELECT id, label FROM sessions WHERE id IN (${placeholders})`)
             .all(...chunk);
         for (const row of rows) {
-            const live = labelMap.get(row.id) ?? null;
-            if ((live ?? '') !== (row.label ?? '')) {
+            const live = labelMap.get(row.id)?.trim() || null;
+            // A missing/empty live label means "no refinement yet", not "erase the
+            // generated title or launch handle already stored for this session".
+            if (live && live !== (row.label ?? '')) {
                 updates.push({ id: row.id, label: live });
             }
         }

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

@@ -78,6 +78,8 @@ interface ClaudeSessionScan {
     version?: string;
     model?: string;
     topic?: string;
+    /** Harness-owned session name (`/rename` or Claude's generated `ai-title`). */
+    label?: string;
     messageCount: number;
     tokenCount?: number;
     /** Real generated (output) tokens, excluding cache-read/-write context. */

package/dist/lib/session/discover.js

@@ -1215,7 +1215,9 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, label) {
             accountKey: acct.key,
             accountOrg: acct.orgName ?? undefined,
             topic: scan.topic,
-            label,
+            // The live sessions metadata file contains only user `/rename` values;
+            // prefer it when present, then fall back to the title parsed from JSONL.
+            label: label || scan.label,
             messageCount: scan.messageCount,
             toolCallCount: scan.toolCallCount,
             tokenCount: scan.tokenCount,
@@ -1253,7 +1255,9 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, label) {
             accountKey: acct.key,
             accountOrg: acct.orgName ?? undefined,
             model: scan.model,
-            label,
+            // Keep parsed ai-title/custom-title values even when the transcript has
+            // no timestamp and therefore takes this stat-backed fallback path.
+            label: label || scan.label,
             messageCount: scan.messageCount,
             toolCallCount: scan.toolCallCount,
             tokenCount: scan.tokenCount,
@@ -3247,9 +3251,10 @@ export function finalizeClaudeScan(state) {
     const durationMs = state.firstTsMs !== undefined && state.lastTsMs !== undefined && state.lastTsMs > state.firstTsMs
         ? state.lastTsMs - state.firstTsMs
         : undefined;
-    // Prefer an explicit session title (user `/rename` > Claude auto-title) over
-    // the first-prompt topic.
-    const resolvedTopic = state.customTitle || state.aiTitle || state.topic;
+    // A topic is the first meaningful prompt. Harness-owned names travel in the
+    // separate label field so consumers can replace an early topic once Claude's
+    // generated title (or a later `/rename`) arrives.
+    const label = state.customTitle || state.aiTitle;
     const worktree = detectWorktree(state.cwd, state.gitBranch);
     const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
     return {
@@ -3258,7 +3263,8 @@ export function finalizeClaudeScan(state) {
         gitBranch: state.gitBranch,
         version: state.version,
         model: state.model,
-        topic: resolvedTopic,
+        topic: state.topic,
+        label,
         entrypoint: state.entrypoint,
         messageCount: state.messageCount,
         toolCallCount: state.toolCallCount,

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

@@ -34,5 +34,40 @@ export declare function extractSlashCommandFromToolInput(toolInput: Record<strin
 export declare const HEADLESS_PLAN_MODE_PREFIX = "You are running in HEADLESS PLAN MODE.";
 /** Strip framework noise from a raw session prompt, returning only meaningful user text. */
 export declare function cleanSessionPrompt(raw: string): string;
+/**
+ * How a session's first user turn reads once its framework noise is stripped —
+ * so a UI row can show `[image]` / `$ cmd` / `/skill` instead of a screenshot
+ * path, a pasted shell line, or a skill's install directory.
+ */
+export type UserPromptKind = 'text' | 'image' | 'command' | 'skill';
+export interface ClassifiedPrompt {
+    /**
+     * The one-line, display-ready form of the prompt — never a bare path. NOT
+     * length-capped: the recap card shows it in full; row consumers cap it
+     * themselves (`deriveSessionRecap`).
+     */
+    clean: string;
+    kind: UserPromptKind;
+}
+/**
+ * Classify a raw first user turn into a display-ready `{ clean, kind }`, so a
+ * Fleet/session row shows the user's actual intent rather than path noise:
+ *
+ *   - `skill`   — a `/skill` invocation's injected "Base directory for this
+ *                 skill: …" line collapses to `/<name>`.
+ *   - `command` — a `$ `-prefixed shell paste keeps only the first command.
+ *   - `image`   — a screenshot/image path standing alone, or an image
+ *                 attachment with no real accompanying text, becomes `[image]`.
+ *   - `text`    — everything else: wrapper tags stripped (via
+ *                 {@link cleanSessionPrompt}) and any inline image path replaced
+ *                 with `[image]` so a mixed prompt still drops the path.
+ *
+ * Pure and cross-harness (text markers, no per-agent branch). `hasImageAttachment`
+ * lets a caller that only has an already-extracted topic line still detect an
+ * image-only turn from the row's attachment list.
+ */
+export declare function classifyUserPrompt(raw: string | undefined, opts?: {
+    hasImageAttachment?: boolean;
+}): ClassifiedPrompt;
 /** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export declare function extractSessionTopic(raw: string): string | undefined;

package/dist/lib/session/prompt.js

@@ -145,6 +145,62 @@ export function cleanSessionPrompt(raw) {
         .filter(line => !NOISE_LINE_PATTERNS.some(pattern => pattern.test(line)));
     return meaningful.join('\n').trim();
 }
+/**
+ * A skill invocation injects a system line naming the skill's install directory:
+ *   "Base directory for this skill: /home/.../skills/<name>"
+ * which collapses to "/<name>" so a row shows the skill, not the path. Anchored
+ * to that exact injected line — a bare `.../skills/<name>` mention in ordinary
+ * prose is NOT a skill invocation and must keep its real text.
+ */
+const SKILL_BASEDIR_RE = /Base directory for this skill:\s*\S*[\/\\]skills[\/\\]([\w.-]+)/i;
+/**
+ * An explicit shell-prompt paste (`$ cmd`). Only the command survives. Deliberately
+ * `$`-only: a leading `>` is a markdown blockquote far more often than a shell
+ * prompt, so matching it misread quoted prose as a command.
+ */
+const COMMAND_PREFIX_RE = /^\$\s+(\S.*)$/;
+/**
+ * A filesystem path (absolute or `~`-rooted) ending in an image extension —
+ * matched even across the spaces a CleanShot filename carries. Used both to
+ * detect an image-only prompt and to drop the path from a mixed one.
+ */
+const IMAGE_PATH_RE = /[\/~][^\n]*?\.(?:png|jpe?g|gif|webp|heic|bmp|svg)\b/i;
+/**
+ * Classify a raw first user turn into a display-ready `{ clean, kind }`, so a
+ * Fleet/session row shows the user's actual intent rather than path noise:
+ *
+ *   - `skill`   — a `/skill` invocation's injected "Base directory for this
+ *                 skill: …" line collapses to `/<name>`.
+ *   - `command` — a `$ `-prefixed shell paste keeps only the first command.
+ *   - `image`   — a screenshot/image path standing alone, or an image
+ *                 attachment with no real accompanying text, becomes `[image]`.
+ *   - `text`    — everything else: wrapper tags stripped (via
+ *                 {@link cleanSessionPrompt}) and any inline image path replaced
+ *                 with `[image]` so a mixed prompt still drops the path.
+ *
+ * Pure and cross-harness (text markers, no per-agent branch). `hasImageAttachment`
+ * lets a caller that only has an already-extracted topic line still detect an
+ * image-only turn from the row's attachment list.
+ */
+export function classifyUserPrompt(raw, opts = {}) {
+    const text = (raw ?? '').replace(/\r/g, '').trim();
+    const skill = text.match(SKILL_BASEDIR_RE);
+    if (skill)
+        return { clean: `/${skill[1]}`, kind: 'skill' };
+    const firstLine = text.split('\n').map(line => line.trim()).find(Boolean) ?? '';
+    const cmd = firstLine.match(COMMAND_PREFIX_RE);
+    if (cmd)
+        return { clean: `$ ${cmd[1]}`.trim(), kind: 'command' };
+    const cleaned = cleanSessionPrompt(text);
+    const cleanedFirst = cleaned.split('\n').map(line => line.trim()).find(Boolean) ?? '';
+    const imgMatch = firstLine.match(IMAGE_PATH_RE);
+    const imageOnly = !!imgMatch && firstLine.replace(imgMatch[0], '').replace(/[^\w]/g, '').length <= 8;
+    if (imageOnly || (opts.hasImageAttachment && !cleanedFirst)) {
+        return { clean: '[image]', kind: 'image' };
+    }
+    const display = (cleanedFirst || firstLine).replace(IMAGE_PATH_RE, '[image]').trim();
+    return { clean: display, kind: 'text' };
+}
 /** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export function extractSessionTopic(raw) {
     if (!raw.trim())

package/dist/lib/session/remote/watch.d.ts

@@ -1,4 +1,4 @@
-import type { ActiveSession } from '../active.js';
+import { type ActiveSession } from '../active.js';
 import { readActiveSessionsCache } from '../session-cache.js';
 export declare const SESSION_WATCH_VERSION: 1;
 export declare const SESSION_WATCH_HEARTBEAT_MS = 15000;

package/dist/lib/session/remote/watch.js

@@ -8,6 +8,7 @@ import { deviceIdentityArgs, sshTargetFor } from '../../devices/connect.js';
 import { machineId, normalizeHost } from '../../machine-id.js';
 import { SSH_OPTS, controlOpts, shellQuote } from '../../ssh-exec.js';
 import { buildWindowsAgentsCommand, remoteShellFor } from '../../hosts/remote-cmd.js';
+import { isReapableOrphan } from '../active.js';
 import { activeSessionsJournalPath, activeSessionJournalIdentity, readActiveSessionsCache, } from '../session-cache.js';
 export const SESSION_WATCH_VERSION = 1;
 export const SESSION_WATCH_HEARTBEAT_MS = 15_000;
@@ -18,7 +19,11 @@ export function sessionWatchRowKey(scope, row) {
 }
 export function toSessionWatchRow(scope, row) {
     const rowKey = sessionWatchRowKey(scope, row);
-    const resumable = Boolean(row.sessionId);
+    // A dead, days-stale crash-orphan is folded OUT of the reconnectable set — it
+    // is not resumable, so the "Needs reconnecting" list stops ballooning with
+    // leaked --device tunnel sessions (RUSH-3011 / issue #3b). A live or
+    // recently-exited session stays resumable.
+    const resumable = Boolean(row.sessionId) && !isReapableOrphan(row);
     const viewingIn = row.viewingIn
         ? [row.viewingIn.app, row.viewingIn.tab ? `tab ${row.viewingIn.tab}` : undefined].filter(Boolean).join(' ')
         : null;

package/dist/lib/session/render.js

@@ -9,7 +9,7 @@
 import chalk from 'chalk';
 import { truncate } from '../format.js';
 import { summarizeToolUse } from './parse.js';
-import { cleanSessionPrompt, extractSessionTopic } from './prompt.js';
+import { cleanSessionPrompt, classifyUserPrompt, extractSessionTopic } from './prompt.js';
 import { renderMarkdown } from '../markdown.js';
 import { redactSecrets } from '../redact.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from './digest.js';
@@ -635,8 +635,12 @@ export function renderSummary(events, cwd) {
     // 1. Prompt
     if (firstUserMessage) {
         const cleaned = cleanSessionPrompt(firstUserMessage);
-        if (cleaned) {
-            lines.push(chalk.bold('Prompt:') + ' ' + cleaned.split('\n')[0]);
+        // Show the classified prompt (a screenshot path folds to `[image]`, a
+        // pasted `$ cmd` to the command, a skill install path to `/<name>`) so the
+        // recap's first line is intent, never path noise (RUSH-3011).
+        const { clean } = classifyUserPrompt(firstUserMessage, { hasImageAttachment: attachments.length > 0 });
+        if (clean || cleaned) {
+            lines.push(chalk.bold('Prompt:') + ' ' + (clean || cleaned.split('\n')[0]));
             const secondLine = cleaned.split('\n')[1]?.trim();
             if (secondLine)
                 lines.push('  ' + secondLine);

package/dist/lib/session/session-cache.js

@@ -27,7 +27,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { createMemoryCache } from '../memory-cache.js';
 import { getCacheDir } from '../state.js';
-import { sessionProcessIsLocal } from './active.js';
+import { backfillActiveRowsFromIndex, sessionProcessIsLocal } from './active.js';
 /** Snapshot file under `getCacheDir()` (regenerable, gitignored). */
 const SNAPSHOT_FILE = '.active-sessions.json';
 /** Immutable-field memo file (keyed by sessionId + transcript mtime). */
@@ -376,6 +376,10 @@ export async function loadLocalActiveSessions(opts = {}) {
             return getActiveSessions({ localOnly: true });
         });
     const sessions = await gather();
+    // The index owns transcript-derived labels (Claude custom-title / ai-title).
+    // Enrich before publishing so the canonical watch snapshot carries the same
+    // label as one-shot `sessions --active` output.
+    backfillActiveRowsFromIndex(sessions);
     for (const s of sessions)
         applyImmutableMemo(s);
     updateImmutableMemos(sessions, now);

package/dist/lib/session/trajectory-compare.d.ts

@@ -0,0 +1,47 @@
+import type { SessionMeta } from './types.js';
+import type { SessionTrajectory, TrajectoryStep } from './trajectory.js';
+/** Where two sessions' tool sequences first stop lining up. */
+export interface TrajectoryDivergence {
+    /** Ordinal of the last step both sessions still agree on (0 if none). */
+    afterOrdinalA: number;
+    afterOrdinalB: number;
+    /** ms into each session's own timeline where the divergence begins. */
+    startMsA: number;
+    startMsB: number;
+    /** One-line description of what differs — the next tool step on each side. */
+    detail: string;
+}
+/** Aggregate numbers for one side of a compare — the summary table row. */
+export interface TrajectorySummary {
+    session: SessionMeta;
+    toolCount: number;
+    errorCount: number;
+    spanMs: number;
+    outputTokens: number;
+}
+/** The result of diffing two trajectories. */
+export interface TrajectoryComparison {
+    a: SessionTrajectory;
+    b: SessionTrajectory;
+    /** Undefined only when the tool sequences are identical (or one/both are empty and equal). */
+    divergence?: TrajectoryDivergence;
+    /** Tool steps present in `b` with no counterpart in `a`, in `b`'s order. */
+    added: TrajectoryStep[];
+    /** Tool steps present in `a` with no counterpart in `b`, in `a`'s order. */
+    removed: TrajectoryStep[];
+    summaryA: TrajectorySummary;
+    summaryB: TrajectorySummary;
+    /** Tool steps dropped from the diff computation by the `maxDiffSteps` cap, per side. */
+    truncatedA: number;
+    truncatedB: number;
+}
+export interface DiffTrajectoriesOptions {
+    /** Cap on tool steps considered per side (the LCS table is O(n*m)). Default 1000. */
+    maxDiffSteps?: number;
+}
+/**
+ * Diff two trajectories: align their tool-step sequences, find the first
+ * divergence, and collect the steps each session ran that the other never
+ * did. Never mutates either input.
+ */
+export declare function diffTrajectories(a: SessionTrajectory, b: SessionTrajectory, options?: DiffTrajectoriesOptions): TrajectoryComparison;

package/dist/lib/session/trajectory-compare.js

@@ -0,0 +1,116 @@
+/**
+ * Diff two {@link SessionTrajectory} models for `agents sessions trace <a> <b>` —
+ * the second selector turns the single-session trajectory into a **compare**.
+ *
+ * Aligns the two sessions' TOOL steps (thinking steps carry no comparable
+ * identity) with the `diff` package's `diffArrays` (already a dependency,
+ * `lib/diff-text.ts`), comparator-keyed on tool name, in order — cheap,
+ * deterministic, and matches how a human reads "where did these two runs
+ * diverge": the first point their tool sequence stops lining up.
+ *
+ * Pure and framework-free, exactly like `trajectory.ts`: takes two already-built
+ * `SessionTrajectory` models (never re-parses a transcript) and returns a plain
+ * diff object the HTML/text/JSON renderers project.
+ */
+import { diffArrays } from 'diff';
+const DEFAULT_MAX_DIFF_STEPS = 1000;
+/**
+ * Turn `diffArrays`' run-length change objects into a per-step edit script.
+ *
+ * `diffArrays(a, b, { comparator })` (Myers' diff under the hood) returns
+ * consecutive-run chunks, not individual elements, and — per its own docs —
+ * an unchanged chunk's `value` is drawn from `b`, not `a`. Neither shape is
+ * what a divergence marker needs (a stepA/stepB PAIR per matched step, with
+ * both sides' own ordinals/timestamps), so this walks two cursors over the
+ * original arrays in lockstep with the run lengths `diffArrays` reports,
+ * recovering the exact `a[i]`/`b[j]` pairing for every `same` step.
+ */
+function computeEditScript(a, b) {
+    const changes = diffArrays(a, b, { comparator: (x, y) => x.tool === y.tool });
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    for (const change of changes) {
+        const count = change.count ?? change.value.length;
+        if (change.removed) {
+            for (let k = 0; k < count; k++)
+                ops.push({ type: 'remove', stepA: a[i++] });
+        }
+        else if (change.added) {
+            for (let k = 0; k < count; k++)
+                ops.push({ type: 'add', stepB: b[j++] });
+        }
+        else {
+            for (let k = 0; k < count; k++)
+                ops.push({ type: 'same', stepA: a[i++], stepB: b[j++] });
+        }
+    }
+    return ops;
+}
+function describeDivergence(op) {
+    if (op.type === 'remove')
+        return `${op.stepA.tool ?? op.stepA.kind} — only in the first session`;
+    if (op.type === 'add')
+        return `${op.stepB.tool ?? op.stepB.kind} — only in the second session`;
+    return '';
+}
+function summarize(t) {
+    return {
+        session: t.session,
+        toolCount: t.stats.toolCount,
+        errorCount: t.errorCount,
+        spanMs: t.spanMs,
+        outputTokens: t.stats.outputTokens,
+    };
+}
+/**
+ * Diff two trajectories: align their tool-step sequences, find the first
+ * divergence, and collect the steps each session ran that the other never
+ * did. Never mutates either input.
+ */
+export function diffTrajectories(a, b, options = {}) {
+    const maxDiffSteps = options.maxDiffSteps ?? DEFAULT_MAX_DIFF_STEPS;
+    const allToolStepsA = a.steps.filter((s) => s.kind === 'tool');
+    const allToolStepsB = b.steps.filter((s) => s.kind === 'tool');
+    const toolStepsA = allToolStepsA.slice(0, maxDiffSteps);
+    const toolStepsB = allToolStepsB.slice(0, maxDiffSteps);
+    const truncatedA = allToolStepsA.length - toolStepsA.length;
+    const truncatedB = allToolStepsB.length - toolStepsB.length;
+    const ops = computeEditScript(toolStepsA, toolStepsB);
+    const added = [];
+    const removed = [];
+    let divergence;
+    let lastSameA;
+    let lastSameB;
+    for (const op of ops) {
+        if (op.type === 'same') {
+            lastSameA = op.stepA;
+            lastSameB = op.stepB;
+            continue;
+        }
+        if (op.type === 'remove')
+            removed.push(op.stepA);
+        else
+            added.push(op.stepB);
+        if (!divergence) {
+            divergence = {
+                afterOrdinalA: lastSameA?.ordinal ?? 0,
+                afterOrdinalB: lastSameB?.ordinal ?? 0,
+                startMsA: op.type === 'remove' ? op.stepA.startMs : (lastSameA?.startMs ?? 0),
+                startMsB: op.type === 'add' ? op.stepB.startMs : (lastSameB?.startMs ?? 0),
+                detail: describeDivergence(op),
+            };
+        }
+    }
+    return {
+        a,
+        b,
+        divergence,
+        added,
+        removed,
+        summaryA: summarize(a),
+        summaryB: summarize(b),
+        truncatedA,
+        truncatedB,
+    };
+}

package/dist/lib/session/trajectory-html.d.ts

@@ -0,0 +1,15 @@
+import type { SessionTrajectory } from './trajectory.js';
+import type { TrajectoryComparison } from './trajectory-compare.js';
+import type { SessionLineage } from './trajectory-lineage.js';
+/** Render one session's trajectory as a self-contained HTML page. */
+export declare function renderTrajectoryHtml(model: SessionTrajectory): string;
+/** Render a two-session {@link TrajectoryComparison} as a self-contained HTML page. */
+export declare function renderTrajectoryCompareHtml(cmp: TrajectoryComparison): string;
+/**
+ * Render a {@link SessionLineage} as ONE self-contained HTML page: the inline-SVG
+ * delegation graph (orchestrator on top, the sessions it spawned below, edges
+ * auto-discovered from the team records) plus a per-node summary card revealed
+ * by clicking a node. Same shell, redaction, and no-CDN rule as the other two
+ * layouts; local paths (`filePath`/`cwd`) are deliberately never rendered.
+ */
+export declare function renderLineageHtml(lineage: SessionLineage): string;