@phnx-labs/agents-cli 1.22.21 → 1.22.22

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 1.22.22
+
+- **New: `agents insights` — how you work, split by the Claude account that did the
+  work.** Tool and language mix, friction (interruptions, tool-error classes, your own
+  reply latency), what you changed (line deltas, files, commits), an hour-of-day
+  rhythm, and how often two accounts ran at once. Modelled on Claude Code's
+  `/insights`, with the difference that motivated it: that command reads one account's
+  directory, while `balanced` rotation sprays sessions across every signed-in account,
+  so it describes a fraction of the work and credits all of it to one org. Source:
+  `apps/cli/src/commands/insights.ts`, `apps/cli/src/lib/session/insights.ts`.
+
+  Deterministic and offline by default. `--narrative` is opt-in and adds a written read
+  by piping the *aggregate* — never raw transcripts, unlike `/insights` — through a
+  headless `claude -p`. Facets are cached per session in a new `session_insights` table
+  keyed on `(file_mtime_ms, file_size)`, so the first run parses every transcript once
+  and later runs re-read only what changed.
+
+- **The Claude parser can surface interruption markers on request.** `[Request
+  interrupted` text was dropped outright, so the signal was unrecoverable downstream.
+  `parseSession(..., { includeInterrupts: true })` now emits a dedicated `interrupt`
+  event. It stays OFF by default because the event array is a versioned consumer
+  contract: `agents sessions <id> --json` serializes it verbatim, `computeSummaryStats`
+  folds every timestamp into the session duration, and the live-state reader inspects a
+  fixed window of trailing events. `agents insights` is the only caller that opts in.
+  Source: `apps/cli/src/lib/session/parse.ts`.
+
+- **`digest.ts` now classifies droid's `Create` as a file write.** Its tool-vocabulary
+  set claimed cross-harness coverage but omitted it, so droid file creations classified
+  as nothing. Source: `apps/cli/src/lib/session/digest.ts`.
+
+- **Codex usage bars no longer show a previous account's numbers after you switch accounts.** `agents view` derives a Codex version's usage from that home's session transcripts, which carry no account identity and are not removed on logout — so after logging a version out and into a different ChatGPT account, the bar kept showing the old account's last-seen percentage (e.g. "S: 99%") until the new account ran a session. Usage is now scoped to the current login: only sessions written at/after the id_token's `auth_time` (the OIDC authentication time) count, and a signed-out home reports no usage. `auth_time` is used rather than the auth.json file mtime because Codex rewrites auth.json on every token refresh, but a refresh does not re-authenticate, so `auth_time` stays at the real login — an actively-refreshing account keeps its bar, only a real re-login or account switch moves the floor. Source: `apps/cli/src/lib/usage.ts`.
+
+- **The interactive session picker's detailed preview no longer collapses to empty.**
+  `agents sessions`, `agents sessions <query>`, and `agents sessions --active` open the
+  picker with the rich preview pane (prompt, files, hooks, errors, tests, last response)
+  on by default, but the preview had no guaranteed height: a 15-row list
+  (`PICKER_RECENT_COUNT`) on a short terminal consumed the whole viewport, the computed
+  `availablePreviewRows` went to zero, and the pane silently vanished — worse when
+  fleet-unreachable warnings and the hidden-session footer had scrolled lines above the
+  prompt. The picker now caps the visible list page so the preview keeps a floor of
+  `PREVIEW_MIN_ROWS` (6) rows, and accounts for the lines printed above the prompt so
+  those notices and the preview stay on screen together. Applied consistently across
+  `itemPicker`, `dynamicPicker`, and `multiItemPicker`, so the bare browser, the query
+  picker, and the `--active` browser all behave the same; the space/tab preview toggle
+  is unchanged. Source: `apps/cli/src/lib/picker.ts`,
+  `apps/cli/src/commands/sessions-picker.ts`, `apps/cli/src/commands/sessions.ts`.
+
 ## 1.22.21
 
 - **`agents secrets exec <bundle> -- <cmd>` now resolves a locked keychain bundle

package/dist/commands/insights.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Insights command — how you actually work, split by the account that did the work.
+ *
+ * The behavioural sibling of the existing rollups, and deliberately not a duplicate of
+ * any of them:
+ *
+ *   agents cost      what you spent            ($ and duration)
+ *   agents output    what shipped              (burn vs PRs and commits)
+ *   agents usage     live quota headroom       (rate-limit windows, right now)
+ *   agents trends    aggregate distributions   (harness mix, tools-per-session, token ratios)
+ *   agents sessions  browse individual work    (search, resume, render)
+ *   agents insights  HOW you work              (tools, friction, rhythm, per account)
+ *
+ * The closest neighbour is `agents trends`, and the boundary is the data path: trends
+ * reads counters — `tool_scan_ledger` call counts and the analytics warehouse — to
+ * produce distributions ("how many tool calls per session, by harness"). This reads
+ * transcript CONTENT through `parseSession` to produce behaviour ("which tools, which
+ * languages, where it went wrong, when you were working"), and splits all of it by
+ * account, a dimension trends does not have. They overlap in spirit on tool and model
+ * mix; they do not read the same store or answer the same question.
+ *
+ * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
+ * command reads one account's directory, while `balanced` rotation sprays sessions
+ * across every signed-in account. This reads the whole index and reports the accounts
+ * apart — see lib/session/claude-accounts.ts for how a transcript is attributed.
+ *
+ * The deterministic report makes zero network calls. `--narrative` is opt-in and adds
+ * the coaching prose by piping the AGGREGATE (never raw transcripts) through a headless
+ * `claude -p`.
+ */
+import type { Command } from 'commander';
+export declare function registerInsightsCommand(program: Command): void;

package/dist/commands/insights.js

@@ -0,0 +1,478 @@
+/**
+ * Insights command — how you actually work, split by the account that did the work.
+ *
+ * The behavioural sibling of the existing rollups, and deliberately not a duplicate of
+ * any of them:
+ *
+ *   agents cost      what you spent            ($ and duration)
+ *   agents output    what shipped              (burn vs PRs and commits)
+ *   agents usage     live quota headroom       (rate-limit windows, right now)
+ *   agents trends    aggregate distributions   (harness mix, tools-per-session, token ratios)
+ *   agents sessions  browse individual work    (search, resume, render)
+ *   agents insights  HOW you work              (tools, friction, rhythm, per account)
+ *
+ * The closest neighbour is `agents trends`, and the boundary is the data path: trends
+ * reads counters — `tool_scan_ledger` call counts and the analytics warehouse — to
+ * produce distributions ("how many tool calls per session, by harness"). This reads
+ * transcript CONTENT through `parseSession` to produce behaviour ("which tools, which
+ * languages, where it went wrong, when you were working"), and splits all of it by
+ * account, a dimension trends does not have. They overlap in spirit on tool and model
+ * mix; they do not read the same store or answer the same question.
+ *
+ * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
+ * command reads one account's directory, while `balanced` rotation sprays sessions
+ * across every signed-in account. This reads the whole index and reports the accounts
+ * apart — see lib/session/claude-accounts.ts for how a transcript is attributed.
+ *
+ * The deterministic report makes zero network calls. `--narrative` is opt-in and adds
+ * the coaching prose by piping the AGGREGATE (never raw transcripts) through a headless
+ * `claude -p`.
+ */
+import * as fs from 'fs';
+import chalk from 'chalk';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { addHostOption } from '../lib/hosts/option.js';
+import { setHelpSections } from '../lib/help.js';
+import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
+import { querySessions, readSessionInsights, writeSessionInsights, clearSessionInsights, } from '../lib/session/db.js';
+import { parseSession } from '../lib/session/parse.js';
+import { computeInsightFacets, mergeFacets, newFacetAccumulator, detectOverlap, percentile, bucketGaps, topEntries, } from '../lib/session/insights.js';
+import { formatUsd } from '../lib/pricing/index.js';
+import { formatDuration } from '../lib/session/render.js';
+import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
+const execFileAsync = promisify(execFile);
+function resolveGroup(by) {
+    if (by === undefined)
+        return 'account';
+    if (by === 'account' || by === 'agent' || by === 'project' || by === 'day')
+        return by;
+    console.error(chalk.red('error: --by must be one of: account, agent, project, day'));
+    process.exit(1);
+}
+/**
+ * Sessions too short to say anything about how you work.
+ *
+ * Inspired by the filter `/insights` applies, but NOT identical and deliberately not
+ * claimed to be: `/insights` counts USER messages, while `messageCount` on the index
+ * counts both roles, so the same threshold is a weaker bar here. Matching it exactly
+ * would mean parsing every session just to decide whether to parse it. The dropped
+ * count is always reported, never silent.
+ */
+function isSubstantive(m, minMessages) {
+    if ((m.messageCount ?? 0) < minMessages)
+        return false;
+    if ((m.durationMs ?? 0) < 60_000)
+        return false;
+    return true;
+}
+function groupKeyFor(m, dim) {
+    switch (dim) {
+        case 'account': return m.accountKey ?? `unattributed:${m.agent}`;
+        case 'agent': return m.agent;
+        case 'project': return m.project || '(no project)';
+        case 'day': return m.timestamp.slice(0, 10);
+    }
+}
+function groupLabelFor(m, dim, key) {
+    if (dim !== 'account')
+        return key;
+    if (m.accountOrg && m.account)
+        return `${m.accountOrg} <${m.account}>`;
+    return key;
+}
+/**
+ * Load facets for every in-scope session, parsing only what the cache does not
+ * already hold. A cold first run parses every transcript once; after that only files
+ * whose (mtime, size) changed are re-read.
+ */
+async function collectFacets(rows, onProgress) {
+    let unreadable = 0;
+    const cached = readSessionInsights(rows.map((r) => r.id));
+    const stale = rows.filter((r) => !cached.has(r.id) && r.filePath);
+    if (stale.length === 0)
+        return { facets: cached, unreadable };
+    const fresh = [];
+    let done = 0;
+    for (const row of stale) {
+        try {
+            // Stat BEFORE reading, so the stamp we persist describes bytes no newer than the
+            // ones parsed: a rescan landing mid-read then reads as stale, not as a hit.
+            const st = fs.statSync(row.filePath);
+            // includeInterrupts: the default event array is a versioned contract, so the
+            // marker is opt-in and this is the reader that opts in.
+            const events = parseSession(row.filePath, row.agent, { includeInterrupts: true });
+            const facets = computeInsightFacets(events);
+            cached.set(row.id, facets);
+            fresh.push({ id: row.id, fileMtimeMs: Math.floor(st.mtimeMs), fileSize: st.size, facets });
+        }
+        catch {
+            // Deleted or corrupt since it was indexed. Counted and reported below, never
+            // silently contributing zero.
+            unreadable++;
+        }
+        done++;
+        if (done % 25 === 0)
+            onProgress(done, stale.length);
+        // Persist in batches so an interrupted cold run does not lose everything.
+        if (fresh.length >= 200) {
+            writeSessionInsights(fresh.splice(0, fresh.length));
+        }
+    }
+    if (fresh.length > 0)
+        writeSessionInsights(fresh);
+    onProgress(stale.length, stale.length);
+    return { facets: cached, unreadable };
+}
+function buildGroups(rows, facetsById, dim) {
+    const byKey = new Map();
+    for (const m of rows) {
+        const key = groupKeyFor(m, dim);
+        let g = byKey.get(key);
+        if (!g) {
+            g = {
+                key,
+                label: groupLabelFor(m, dim, key),
+                plan: null,
+                sessions: 0,
+                costUsd: 0,
+                durationMs: 0,
+                outputTokens: 0,
+                facets: newFacetAccumulator(),
+            };
+            byKey.set(key, g);
+        }
+        g.sessions++;
+        g.costUsd += m.costUsd ?? 0;
+        g.durationMs += m.durationMs ?? 0;
+        g.outputTokens += m.outputTokens ?? 0;
+        const f = facetsById.get(m.id);
+        if (f)
+            mergeFacets(g.facets, f);
+    }
+    return [...byKey.values()].sort((a, b) => b.sessions - a.sessions || a.key.localeCompare(b.key));
+}
+/** A compact bar for a count relative to the row maximum. */
+function bar(count, max, width) {
+    if (max <= 0)
+        return '';
+    const filled = Math.max(1, Math.round((count / max) * width));
+    return '█'.repeat(filled);
+}
+function renderCounts(title, entries, out) {
+    if (entries.length === 0)
+        return;
+    out.push('');
+    out.push(chalk.bold(title));
+    const nameW = Math.max(...entries.map((e) => stringWidth(e.name)));
+    const countW = Math.max(...entries.map((e) => String(e.count).length));
+    const max = Math.max(...entries.map((e) => e.count));
+    const barW = Math.max(6, Math.min(28, terminalWidth() - nameW - countW - 8));
+    for (const e of entries) {
+        out.push(`  ${padToWidth(e.name, nameW)}  ${chalk.cyan(String(e.count).padStart(countW))}  ` +
+            chalk.gray(bar(e.count, max, barW)));
+    }
+}
+function renderHours(hours, out) {
+    const total = hours.reduce((a, b) => a + b, 0);
+    if (total === 0)
+        return;
+    const blocks = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+    const max = Math.max(...hours);
+    const spark = hours
+        .map((h) => (h === 0 ? ' ' : blocks[Math.min(blocks.length - 1, Math.floor((h / max) * (blocks.length - 1)))]))
+        .join('');
+    out.push('');
+    out.push(chalk.bold('When you work') + chalk.gray('  (local time)'));
+    out.push(`  ${chalk.cyan(spark)}`);
+    out.push(`  ${chalk.gray('0h'.padEnd(6))}${chalk.gray('6h'.padEnd(6))}${chalk.gray('12h'.padEnd(6))}${chalk.gray('18h'.padEnd(5))}${chalk.gray('23h')}`);
+}
+function renderReport(groups, dim, meta) {
+    const out = [];
+    const scope = meta.since ? `last ${meta.since}` : 'all time';
+    out.push(chalk.bold('Insights') + chalk.gray(`  ${scope} · ${meta.analyzed} of ${meta.scanned} sessions`));
+    if (groups.length === 0) {
+        out.push('');
+        out.push(chalk.gray('  No sessions in scope. Try a wider --since, or run `agents sessions --all` to index.'));
+        console.log(out.join('\n'));
+        return;
+    }
+    // Per-group table — the headline, and the thing no sibling command produces.
+    out.push('');
+    out.push(chalk.bold(`By ${dim}`));
+    const labelW = Math.min(Math.max(...groups.map((g) => stringWidth(g.label)), 5), Math.max(20, terminalWidth() - 46));
+    const sessW = Math.max(...groups.map((g) => String(g.sessions).length), 3);
+    for (const g of groups) {
+        const cost = g.costUsd > 0 ? formatUsd(g.costUsd) : '—';
+        const dur = g.durationMs > 0 ? formatDuration(g.durationMs) : '—';
+        out.push(`  ${padToWidth(truncateToWidth(g.label, labelW), labelW)}  ` +
+            `${chalk.gray(String(g.sessions).padStart(sessW))} ${chalk.gray('sess')}  ` +
+            `${chalk.green(padToWidth(cost, 9))}  ${chalk.gray(dur)}`);
+    }
+    // Everything below is the whole scope folded together; per-group detail is in --json.
+    const all = newFacetAccumulator();
+    for (const g of groups)
+        mergeFacets(all, g.facets);
+    renderCounts('Top tools', topEntries(all.toolCounts, 8), out);
+    renderCounts('Languages', topEntries(all.languages, 6), out);
+    renderCounts('Models', topEntries(all.models, 6), out);
+    // Friction — the section that earns the command.
+    const gaps = all.responseGaps;
+    out.push('');
+    out.push(chalk.bold('Friction'));
+    out.push(`  ${padToWidth('interruptions', 18)}  ${chalk.cyan(String(all.interruptions))}` +
+        chalk.gray('   turns you cut short'));
+    out.push(`  ${padToWidth('tool errors', 18)}  ${chalk.cyan(String(all.errorCount))}`);
+    if (gaps.length > 0) {
+        out.push(`  ${padToWidth('your reply time', 18)}  ` +
+            chalk.cyan(`p50 ${Math.round(percentile(gaps, 50))}s`) + chalk.gray(` · p90 ${Math.round(percentile(gaps, 90))}s`));
+    }
+    const errs = topEntries(all.errorCategories, 6);
+    if (errs.length > 0) {
+        for (const e of errs)
+            out.push(`    ${chalk.gray('·')} ${padToWidth(e.name, 16)} ${chalk.gray(String(e.count))}`);
+    }
+    // Output
+    out.push('');
+    out.push(chalk.bold('What you changed'));
+    // Gate on whether anything was actually measured, not on whether an edit-shaped call
+    // was seen. Codex patches through `exec`, so it can log edit-class calls and still
+    // expose no line arguments to count — rendering that as "0 lines" would read as "wrote
+    // nothing" for a harness that wrote plenty.
+    if (all.linesTouchedAfter > 0 || all.linesTouchedBefore > 0) {
+        // "touched", not "+/-": these are the before/after line counts of each edit, so an
+        // Edit with unchanged context lines counts them on both sides. Not a diffstat, and
+        // labelled so nobody reads it as one.
+        out.push(`  ${chalk.cyan(String(all.linesTouchedAfter))} ${chalk.gray('lines written,')} ` +
+            `${chalk.cyan(String(all.linesTouchedBefore))} ${chalk.gray('replaced')}  ` +
+            chalk.gray('(lines touched, not a diff)'));
+    }
+    else {
+        out.push(`  ${chalk.gray('lines touched  —  not measurable for this harness (edits go through the shell)')}`);
+    }
+    out.push(`  ${chalk.gray(`${all.filesCreated} created, ${all.filesModified} modified, ${all.filesDeleted} deleted`)}`);
+    // Same not-measurable rule as the lines above. These are substring-matched from
+    // shell command TEXT, and not every harness exposes it — the codex parser populates
+    // `command` for `exec_command` but not plain `exec`, its dominant tool — so gate on
+    // whether we had anything to search rather than on seeing a shell-shaped tool call.
+    // When we did, the count is real, and still disagrees with `agents output`, which
+    // counts deduped SHAs from git log.
+    if (all.shellCommandsSeen > 0) {
+        out.push(`  ${chalk.gray(`${all.gitCommits} commits · ${all.gitPushes} pushes (seen in shell commands)`)}`);
+    }
+    else {
+        out.push(`  ${chalk.gray('commits  —  not measurable for this harness')}`);
+    }
+    renderHours(all.messageHours, out);
+    // Concurrency — direct evidence that a single-account view would be wrong.
+    if (meta.overlap.overlappingPairs > 0) {
+        out.push('');
+        out.push(chalk.bold('Parallel sessions'));
+        out.push(`  ${chalk.cyan(String(meta.overlap.sessionsInvolved))} ${chalk.gray('sessions ran alongside another')}`);
+        // Pairs, not sessions — stated as pairs so the two numbers are not read as a
+        // subset of each other.
+        const crossNote = meta.overlap.crossAccountPairs > 0
+            ? `, ${meta.overlap.crossAccountPairs} of them across two different accounts`
+            : '';
+        out.push(chalk.gray(`  ${meta.overlap.overlappingPairs} overlapping pairs${crossNote}`));
+    }
+    if (meta.filteredOut > 0) {
+        out.push('');
+        out.push(chalk.gray(`  ${meta.filteredOut} sessions excluded as too short (under ${meta.minMessages} messages or 1 minute).`));
+    }
+    if (meta.unreadable > 0) {
+        if (meta.filteredOut === 0)
+            out.push('');
+        out.push(chalk.yellow(`  ${meta.unreadable} transcripts could not be read; their behaviour is missing from these totals.`));
+    }
+    if (all.gapsOverCeiling > 0) {
+        out.push(chalk.gray(`  ${all.gapsOverCeiling} reply gaps over an hour excluded from the percentiles.`));
+    }
+    out.push('');
+    out.push(chalk.gray('  `agents insights --by project` to see it per repo'));
+    out.push(chalk.gray('  `agents insights --narrative` for a written read on what to change'));
+    console.log(out.join('\n'));
+}
+/**
+ * The opt-in coaching layer. Pipes the AGGREGATE through a headless `claude -p` — never
+ * raw transcripts, unlike `/insights`, which ships session text to the API. Reuses
+ * whatever account the shim resolves, so there is no API key handling here.
+ */
+async function renderNarrative(payload) {
+    const prompt = [
+        'You are reading a developer\'s own coding-session telemetry, already aggregated.',
+        'Write a short, direct read for them. Four sections, 2-3 sentences each:',
+        '1. What is working — the patterns worth keeping.',
+        '2. What is costing you — split into the assistant\'s fault vs your own workflow.',
+        '3. Quick wins — concrete, tied to a number in the data.',
+        '4. Worth trying — one more ambitious workflow change.',
+        'Be specific and cite the numbers. No preamble, no flattery, no bullet padding.',
+        '',
+        JSON.stringify(payload),
+    ].join('\n');
+    try {
+        const { stdout } = await execFileAsync('claude', ['-p', prompt], {
+            timeout: 180_000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        // stderr, always. Under --json stdout is a machine contract, and prose appended
+        // after the closing brace makes the payload unparseable; on a TTY stderr renders
+        // identically, so there is nothing to special-case.
+        process.stderr.write('\n' + chalk.bold('Narrative') + '\n');
+        process.stderr.write(stdout.trim().split('\n').map((l) => `  ${l}`).join('\n') + '\n');
+    }
+    catch (err) {
+        const msg = err.code === 'ENOENT'
+            ? 'claude is not on PATH'
+            : (err.message ?? 'unknown error');
+        console.error('');
+        console.error(chalk.red(`✗ narrative unavailable: ${msg}`));
+        console.error(chalk.gray('  The report above is complete; only the written section was skipped.'));
+        // A scripted caller asked for this section and did not get it. Say so in the exit
+        // code rather than reporting success for a partial result.
+        process.exitCode = 1;
+    }
+}
+async function insightsAction(options) {
+    const dim = resolveGroup(options.by);
+    const minMessages = Number.parseInt(options.minMessages ?? '2', 10);
+    if (!Number.isFinite(minMessages) || minMessages < 0) {
+        console.error(chalk.red('error: --min-messages must be a non-negative integer'));
+        process.exit(1);
+    }
+    const since = options.since ?? '30d';
+    const sinceMs = since === 'all' ? undefined : parseTimeFilter(since);
+    // Refresh the index first, exactly as `agents cost` does, so a report never silently
+    // describes a stale picture of disk.
+    await discoverSessions({ all: true, since: since === 'all' ? undefined : since, limit: 1 });
+    if (options.refresh)
+        clearSessionInsights();
+    const filter = { sinceMs };
+    if (options.agent)
+        filter.agent = options.agent;
+    const scanned = querySessions(filter);
+    const wanted = options.account?.toLowerCase();
+    const inScope = scanned.filter((m) => {
+        if (!wanted)
+            return true;
+        return [m.accountKey, m.account, m.accountOrg]
+            .some((v) => v?.toLowerCase().includes(wanted));
+    });
+    const substantive = inScope.filter((m) => isSubstantive(m, minMessages));
+    const filteredOut = inScope.length - substantive.length;
+    const isTty = process.stdout.isTTY && !options.json;
+    const { facets: facetsById, unreadable } = await collectFacets(substantive, (done, total) => {
+        if (isTty && done < total)
+            process.stderr.write(`\rReading transcripts ${done}/${total}…`);
+        else if (isTty)
+            process.stderr.write('\r'.padEnd(40) + '\r');
+    });
+    const spans = substantive.map((m) => {
+        const start = new Date(m.timestamp).getTime();
+        return {
+            id: m.id,
+            accountKey: m.accountKey ?? `unattributed:${m.agent}`,
+            startMs: start,
+            endMs: start + (m.durationMs ?? 0),
+        };
+    });
+    const overlap = detectOverlap(spans);
+    const groups = buildGroups(substantive, facetsById, dim);
+    if (options.json) {
+        const payload = {
+            generatedAt: new Date().toISOString(),
+            window: { since: since === 'all' ? null : since },
+            scanned: inScope.length,
+            analyzed: substantive.length,
+            filteredOut,
+            unreadable,
+            minMessages,
+            by: dim,
+            overlap,
+            groups: groups.map((g) => ({
+                key: g.key,
+                label: g.label,
+                sessions: g.sessions,
+                costUsd: g.costUsd,
+                durationMs: g.durationMs,
+                outputTokens: g.outputTokens,
+                ...g.facets,
+                responseGapP50: Math.round(percentile(g.facets.responseGaps, 50)),
+                responseGapP90: Math.round(percentile(g.facets.responseGaps, 90)),
+                responseGapBuckets: bucketGaps(g.facets.responseGaps),
+                // The raw sample is large and uninteresting once bucketed.
+                responseGaps: undefined,
+            })),
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        if (options.narrative)
+            await renderNarrative(payload);
+        return;
+    }
+    renderReport(groups, dim, {
+        since: since === 'all' ? undefined : since,
+        scanned: inScope.length,
+        analyzed: substantive.length,
+        filteredOut,
+        unreadable,
+        minMessages,
+        overlap,
+    });
+    if (options.narrative) {
+        await renderNarrative(groups.map((g) => ({
+            account: g.label, sessions: g.sessions, costUsd: g.costUsd,
+            topTools: topEntries(g.facets.toolCounts, 8),
+            languages: topEntries(g.facets.languages, 6),
+            errorCategories: topEntries(g.facets.errorCategories, 6),
+            interruptions: g.facets.interruptions,
+            linesTouchedAfter: g.facets.linesTouchedAfter, linesTouchedBefore: g.facets.linesTouchedBefore,
+            gitCommits: g.facets.gitCommits,
+            replyP50s: Math.round(percentile(g.facets.responseGaps, 50)),
+        })));
+    }
+}
+export function registerInsightsCommand(program) {
+    const cmd = addHostOption(program.command('insights'))
+        .description('How you work — tools, friction, and rhythm, split by the account that did the work')
+        .option('--json', 'Output the full report as JSON')
+        .option('--since <time>', 'Window: 7d, 4w, 3mo, an ISO date, or "all" (default 30d)')
+        .option('--by <dimension>', 'Group by: account (default), agent, project, or day')
+        .option('--account <match>', 'Only sessions whose account key, email, or org contains this')
+        .option('--agent <id>', 'Only one harness (claude, codex, droid, …)')
+        .option('--min-messages <n>', 'Skip sessions under this many messages, both roles counted (default 2)')
+        .option('--refresh', 'Discard cached facets and re-read every transcript')
+        .option('--narrative', 'Add a written read on the numbers via a headless `claude -p`')
+        .action(async (options) => {
+        await insightsAction(options);
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # Last 30 days, split by Claude account — the default
+      agents insights
+
+      # Which repo is eating the time
+      agents insights --by project --since 90d
+
+      # One account only, all of its history
+      agents insights --account "Turing Labs" --since all
+
+      # Machine-readable, for a dashboard or a slash command
+      agents insights --json
+
+      # Add a written read on what to change
+      agents insights --narrative
+    `,
+        notes: `
+      Answers "how do you work". For "what did it cost" use \`agents cost\`, for "what
+      shipped" use \`agents output\`, for live quota use \`agents usage\`.
+
+      The first run parses every in-scope transcript and caches the result; later runs
+      re-read only files that changed. \`--refresh\` forces a full re-read.
+
+      Account attribution is Claude-only today. Sessions from other harnesses group
+      under \`unattributed:<agent>\`.
+
+      Everything except \`--narrative\` is local and makes no network calls.
+    `,
+    });
+}

package/dist/commands/sessions-picker.d.ts

@@ -28,6 +28,8 @@ export interface SessionPickerConfig {
     initialSearch?: string;
     /** Verb shown on the Enter key in the footer (default 'resume'). */
     enterHint?: string;
+    /** Lines the caller printed above the prompt (hidden-session footer). */
+    linesAbovePrompt?: number;
 }
 /** Build a cached multi-line preview string for display in the session picker. */
 export declare function buildPreview(session: SessionMeta): string;

package/dist/commands/sessions-picker.js

@@ -801,6 +801,7 @@ export async function sessionPicker(config) {
         initialSearch: config.initialSearch,
         emptyMessage: 'No sessions match.',
         enterHint: config.enterHint ?? 'resume',
+        linesAbovePrompt: config.linesAbovePrompt,
     });
     if (!picked)
         return null;

package/dist/commands/sessions.js

@@ -2726,8 +2726,13 @@ export function formatPickerTip(sessions) {
     return chalk.gray(PICKER_TIPS[sessions.length % PICKER_TIPS.length]);
 }
 export async function pickSessionInteractive(sessions, message = 'Search sessions:', initialSearch, hiddenCount = 0, enterHint) {
+    // The hidden-session footer is console.log'd above the Inquirer prompt, so it
+    // scrolls the viewport the picker can't measure; tell the picker to reserve for
+    // it (see pickerPageSize) so the preview and the footer stay on screen together.
+    let linesAbovePrompt = 0;
     if (hiddenCount > 0) {
         console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
+        linesAbovePrompt += 1;
     }
     const cols = pickerColumnsFor(sessions);
     try {
@@ -2746,6 +2751,7 @@ export async function pickSessionInteractive(sessions, message = 'Search session
             pageSize: PICKER_RECENT_COUNT,
             initialSearch,
             enterHint,
+            linesAbovePrompt,
         });
     }
     catch (err) {

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -327,6 +327,7 @@ Credentials and profiles:
 Diagnostics:
   doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence; --check for the CI drift gate
   usage [agent]                   Show rate-limit and quota usage per agent
+  insights                        How you work — tools, friction, rhythm, split by Claude account
   perf                            Latency rollups (hooks, commands, runs) from the disposable perf warehouse
 
 Config sync:
@@ -963,6 +964,7 @@ async function registerAllEagerCommands() {
     await reg(loadFactory);
     await reg(loadUsage);
     await reg(loadCost);
+    await reg(loadInsights);
     await reg(loadPerf);
     await reg(loadTrends);
     await reg(loadOutput);

package/dist/lib/hosts/passthrough.js

@@ -46,6 +46,7 @@ const REMOTE_PASSTHROUGH = {
     list: {},
     usage: {},
     cost: {},
+    insights: {},
     output: {},
     budget: {},
     // config / resources