@phnx-labs/agents-cli 1.22.45 → 1.22.47

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

@@ -0,0 +1,92 @@
+import type { SessionMeta } from './types.js';
+/**
+ * What a node is in the graph, decided from real signals only:
+ *   - `orchestrator` — it spawned at least one other session in this graph.
+ *   - `teammate`     — an `agents teams` teammate (a `meta.json` record backs it).
+ *   - `subagent`     — an SDK/`sdk-cli` spawn with no teammate record.
+ *   - `session`      — an ordinary session: no children, not team-spawned.
+ */
+export type LineageRole = 'orchestrator' | 'teammate' | 'subagent' | 'session';
+/**
+ * How recently the node's session did anything, relative to `now`. This is a
+ * RECENCY signal, not a verdict: nothing on `SessionMeta` records whether the
+ * work succeeded, so the graph never claims "merged" or "crashed". A node that
+ * opened a PR carries {@link LineageNode.prNumber}, which is a fact.
+ */
+export type LineageActivity = 'active' | 'idle' | 'stale';
+/** One session in the lineage graph. */
+export interface LineageNode {
+    session: SessionMeta;
+    id: string;
+    shortId: string;
+    agent: string;
+    /** Teammate handle from its team record, when it has one. */
+    handle?: string;
+    /** Team name (`task_name`) from its team record, when it has one. */
+    team?: string;
+    /** Teammate launch mode (plan/edit/auto/skip) from its team record. */
+    mode?: string;
+    role: LineageRole;
+    /** Hops from the root: 0 for the root itself. */
+    depth: number;
+    /** Indexed tool calls (`SessionMeta.toolCallCount`), 0 when unrecorded. */
+    toolCount: number;
+    /** Wall-clock span in ms (`SessionMeta.durationMs`), 0 when unrecorded. */
+    durationMs: number;
+    activity: LineageActivity;
+    /** PR the session opened, when it opened one. */
+    prNumber?: number;
+    /** How many children this node has in this graph. */
+    childCount: number;
+}
+/** A parent → child delegation edge, and which record established it. */
+export interface LineageEdge {
+    parent: string;
+    child: string;
+    /**
+     * `parentSessionId` — the child's own team record named this orchestrator.
+     * `teamSpawner`     — the child's record named none, but its whole team agreed
+     *                     on one spawner (`groupSessionsByTeam.spawnerSessionId`).
+     */
+    source: 'parentSessionId' | 'teamSpawner';
+}
+/** The resolved delegation graph rooted at one session. */
+export interface SessionLineage {
+    rootId: string;
+    /** The root first, then breadth-first; siblings ordered by spawn time. */
+    nodes: LineageNode[];
+    edges: LineageEdge[];
+    /** Distinct team names across the graph, for the header line. */
+    teams: string[];
+    /**
+     * Parent session ids a node pointed at that are not in the pool (the
+     * orchestrator's transcript was never indexed, or the scan window cut it off).
+     * Surfaced rather than dropped so a missing edge is never silent.
+     */
+    unresolvedParentIds: string[];
+}
+export interface BuildLineageOptions {
+    /**
+     * Which session the graph is about. The graph is always rooted at that
+     * session's TOPMOST ancestor in the pool, so passing a child still renders its
+     * whole team. Defaults to the first session in `sessions`.
+     */
+    rootId?: string;
+    /** Epoch ms used to classify {@link LineageActivity}. Defaults to `Date.now()`. */
+    now?: number;
+    /** Last activity within this many ms is `active`. Default 5 minutes. */
+    activeWithinMs?: number;
+    /** Last activity within this many ms is `idle`; older is `stale`. Default 24 hours. */
+    idleWithinMs?: number;
+}
+/**
+ * Build the delegation graph rooted at one session.
+ *
+ * `sessions` is the discovery pool WITH team sessions included — team-origin
+ * rows are hidden from the ordinary listing by default (`AGENTS.md` invariant 7),
+ * so a caller that filters them out first would resolve an empty graph. It MUST
+ * contain the `rootId` row (a root outside the pool throws rather than rooting
+ * the graph somewhere else). The returned graph is the root's subtree: unrelated
+ * sessions in the pool supply edges but never become nodes.
+ */
+export declare function buildLineage(sessions: SessionMeta[], options?: BuildLineageOptions): SessionLineage;

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

@@ -0,0 +1,195 @@
+/**
+ * Team lineage for `agents sessions trace <parent> --tree` — the third and last
+ * layout of the trace surface (PR3/3), after the single trajectory and the
+ * two-session compare.
+ *
+ * A lineage is the delegation graph of an orchestrator and the sessions it
+ * spawned. The edges are not invented here: they already exist in the session
+ * index as `teamOrigin.parentSessionId` (the orchestrator recorded in a
+ * teammate's `meta.json`, `team-filter.ts:151`), with a second pass over
+ * `groupSessionsByTeam`'s agreed-on `spawnerSessionId` (`team-filter.ts:317`)
+ * for teammates whose own record carries no parent. This module only resolves
+ * and orders them.
+ *
+ * **A node is a SESSION, never an inline sub-agent.** A `Task`/`Agent` tool call
+ * is a step inside ONE transcript (`trajectory.ts` marks it
+ * `delegation: 'inline-task'`) and produces no session row, so it can never
+ * become a node here — the graph is built strictly from `SessionMeta` rows that
+ * `discoverSessions` returned.
+ *
+ * Pure and framework-free like `trajectory.ts` / `trajectory-compare.ts`: it
+ * takes session metadata (no transcript parsing, no clock of its own — `now` is
+ * an option) and returns a plain object the HTML/text/JSON renderers project.
+ */
+import { enrichTeamOrigins, groupSessionsByTeam, teamRowKind } from './team-filter.js';
+const DEFAULT_ACTIVE_WITHIN_MS = 5 * 60_000;
+const DEFAULT_IDLE_WITHIN_MS = 24 * 60 * 60_000;
+/** Recency signal for a row: last activity, else the creation timestamp. */
+function rowTs(session) {
+    return session.lastActivity ?? session.timestamp;
+}
+/** Spawn time for ordering siblings: the team record's `started_at`, else creation. */
+function spawnTs(session) {
+    return session.teamOrigin?.startedAt ?? session.timestamp;
+}
+function classifyActivity(session, now, activeWithin, idleWithin) {
+    const ts = new Date(rowTs(session)).getTime();
+    if (Number.isNaN(ts))
+        return 'stale';
+    const age = now - ts;
+    if (age <= activeWithin)
+        return 'active';
+    if (age <= idleWithin)
+        return 'idle';
+    return 'stale';
+}
+/**
+ * How far outside a run's own spawn window a parentless teammate may still be
+ * adopted by that run's spawner.
+ *
+ * `groupSessionsByTeam` buckets by team NAME alone (`team-filter.ts:292`), and
+ * `--tree` scans the pool all-time, so two separate runs of a team called
+ * `fleet-resume` land in one group — without a window, the older run's
+ * parentless teammates get adopted by the newer run's orchestrator and render as
+ * its children. A teams run spawns its teammates within minutes of each other,
+ * so an hour is generous for the first or last of them and still far tighter
+ * than the all-time scan that caused the misattribution.
+ */
+const SPAWNER_ADOPTION_SLACK_MS = 60 * 60_000;
+function spawnMs(session) {
+    return new Date(spawnTs(session)).getTime();
+}
+/**
+ * Resolve every parent → child edge the session index knows about.
+ *
+ * Two passes, in priority order: a teammate's own `parentSessionId` wins, and
+ * only a teammate that carries none inherits its team's agreed-on spawner —
+ * and then only if it was spawned inside that run's own window (see
+ * {@link SPAWNER_ADOPTION_SLACK_MS}). A self-edge (a record naming its own
+ * session) is dropped: it would make the root its own child and hang the walk.
+ */
+function resolveParents(sessions) {
+    const parentOf = new Map();
+    for (const session of sessions) {
+        const parent = session.teamOrigin?.parentSessionId;
+        if (parent && parent !== session.id) {
+            parentOf.set(session.id, { parent, child: session.id, source: 'parentSessionId' });
+        }
+    }
+    for (const group of groupSessionsByTeam(sessions)) {
+        const spawner = group.spawnerSessionId;
+        if (!spawner)
+            continue;
+        // The window of the teammates that actually named this spawner — the run.
+        const named = group.sessions.filter((r) => r.teamOrigin.parentSessionId === spawner).map(spawnMs).filter((t) => !Number.isNaN(t));
+        if (named.length === 0)
+            continue;
+        const from = Math.min(...named) - SPAWNER_ADOPTION_SLACK_MS;
+        const to = Math.max(...named) + SPAWNER_ADOPTION_SLACK_MS;
+        for (const row of group.sessions) {
+            if (parentOf.has(row.id) || row.id === spawner)
+                continue;
+            const ts = spawnMs(row);
+            if (Number.isNaN(ts) || ts < from || ts > to)
+                continue;
+            parentOf.set(row.id, { parent: spawner, child: row.id, source: 'teamSpawner' });
+        }
+    }
+    return parentOf;
+}
+/** Walk up from `startId` to the topmost ancestor present in the pool. */
+function topmostAncestor(startId, parentOf, byId) {
+    let current = startId;
+    const seen = new Set([current]);
+    for (;;) {
+        const edge = parentOf.get(current);
+        if (!edge || !byId.has(edge.parent) || seen.has(edge.parent))
+            return current;
+        current = edge.parent;
+        seen.add(current);
+    }
+}
+function roleFor(session, childCount) {
+    if (childCount > 0)
+        return 'orchestrator';
+    if (session.teamOrigin)
+        return teamRowKind(session.teamOrigin);
+    return 'session';
+}
+/**
+ * Build the delegation graph rooted at one session.
+ *
+ * `sessions` is the discovery pool WITH team sessions included — team-origin
+ * rows are hidden from the ordinary listing by default (`AGENTS.md` invariant 7),
+ * so a caller that filters them out first would resolve an empty graph. It MUST
+ * contain the `rootId` row (a root outside the pool throws rather than rooting
+ * the graph somewhere else). The returned graph is the root's subtree: unrelated
+ * sessions in the pool supply edges but never become nodes.
+ */
+export function buildLineage(sessions, options = {}) {
+    const now = options.now ?? Date.now();
+    const activeWithin = options.activeWithinMs ?? DEFAULT_ACTIVE_WITHIN_MS;
+    const idleWithin = options.idleWithinMs ?? DEFAULT_IDLE_WITHIN_MS;
+    const enriched = enrichTeamOrigins(sessions);
+    const byId = new Map(enriched.map((s) => [s.id, s]));
+    const parentOf = resolveParents(enriched);
+    const childrenOf = new Map();
+    const unresolved = new Set();
+    for (const edge of parentOf.values()) {
+        if (!byId.has(edge.parent)) {
+            unresolved.add(edge.parent);
+            continue;
+        }
+        const child = byId.get(edge.child);
+        (childrenOf.get(edge.parent) ?? childrenOf.set(edge.parent, []).get(edge.parent)).push(child);
+    }
+    for (const kids of childrenOf.values()) {
+        kids.sort((a, b) => (spawnTs(a) < spawnTs(b) ? -1 : spawnTs(a) > spawnTs(b) ? 1 : a.id.localeCompare(b.id)));
+    }
+    // A rootId the pool does not contain is a CALLER bug — silently rooting the
+    // graph at some unrelated first row is how a lineage renders the wrong team.
+    if (options.rootId && !byId.has(options.rootId)) {
+        throw new Error(`buildLineage: root session ${options.rootId} is not in the pool — the caller must include the root row.`);
+    }
+    const requested = options.rootId ?? enriched[0]?.id;
+    const rootId = requested ? topmostAncestor(requested, parentOf, byId) : '';
+    const root = rootId ? byId.get(rootId) : undefined;
+    if (!root) {
+        return { rootId: '', nodes: [], edges: [], teams: [], unresolvedParentIds: [...unresolved] };
+    }
+    // Breadth-first from the root, so the render order IS the drawing order:
+    // depth 0 on top, each level below it. `seen` guards a cyclic record.
+    const nodes = [];
+    const seen = new Set([rootId]);
+    const queue = [{ session: root, depth: 0 }];
+    const subtreeEdges = [];
+    while (queue.length > 0) {
+        const { session, depth } = queue.shift();
+        const kids = (childrenOf.get(session.id) ?? []).filter((k) => !seen.has(k.id));
+        nodes.push({
+            session,
+            id: session.id,
+            shortId: session.shortId || session.id.slice(0, 8),
+            agent: session.agent,
+            handle: session.teamOrigin?.handle,
+            team: session.teamOrigin?.team,
+            mode: session.teamOrigin?.mode ?? session.mode,
+            role: roleFor(session, kids.length),
+            depth,
+            toolCount: session.toolCallCount ?? 0,
+            durationMs: session.durationMs ?? 0,
+            activity: classifyActivity(session, now, activeWithin, idleWithin),
+            prNumber: session.prNumber,
+            childCount: kids.length,
+        });
+        for (const kid of kids) {
+            seen.add(kid.id);
+            subtreeEdges.push(parentOf.get(kid.id));
+            queue.push({ session: kid, depth: depth + 1 });
+        }
+    }
+    const teams = [...new Set(nodes.map((n) => n.team).filter((t) => !!t))].sort();
+    const nodeIds = new Set(nodes.map((n) => n.id));
+    const unresolvedForSubtree = [...unresolved].filter((parent) => enriched.some((s) => nodeIds.has(s.id) && parentOf.get(s.id)?.parent === parent));
+    return { rootId, nodes, edges: subtreeEdges, teams, unresolvedParentIds: unresolvedForSubtree };
+}

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

@@ -0,0 +1,37 @@
+import type { SessionTrajectory } from './trajectory.js';
+import type { TrajectoryComparison } from './trajectory-compare.js';
+import type { SessionLineage } from './trajectory-lineage.js';
+export interface RenderTrajectoryTextOptions {
+    /** Collapse to error steps and their immediate neighbours. */
+    errorsOnly?: boolean;
+    /** Cap on the step lines emitted; the remainder is collapsed with a count. */
+    maxSteps?: number;
+}
+/** Render one session's trajectory as compact, ANSI-free text. */
+export declare function renderTrajectoryText(model: SessionTrajectory, options?: RenderTrajectoryTextOptions): string;
+export interface RenderTrajectoryCompareTextOptions {
+    /** Cap on step lines listed per diff column; the remainder is collapsed with a count. Default 15. */
+    maxDiffLines?: number;
+}
+/**
+ * Render a two-session {@link TrajectoryComparison} as compact, ANSI-free text —
+ * both sessions' headline stats, the first divergence point, and the step-level
+ * diff (only-in-first / only-in-second), each capped so a triaging agent pays a
+ * bounded token cost regardless of how far the two runs diverge.
+ */
+export declare function renderTrajectoryCompareText(cmp: TrajectoryComparison, options?: RenderTrajectoryCompareTextOptions): string;
+/**
+ * Render a {@link SessionLineage} as a tree — the `--tree` text rendering an
+ * agent reads when it asks "what did this orchestrator spawn, and where did the
+ * fan-out go?".
+ *
+ * Drawn from the EDGES, not from each node's depth. Indenting by depth alone
+ * puts every depth-2 node under whichever depth-1 node happened to print last,
+ * so a nested teammate reads as a child of its aunt and its real parent is
+ * unrecoverable from the output — a lie an agent has no way to detect.
+ *
+ * One line per session: its handle/short id, harness, role, indexed tool count,
+ * span, recency and PR when it opened one. No per-step detail — lineage answers
+ * the shape of the fan-out; `agents sessions trace <child>` answers one child.
+ */
+export declare function renderLineageText(lineage: SessionLineage): string;

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

@@ -0,0 +1,277 @@
+/**
+ * Render a {@link SessionTrajectory} as a compact, ANSI-free, token-bounded text
+ * trajectory — the rendering an AGENT reads in-context when it asks "where did
+ * session X stall?" (the non-TTY / `--text` audience of `agents sessions trace`).
+ *
+ * Deliberately terse: a header line, the idle stalls, one line per step (tool,
+ * redacted label, duration, outcome), a "where the time went" line, and a bounded
+ * error-detail tail. No color, no box-drawing, no cursor codes — safe to splice
+ * straight into another agent's prompt. `errorsOnly` collapses the run to the
+ * error steps and their neighbours so a triaging agent pays only for the failures.
+ */
+import { formatTokenCount } from './render.js';
+const DEFAULT_MAX_STEPS = 80;
+const LABEL_COL = 40;
+/** Precise, compact per-step duration: "8m04s", "1.6s", "320ms", "—" for zero. */
+function dur(ms, estimated) {
+    if (ms <= 0)
+        return estimated ? '~0s' : '0s';
+    let s;
+    if (ms < 1000)
+        s = `${Math.round(ms)}ms`;
+    else if (ms < 60_000)
+        s = `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)}s`;
+    else {
+        const totalSec = Math.round(ms / 1000);
+        s = `${Math.floor(totalSec / 60)}m${String(totalSec % 60).padStart(2, '0')}s`;
+    }
+    return estimated ? `~${s}` : s;
+}
+function outcomeMark(step) {
+    if (step.outcome === 'error')
+        return '✗';
+    if (step.outcome === 'ok')
+        return 'ok';
+    return '';
+}
+function pad(text, width) {
+    return text.length >= width ? text : text + ' '.repeat(width - text.length);
+}
+function clipLabel(label) {
+    const oneLine = label.replace(/\s+/g, ' ').trim();
+    return oneLine.length <= LABEL_COL ? oneLine : `${oneLine.slice(0, LABEL_COL - 1)}…`;
+}
+function shareLine(model) {
+    // Program-keyed, mirroring the HTML panel — a Bash-heavy run reads as
+    // `git 56%  gh 33%  agents 11%`, never a single opaque `Bash 100%`.
+    const entries = Object.entries(model.programTimeShare)
+        .sort((a, b) => b[1] - a[1])
+        .filter(([, share]) => share >= 0.02)
+        .slice(0, 5)
+        .map(([program, share]) => `${program} ${Math.round(share * 100)}%`);
+    return entries.length > 0 ? `where the time went: ${entries.join('  ')}` : undefined;
+}
+/** The display tag for a step — the effective program for a shell call, else the tool. */
+function stepTag(step) {
+    return step.program ?? step.tool ?? step.kind;
+}
+/**
+ * Break the tool mix down BY PROGRAM — a Bash-heavy session reads as
+ * `git 92  agents 80  gh 69` instead of a single "Bash". Count-based.
+ */
+function programMixLine(model) {
+    const counts = new Map();
+    for (const step of model.steps) {
+        if (step.kind !== 'tool')
+            continue;
+        const tag = stepTag(step);
+        counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    }
+    const entries = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 8)
+        .map(([tag, n]) => `${tag} ${n}`);
+    return entries.length > 0 ? `commands: ${entries.join('  ')}` : undefined;
+}
+/** Select the steps to print: all of them, or (errorsOnly) errors + neighbours. */
+function selectSteps(steps, errorsOnly) {
+    if (!errorsOnly)
+        return steps;
+    const keep = new Set();
+    steps.forEach((step, i) => {
+        if (step.outcome === 'error') {
+            keep.add(i);
+            if (i > 0)
+                keep.add(i - 1);
+            if (i < steps.length - 1)
+                keep.add(i + 1);
+        }
+    });
+    const out = [];
+    let prevKept = -1;
+    const firstKept = steps.findIndex((_, i) => keep.has(i));
+    if (firstKept > 0)
+        out.push('gap'); // steps dropped before the first error neighbourhood
+    steps.forEach((step, i) => {
+        if (!keep.has(i))
+            return;
+        if (prevKept >= 0 && i - prevKept > 1)
+            out.push('gap');
+        out.push(step);
+        prevKept = i;
+    });
+    if (prevKept >= 0 && prevKept < steps.length - 1)
+        out.push('gap'); // steps dropped after the last
+    return out;
+}
+/** Render one session's trajectory as compact, ANSI-free text. */
+export function renderTrajectoryText(model, options = {}) {
+    const { session, stats } = model;
+    const errorsOnly = options.errorsOnly === true;
+    const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+    const lines = [];
+    // Header.
+    const spanMin = model.spanMs > 0 ? `${Math.max(1, Math.round(model.spanMs / 60_000))}m` : '0m';
+    const errPart = model.errorCount > 0 ? ` · ${model.errorCount}✗` : '';
+    const tokPart = stats.outputTokens > 0 ? ` · ${formatTokenCount(stats.outputTokens)} out` : '';
+    const modelPart = session.model ? `·${session.model}` : '';
+    lines.push(`${session.shortId || session.id} ${session.agent}${modelPart} · ${spanMin} · ${stats.toolCount} tools${errPart}${tokPart}`);
+    if (model.steps.length === 0) {
+        lines.push('(no events to visualize)');
+        return lines.join('\n') + '\n';
+    }
+    // Idle stalls, most notable first.
+    for (const gap of [...model.gaps].sort((a, b) => b.durationMs - a.durationMs).slice(0, 4)) {
+        lines.push(`idle ${dur(gap.durationMs, false)} after step ${gap.afterOrdinal} (stall)`);
+    }
+    // Steps.
+    const selected = selectSteps(model.steps, errorsOnly);
+    let printed = 0;
+    let omitted = 0;
+    for (const entry of selected) {
+        if (entry === 'gap') {
+            lines.push('  …');
+            continue;
+        }
+        if (printed >= maxSteps) {
+            omitted++;
+            continue;
+        }
+        const ord = pad(String(entry.ordinal).padStart(2, '0'), 3);
+        const tag = pad(stepTag(entry), 8);
+        const label = pad(clipLabel(entry.label), LABEL_COL);
+        const mark = outcomeMark(entry);
+        const exit = entry.exitCode !== undefined && entry.exitCode !== 0 ? ` exit ${entry.exitCode}` : '';
+        lines.push(`${ord} ${tag} ${label} ${dur(entry.durationMs, entry.durationEstimated)}${exit}${mark ? ' ' + mark : ''}`.trimEnd());
+        // A short, indented evidence line for an error step.
+        if (entry.outcome === 'error' && entry.detail) {
+            lines.push(`     ${clipLabel(entry.detail)}`);
+        }
+        printed++;
+    }
+    if (omitted > 0)
+        lines.push(`  … ${omitted} more step${omitted === 1 ? '' : 's'} (raise --json for the full model)`);
+    if (model.truncatedSteps > 0)
+        lines.push(`  … ${model.truncatedSteps} step${model.truncatedSteps === 1 ? '' : 's'} collapsed by the render cap`);
+    // Where the time went, then the command/program mix.
+    const share = shareLine(model);
+    if (share)
+        lines.push(share);
+    const mix = programMixLine(model);
+    if (mix)
+        lines.push(mix);
+    return lines.join('\n') + '\n';
+}
+const DEFAULT_MAX_DIFF_LINES = 15;
+function sessionLabel(session) {
+    return `${session.agent} ${session.shortId || session.id}`;
+}
+function summaryLine(summary) {
+    const spanMin = summary.spanMs > 0 ? `${Math.max(1, Math.round(summary.spanMs / 60_000))}m` : '0m';
+    const errPart = summary.errorCount > 0 ? ` · ${summary.errorCount}✗` : '';
+    const tokPart = summary.outputTokens > 0 ? ` · ${formatTokenCount(summary.outputTokens)} out` : '';
+    return `  ${sessionLabel(summary.session)} · ${spanMin} · ${summary.toolCount} tools${errPart}${tokPart}`;
+}
+function diffColumn(heading, steps, maxLines) {
+    if (steps.length === 0)
+        return [`${heading} (0): none`];
+    const lines = [`${heading} (${steps.length}):`];
+    const shown = steps.slice(0, maxLines);
+    for (const step of shown) {
+        const mark = outcomeMark(step);
+        lines.push(`  ${pad(stepTag(step), 8)} ${pad(clipLabel(step.label), LABEL_COL)} ${dur(step.durationMs, step.durationEstimated)}${mark ? ' ' + mark : ''}`.trimEnd());
+    }
+    const omitted = steps.length - shown.length;
+    if (omitted > 0)
+        lines.push(`  … ${omitted} more`);
+    return lines;
+}
+/**
+ * Render a two-session {@link TrajectoryComparison} as compact, ANSI-free text —
+ * both sessions' headline stats, the first divergence point, and the step-level
+ * diff (only-in-first / only-in-second), each capped so a triaging agent pays a
+ * bounded token cost regardless of how far the two runs diverge.
+ */
+export function renderTrajectoryCompareText(cmp, options = {}) {
+    const maxDiffLines = options.maxDiffLines ?? DEFAULT_MAX_DIFF_LINES;
+    const labelA = sessionLabel(cmp.a.session);
+    const labelB = sessionLabel(cmp.b.session);
+    const lines = [];
+    lines.push(`compare: ${labelA} vs ${labelB}`);
+    lines.push(summaryLine(cmp.summaryA));
+    lines.push(summaryLine(cmp.summaryB));
+    if (cmp.divergence) {
+        lines.push(`diverge after step ${cmp.divergence.afterOrdinalA}/${cmp.divergence.afterOrdinalB}: ${cmp.divergence.detail}`);
+    }
+    else {
+        lines.push('no divergence — tool sequences match');
+    }
+    if (cmp.truncatedA > 0 || cmp.truncatedB > 0) {
+        lines.push(`diff capped — ${cmp.truncatedA} step(s) from the first and ${cmp.truncatedB} from the second were not compared`);
+    }
+    lines.push(...diffColumn(`only in ${labelA}`, cmp.removed, maxDiffLines));
+    lines.push(...diffColumn(`only in ${labelB}`, cmp.added, maxDiffLines));
+    return lines.join('\n') + '\n';
+}
+/**
+ * Render a {@link SessionLineage} as a tree — the `--tree` text rendering an
+ * agent reads when it asks "what did this orchestrator spawn, and where did the
+ * fan-out go?".
+ *
+ * Drawn from the EDGES, not from each node's depth. Indenting by depth alone
+ * puts every depth-2 node under whichever depth-1 node happened to print last,
+ * so a nested teammate reads as a child of its aunt and its real parent is
+ * unrecoverable from the output — a lie an agent has no way to detect.
+ *
+ * One line per session: its handle/short id, harness, role, indexed tool count,
+ * span, recency and PR when it opened one. No per-step detail — lineage answers
+ * the shape of the fan-out; `agents sessions trace <child>` answers one child.
+ */
+export function renderLineageText(lineage) {
+    const lines = [];
+    const root = lineage.nodes[0];
+    if (!root) {
+        lines.push('(no lineage — the selected session spawned nothing indexed)');
+        return lines.join('\n') + '\n';
+    }
+    const teamPart = lineage.teams.length > 0 ? ` · team ${lineage.teams.map((t) => `"${t}"`).join(', ')}` : '';
+    const spawned = lineage.nodes.length - 1;
+    lines.push(`lineage: ${root.agent} ${root.shortId}${teamPart} · ${spawned} spawned session${spawned === 1 ? '' : 's'}`);
+    const byId = new Map(lineage.nodes.map((n) => [n.id, n]));
+    const childrenOf = new Map();
+    for (const edge of lineage.edges) {
+        (childrenOf.get(edge.parent) ?? childrenOf.set(edge.parent, []).get(edge.parent)).push(edge.child);
+    }
+    const describe = (node) => {
+        const name = node.handle && node.handle !== node.shortId ? `${node.handle} · ${node.shortId}` : node.shortId;
+        const bits = [node.agent, node.role, `${node.toolCount} tools`];
+        if (node.durationMs > 0)
+            bits.push(dur(node.durationMs, false));
+        bits.push(node.activity);
+        if (node.mode)
+            bits.push(node.mode);
+        if (node.prNumber)
+            bits.push(`PR #${node.prNumber}`);
+        return `${name} · ${bits.join(' · ')}`;
+    };
+    // Depth-first from the root so a child always prints directly under its own
+    // parent; `prefix` carries the ancestors' continuation bars.
+    const walk = (id, prefix) => {
+        const kids = childrenOf.get(id) ?? [];
+        kids.forEach((childId, i) => {
+            const node = byId.get(childId);
+            if (!node)
+                return;
+            const last = i === kids.length - 1;
+            lines.push(`${prefix}${last ? '└─ ' : '├─ '}${describe(node)}`);
+            walk(childId, `${prefix}${last ? '   ' : '│  '}`);
+        });
+    };
+    lines.push(describe(root));
+    walk(root.id, '');
+    if (lineage.unresolvedParentIds.length > 0) {
+        lines.push(`unresolved parent${lineage.unresolvedParentIds.length === 1 ? '' : 's'} (not in the scanned pool): ` +
+            lineage.unresolvedParentIds.join(', '));
+    }
+    return lines.join('\n') + '\n';
+}