rvlib-shipkit 2.2.0 → 2.4.0

package/src/agent-time/report.ts

@@ -0,0 +1,335 @@
+// `sk time` from the index rows: where the wall went, which commands ate the
+// time, what failed and ran again, and what he said while it ran.
+//
+// The constraint a reader breaks first: one session can sit in two or three
+// config roots (a session imported into another account to resume it there).
+// Streams are merged by session and agent, and calls deduped by their tool
+// use id, or every imported session counts twice.
+import { type PromptEntry, dedupePrompts } from '../reflect/prompt-corpus.ts'
+import type { Outcome } from '../reflect/transcript.ts'
+import type { Masker } from './mask.ts'
+import { type Signal, signalsOf } from './signals.ts'
+import type { FileRow, Loaded } from './store.ts'
+import { type ReadCost, type TurnStats, addTurns, emptyTurns, turnsOf } from './turns.ts'
+import { type Breakdown, type Call, type Mark, type Stream, FAILED, IDLE_MS, addBreakdown, callMs, type Closed, closeCalls, emptyBreakdown, quantileSorted, ranBefore, retries, wallBreakdown } from './timeline.ts'
+
+export type ShapeRow = { shape: string; tool: string; calls: number; ms: number; approvals: number; approvalMs: number; p50: number; p95: number; max: number; failed: number; timeouts: number; blocked: number; retried: number; blind: number; failedMs: number }
+
+export type SlowCall = { ms: number; shape: string; cmd: string; at: number; account: string; session: string; agent: boolean; outcome: Outcome | null; open: boolean }
+
+export type Complaint = { at: number; session: string; account: string; text: string; signals: { signal: Signal; rule: string }[]; ran: { shape: string; cmd: string; ms: number; open: boolean }[] }
+
+/** one session or one sub-agent run, by its turns */
+export type TurnRow = { session: string; agent: string; account: string; start: number; work: number; wall: number; turns: TurnStats }
+
+/** turn count: the main sessions and the sub-agents apart, the runs with the
+ *  most wall, and the read shapes by the model time of the turns that issued them */
+export type TurnReport = {
+    main: TurnStats
+    sub: TurnStats & { runs: number; work: Breakdown; runP50: number; runP90: number; callsP50: number }
+    rows: TurnRow[]
+    reads: ReadCost[]
+}
+
+export type SessionRow = { session: string; account: string; repo: string; start: number; wall: Breakdown; calls: number; subagents: number; first: string }
+
+export type TimeReport = {
+    repos: string[]
+    from: number | null
+    to: number
+    accounts: string[]
+    sessions: number
+    subagentRuns: number
+    /** history whose transcript Claude Code already pruned, still in the index */
+    prunedSessions: number
+    wall: Breakdown
+    subagentWork: number
+    callCount: number
+    callMs: number
+    shapes: ShapeRow[]
+    tools: ShapeRow[]
+    slowest: SlowCall[]
+    feedback: { prompts: number; queued: number; counts: Record<Signal, number>; rules: Record<string, number>; hits: Complaint[] }
+    sessionRows: SessionRow[]
+    turns: TurnReport
+    /** the measured waste, biggest first: each with the number behind it */
+    insights: Insight[]
+}
+
+export type Insight = { id: 'classifier' | 'bash-edits' | 'polling' | 'failed' | 'approval'; ms: number; estimate: boolean; text: string }
+
+/** commands that cost nothing to run: their time is the harness around them */
+const CHEAP = new Set(['grep', 'sed', 'cat', 'ls', 'head', 'tail', 'wc', 'git status', 'echo', 'pwd', 'rg'])
+
+const isEdit = (shape: string): boolean => shape.endsWith('(edit)') || shape === 'cat > (write)'
+const isPolling = (shape: string): boolean => shape.startsWith('(until)') || shape.startsWith('(while)') || shape === 'sleep'
+
+const fmt = (ms: number): string => (ms < 1000 ? `${(ms / 1000).toFixed(1)}s` : ms < 60_000 ? `${Math.round(ms / 1000)}s` : ms < 3_600_000 ? `${Math.round(ms / 60_000)}m` : `${(ms / 3_600_000).toFixed(1)}h`)
+
+const p50Of = (xs: number[]): number => quantileSorted(xs.sort((a, b) => a - b), 0.5)
+
+/** the waste the rows add up to, each a cause with its number */
+export function insightsOf(calls: Closed[], wall: Breakdown, shapes: ShapeRow[]): Insight[] {
+    const out: Insight[] = []
+    const bash = calls.filter((c) => c.tool === 'Bash')
+    const cheap = bash.filter((c) => CHEAP.has(c.shape))
+    const viaClassifier = cheap.filter((c) => c.perm === 'classifier').map(callMs)
+    const viaRule = cheap.filter((c) => c.perm === 'rule').map(callMs)
+    const classified = bash.filter((c) => c.perm === 'classifier').length
+    if (viaClassifier.length >= 20 && viaRule.length >= 20) {
+        const c = p50Of(viaClassifier)
+        const r = p50Of(viaRule)
+        if (c > r) out.push({ id: 'classifier', ms: (c - r) * classified, estimate: true, text: `the auto mode classifier checked ${classified.toLocaleString('en-US')} Bash calls before they ran: a cheap command (grep, sed, cat, ls) takes p50 ${fmt(c)} through it, ${fmt(r)} when a rule allows it. fix: allow rules for the read only commands agents repeat` })
+    }
+    const edits = bash.filter((c) => isEdit(c.shape))
+    const editTool = calls.filter((c) => c.tool === 'Edit').map(callMs)
+    if (edits.length > 0) {
+        const ms = edits.map(callMs)
+        const bashP50 = p50Of(ms)
+        const toolP50 = editTool.length >= 20 ? p50Of(editTool) : null
+        const saved = toolP50 == null || toolP50 >= bashP50 ? '' : `, about ${fmt((bashP50 - toolP50) * edits.length)} back at the Edit tool's p50 ${fmt(toolP50)}`
+        out.push({ id: 'bash-edits', ms: ms.reduce((a, b) => a + b, 0), estimate: false, text: `${edits.length.toLocaleString('en-US')} file edits through Bash (python3 heredocs, sed -i, perl -i, cat >), p50 ${fmt(bashP50)}${saved}` })
+    }
+    const polls = bash.filter((c) => isPolling(c.shape))
+    if (polls.length > 0) {
+        const timeouts = polls.filter((c) => c.outcome === 'timeout').length
+        const top = shapes.filter((s) => isPolling(s.shape)).slice(0, 3).map((s) => `${s.shape} ${fmt(s.ms)}`).join(', ')
+        out.push({ id: 'polling', ms: polls.map(callMs).reduce((a, b) => a + b, 0), estimate: false, text: `${polls.length.toLocaleString('en-US')} polling waits (until and while loops, sleep), ${timeouts} hit the Bash timeout: ${top}` })
+    }
+    const failed = bash.filter((c) => c.outcome != null && FAILED.has(c.outcome))
+    if (failed.length > 0) {
+        const rerun = shapes.reduce((a, s) => a + s.retried, 0)
+        const blind = shapes.reduce((a, s) => a + s.blind, 0)
+        out.push({ id: 'failed', ms: failed.map(callMs).reduce((a, b) => a + b, 0), estimate: false, text: `${failed.length.toLocaleString('en-US')} failed Bash runs (non zero exit, error, timeout), ${rerun} run again, ${blind} of them unchanged` })
+    }
+    if (wall.approval > 0) {
+        const n = calls.filter((c) => c.approval).length
+        const top = [...shapes].filter((s) => s.approvals > 0).sort((a, b) => b.approvalMs - a.approvalMs).slice(0, 3).map((s) => `${s.shape} ${fmt(s.approvalMs)}`).join(', ')
+        out.push({ id: 'approval', ms: wall.approval, estimate: false, text: `waiting for you to allow ${n} call${n === 1 ? '' : 's'}: ${top}` })
+    }
+    return out.sort((a, b) => b.ms - a.ms)
+}
+
+type Group = { key: string; session: string; agent: string; files: FileRow[]; stream: Stream; closed: Closed[] }
+
+/** one stream per session and agent, every copy of it merged */
+export function mergeStreams(loaded: Loaded): Group[] {
+    const groups = new Map<string, Group>()
+    for (const f of loaded.files) {
+        const key = `${f.session}/${f.agent}`
+        const g = groups.get(key) ?? { key, session: f.session, agent: f.agent, files: [], stream: { calls: [], marks: [] }, closed: [] }
+        g.files.push(f)
+        groups.set(key, g)
+    }
+    for (const g of groups.values()) {
+        const calls = new Map<string, Call>()
+        const marks = new Map<string, Mark>()
+        for (const f of g.files) {
+            for (const c of loaded.calls.get(f.id) ?? []) {
+                const have = calls.get(c.id)
+                if (have == null || (have.end == null && c.end != null)) calls.set(c.id, c)
+            }
+            for (const m of loaded.marks.get(f.id) ?? []) marks.set(`${m.at}/${m.kind}`, m)
+        }
+        g.stream = { calls: [...calls.values()], marks: [...marks.values()] }
+        g.closed = closeCalls(g.stream)
+    }
+    return [...groups.values()]
+}
+
+function pushTo<K, V>(m: Map<K, V[]>, k: K, v: V): void {
+    const list = m.get(k)
+    if (list == null) m.set(k, [v])
+    else list.push(v)
+}
+
+/** the k items of largest `key`, largest first, without sorting the list */
+function topBy<T>(xs: T[], k: number, key: (x: T) => number): T[] {
+    const top: { x: T; v: number }[] = []
+    for (const x of xs) {
+        const v = key(x)
+        if (top.length === k && v <= (top[k - 1] as { v: number }).v) continue
+        let i = top.length
+        while (i > 0 && (top[i - 1] as { v: number }).v < v) i--
+        top.splice(i, 0, { x, v })
+        if (top.length > k) top.pop()
+    }
+    return top.map((t) => t.x)
+}
+
+const isFailed = (o: Outcome | null): boolean => o != null && FAILED.has(o)
+
+function rowsBy(calls: { c: Closed; key: string }[], retriesByKey: Map<string, { retried: number; blind: number }>): ShapeRow[] {
+    const by = new Map<string, Closed[]>()
+    for (const { c, key } of calls) {
+        const list = by.get(key)
+        if (list == null) by.set(key, [c])
+        else list.push(c)
+    }
+    return [...by].map(([key, cs]): ShapeRow => {
+        const ms = new Float64Array(cs.length)
+        const row: ShapeRow = { shape: key, tool: cs[0]?.tool ?? '', calls: cs.length, ms: 0, approvals: 0, approvalMs: 0, p50: 0, p95: 0, max: 0, failed: 0, timeouts: 0, blocked: 0, retried: 0, blind: 0, failedMs: 0 }
+        cs.forEach((c, i) => {
+            const d = callMs(c)
+            ms[i] = d
+            row.ms += d
+            if (c.approval) {
+                row.approvals++
+                row.approvalMs += d
+            }
+            if (isFailed(c.outcome)) {
+                row.failed++
+                row.failedMs += d
+            }
+            if (c.outcome === 'timeout') row.timeouts++
+            if (c.outcome === 'blocked' || c.outcome === 'denied') row.blocked++
+        })
+        ms.sort()
+        const sorted = Array.from(ms)
+        const r = retriesByKey.get(key)
+        return { ...row, p50: quantileSorted(sorted, 0.5), p95: quantileSorted(sorted, 0.95), max: sorted[sorted.length - 1] ?? 0, retried: r?.retried ?? 0, blind: r?.blind ?? 0 }
+    }).sort((a, b) => b.ms - a.ms || b.calls - a.calls)
+}
+
+export function buildReport(loaded: Loaded, q: { repos: string[]; from: number | null; to: number; repoOf: (project: string) => string }, mask: Masker): TimeReport {
+    const from = q.from ?? -Infinity
+    const groups = mergeStreams(loaded)
+    const accounts = new Set<string>()
+    const wall = emptyBreakdown()
+    let subagentWork = 0
+    const all: { c: Closed; g: Group }[] = []
+    const retryShape = new Map<string, { retried: number; blind: number }>()
+    const sessionRows: SessionRow[] = []
+    const subsBySession = new Map<string, number>()
+    for (const g of groups) if (g.agent !== '') subsBySession.set(g.session, (subsBySession.get(g.session) ?? 0) + 1)
+    const promptsByFile = new Map<number, Loaded['prompts']>()
+    for (const p of loaded.prompts) pushTo(promptsByFile, p.file_id, p)
+    const mainTurns = emptyTurns()
+    const subTurns = emptyTurns()
+    const subWork = emptyBreakdown()
+    const runMs: number[] = []
+    const runCalls: number[] = []
+    const turnRows: TurnRow[] = []
+    const readCosts = new Map<string, ReadCost>()
+
+    for (const g of groups) {
+        for (const f of g.files) accounts.add(f.account)
+        const turnModel = new Float64Array(g.closed.length)
+        const b = wallBreakdown(g.stream, from, q.to, IDLE_MS, g.closed, turnModel)
+        const t = turnsOf(g.closed, b.model, turnModel, readCosts)
+        const work = b.model + b.tools + b.approval + b.subagent + b.background
+        if (t.calls > 0) turnRows.push({ session: g.session, agent: g.agent, account: g.files[0]?.account ?? '', start: g.closed[0]?.start ?? 0, work: b.model + b.tools + b.approval, wall: work, turns: t })
+        if (g.agent === '') addTurns(mainTurns, t)
+        else {
+            addTurns(subTurns, t)
+            addBreakdown(subWork, b)
+            runMs.push(work)
+            runCalls.push(t.calls)
+        }
+        if (g.agent === '') {
+            addBreakdown(wall, b)
+            const firstPrompt = g.files.flatMap((f) => promptsByFile.get(f.id) ?? []).sort((a, b2) => a.at - b2.at)[0]
+            sessionRows.push({
+                session: g.session,
+                account: g.files[0]?.account ?? '',
+                repo: q.repoOf(g.files[0]?.project ?? ''),
+                start: [...g.stream.marks.map((m) => m.at), ...g.stream.calls.map((c) => c.start)].reduce((a, b) => (b < a ? b : a), Infinity),
+                wall: b,
+                calls: g.stream.calls.length,
+                subagents: subsBySession.get(g.session) ?? 0,
+                first: firstPrompt == null ? '' : mask(firstPrompt.text.replace(/\s+/g, ' ').slice(0, 70)),
+            })
+        } else subagentWork += work
+        for (const c of g.closed) all.push({ c, g })
+        for (const r of retries(g.closed)) {
+            const x = retryShape.get(r.failed.shape) ?? { retried: 0, blind: 0 }
+            x.retried++
+            if (r.blind) x.blind++
+            retryShape.set(r.failed.shape, x)
+        }
+    }
+
+    const bash = all.filter(({ c }) => c.tool === 'Bash')
+    const shapes = rowsBy(all.filter(({ c }) => c.tool !== 'Agent' && c.tool !== 'Task').map(({ c }) => ({ c, key: c.shape })), retryShape)
+    // the Bash shapes first: they are the commands; other tools stay in the table
+    shapes.sort((a, b) => b.ms - a.ms)
+    const tools = rowsBy(all.map(({ c }) => ({ c, key: c.tool })), new Map())
+    const slowest: SlowCall[] = topBy(bash, 40, ({ c }) => callMs(c))
+        .map(({ c, g }) => ({ ms: callMs(c), shape: c.shape, cmd: mask(c.cmd.replace(/\s+/g, ' ').slice(0, 120)), at: c.start, account: g.files[0]?.account ?? '', session: g.session, agent: g.agent !== '', outcome: c.outcome, open: c.open }))
+
+    // feedback: his prompts, deduped across copies, signals by rule, and for a
+    // slowness complaint what every stream of that session was running
+    const fileById = new Map(loaded.files.map((f) => [f.id, f]))
+    const groupsBySession = new Map<string, Group[]>()
+    for (const g of groups) pushTo(groupsBySession, g.session, g)
+    const counts: Record<Signal, number> = { status: 0, slow: 0, correction: 0 }
+    const rules: Record<string, number> = {}
+    const hits: Complaint[] = []
+    const typed: (PromptEntry & { file: FileRow })[] = []
+    for (const p of loaded.prompts) {
+        const f = fileById.get(p.file_id)
+        if (f == null || f.agent !== '') continue
+        typed.push({ uuid: `${p.at}/${p.origin}/${p.text}`, timestamp: new Date(p.at).toISOString(), sessionId: f.session, account: f.account, text: p.text, origin: p.origin, file: f })
+    }
+    typed.sort((a, b) => a.timestamp.localeCompare(b.timestamp))
+    const kept = dedupePrompts(typed) as (PromptEntry & { file: FileRow })[]
+    const repoGroups = (session: string): Group[] => groupsBySession.get(session) ?? []
+    let sortedAll: Closed[] | null = null
+    const allSorted = (): Closed[] => (sortedAll ??= all.map(({ c }) => c).sort((a, b) => a.start - b.start))
+    for (const p of kept) {
+        const signals = signalsOf(p.text)
+        if (signals.length === 0) continue
+        for (const s of signals) {
+            counts[s.signal]++
+            rules[s.rule] = (rules[s.rule] ?? 0) + 1
+        }
+        const at = Date.parse(p.timestamp)
+        const notAgent = (c: Closed) => c.tool !== 'Agent' && c.tool !== 'Task'
+        // his session first; a fresh session had nothing running, so then every
+        // session of the repo in those minutes
+        let ran = repoGroups(p.file.session).flatMap((g) => ranBefore(g.closed, at)).filter(notAgent)
+        if (ran.length === 0) ran = ranBefore(allSorted(), at).filter(notAgent)
+        hits.push({
+            at,
+            session: p.file.session,
+            account: p.account,
+            text: mask(p.text.replace(/\s+/g, ' ').slice(0, 160)),
+            signals,
+            ran: ran.sort((a, b) => callMs(b) - callMs(a)).slice(0, 3).map((c) => ({ shape: c.shape, cmd: mask(c.cmd.replace(/\s+/g, ' ').slice(0, 80)), ms: callMs(c), open: c.open })),
+        })
+    }
+    const prompts = kept.length
+    const queued = kept.filter((p) => p.origin === 'queued').length
+
+    const mains = groups.filter((g) => g.agent === '')
+    return {
+        repos: q.repos,
+        from: q.from,
+        to: q.to,
+        accounts: [...accounts].sort(),
+        sessions: mains.length,
+        subagentRuns: groups.length - mains.length,
+        prunedSessions: mains.filter((g) => g.files.every((f) => f.gone === 1)).length,
+        wall,
+        subagentWork,
+        callCount: all.length,
+        callMs: all.reduce((a, { c }) => a + callMs(c), 0),
+        shapes,
+        tools,
+        slowest,
+        feedback: { prompts, queued, counts, rules, hits },
+        sessionRows: sessionRows.sort((a, b) => total(b.wall, false) - total(a.wall, false)),
+        turns: {
+            main: mainTurns,
+            sub: { ...subTurns, runs: runMs.length, work: subWork, runP50: quantileSorted(runMs.sort((a, b) => a - b), 0.5), runP90: quantileSorted(runMs, 0.9), callsP50: quantileSorted(runCalls.sort((a, b) => a - b), 0.5) },
+            rows: topBy(turnRows, 200, (r) => r.work),
+            reads: [...readCosts.values()].sort((a, b) => b.model - a.model),
+        },
+        insights: insightsOf(all.map(({ c }) => c), wall, shapes),
+    }
+}
+
+/** the wall of a breakdown; idle left out unless asked */
+export const total = (b: Breakdown, idle: boolean): number => b.model + b.tools + b.approval + b.subagent + b.background + b.human + (idle ? b.idle : 0)
+
+export { IDLE_MS }

package/src/agent-time/shape.ts

@@ -0,0 +1,271 @@
+// A tool call's SHAPE: the name its time is grouped under. A Bash command
+// becomes its program and subcommand (`git commit`, `bun test <file>`,
+// `sk ci --only lint`), so five hundred variants group into a few dozen rows.
+//
+// The constraint a reader breaks first: a shape never keeps a free value (a
+// path, a message, a hash), or every call becomes its own row again. The only
+// value kept is `sk ci --only <check>`, a small closed set that says WHICH
+// check is slow.
+
+/** bumped with any rule below: the index shapes every stored call again */
+export const SHAPE_VERSION = 4
+
+/** programs whose first word is never a subcommand */
+const NO_SUBCOMMAND = new Set([
+    'awk', 'cat', 'chmod', 'cp', 'curl', 'date', 'diff', 'du', 'echo', 'ffmpeg', 'ffprobe', 'file', 'find', 'grep', 'head',
+    'jq', 'kill', 'killall', 'less', 'ln', 'ls', 'lsof', 'mkdir', 'mv', 'open', 'pgrep', 'pkill', 'printf', 'ps', 'pwd', 'rg',
+    'rm', 'rmdir', 'sed', 'sleep', 'sort', 'sqlite3', 'stat', 'tail', 'tee', 'test', 'touch', 'tr', 'tree', 'uniq', 'uptime',
+    'wc', 'wget', 'which', 'xargs', 'perl', 'magick', 'convert', 'zip', 'unzip', 'tar', 'osascript', 'say', 'afplay', 'screencapture', 'sips', 'top',
+])
+
+/** programs whose shape keeps two subcommand words (`gh pr view`, `sk gp start`) */
+const TWO_LEVELS = new Set(['sk', 'shipkit', 'gh', 'docker', 'kubectl', 'gcloud', 'wrangler', 'chi', 'comfy-ts', 'cflow', 'brew'])
+
+/** bun's own subcommands; any other first word is a package script */
+const BUN_BUILTINS = new Set(['test', 'run', 'x', 'install', 'i', 'add', 'remove', 'rm', 'build', 'pm', 'link', 'unlink', 'init', 'create', 'upgrade', 'lint', 'fmt', 'outdated', 'update', 'publish', 'patch', 'why', 'audit', 'exec', 'repl', 'info'])
+
+/** a segment that only sets the scene for the next one */
+const SETUP = new Set(['cd', 'export', 'set', 'source', '.', 'pushd', 'popd', 'unset', 'ulimit', 'shopt', 'true', ':'])
+
+/** words that run the rest of the line as the real command */
+const WRAPPERS: Record<string, number> = { nice: 0, time: 0, timeout: 1, command: 0, exec: 0, env: 0, sudo: 0, caffeinate: 0, stdbuf: 0, nohup: 0 }
+
+/** flags that eat the next word, per program, before its subcommand */
+const ARG_FLAGS: Record<string, Set<string>> = { git: new Set(['-C', '-c']), nice: new Set(['-n']), bun: new Set(['--cwd', '--filter']) }
+
+/** shell words, quotes removed; enough of a shell to split a command line */
+export function shellWords(segment: string): string[] {
+    const words: string[] = []
+    let cur = ''
+    let quote: string | null = null
+    let any = false
+    for (let i = 0; i < segment.length; i++) {
+        const c = segment[i] as string
+        if (quote != null) {
+            if (c === quote) quote = null
+            else if (c === '\\' && quote === '"' && i + 1 < segment.length) cur += segment[++i]
+            else cur += c
+        } else if (c === '"' || c === "'") {
+            quote = c
+            any = true
+        } else if (c === '\\' && i + 1 < segment.length) cur += segment[++i]
+        else if (/\s/.test(c)) {
+            if (cur !== '' || any) words.push(cur)
+            cur = ''
+            any = false
+        } else cur += c
+    }
+    if (cur !== '' || any) words.push(cur)
+    return words
+}
+
+/** a heredoc's body is data, never a command: `cat > f <<'EOF'` keeps its
+ *  first line, the lines up to the marker go */
+export function stripHeredocs(command: string): string {
+    const out: string[] = []
+    let marker: string | null = null
+    for (const line of command.split('\n')) {
+        if (marker != null) {
+            if (line.trim() === marker) marker = null
+            continue
+        }
+        out.push(line)
+        const m = /<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/.exec(line)
+        if (m?.[1] != null) marker = m[1]
+    }
+    return out.join('\n')
+}
+
+/** the statements of a command line (split on `&&`, `||`, `;` and newlines
+ *  outside quotes), each one only its first pipeline part: in `grep x | head`
+ *  the time is the producer's */
+export function statements(command: string): string[] {
+    const out: string[] = []
+    let cur = ''
+    let piped = false
+    let quote: string | null = null
+    const text = stripHeredocs(command).replace(/\\\n/g, ' ')
+    const flush = (): void => {
+        out.push(cur)
+        cur = ''
+        piped = false
+    }
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i] as string
+        if (quote != null) {
+            if (c === quote) quote = null
+            if (!piped) cur += c
+            continue
+        }
+        if (c === '"' || c === "'") {
+            quote = c
+            if (!piped) cur += c
+            continue
+        }
+        const two = text.slice(i, i + 2)
+        if (two === '&&' || two === '||') {
+            flush()
+            i++
+        } else if (c === ';' || c === '\n') flush()
+        else if (c === '|') piped = true
+        else if (!piped) cur += c
+    }
+    flush()
+    return out.map((x) => x.trim()).filter((x) => x !== '')
+}
+
+const isWord = (w: string): boolean => /^[a-z][a-z0-9:_-]*$/i.test(w) && !/\.[a-z0-9]+$/i.test(w)
+const isPathLike = (w: string): boolean => w.includes('/') || /\.[a-z0-9]{1,5}$/i.test(w) || w.startsWith('~')
+const isScript = (w: string): boolean => /\.(?:sh|bash|zsh|ts|tsx|js|mjs|cjs|py|rb|pl)$/i.test(w) || (w.includes('/') && !w.startsWith('-'))
+const base = (w: string): string => w.replace(/\/+$/, '').split('/').pop() ?? w
+
+/** a statement's words: redirections, a leading `X=$(` and env assignments gone */
+function wordsOf(statement: string): string[] {
+    // `cat > f`, `cat a > b`: a file write, whatever it writes
+    if (/^cat\b[^|]*?(?<![0-9&>])>{1,2}(?!&)/.test(statement)) return ['cat', '>']
+    const w = shellWords(statement.replace(/^[A-Za-z_][A-Za-z0-9_]*=\$\(/, '').replace(/^\(+|\)+$/g, '').replace(/\s\d?>>?&?\d?\s*\S*/g, ' ').replace(/\s<\S+/g, ' '))
+    while (w.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(w[0] as string)) w.shift()
+    return w
+}
+
+/** statements that cost nothing next to the one they come with: a shape skips
+ *  them when a heavier statement follows (`uptime; sk ci`, `mkdir -p x && bun y.ts`) */
+const LIGHT = new Set(['echo', 'printf', 'uptime', 'date', 'pwd', 'mkdir', 'touch', 'which', 'clear', 'rm', 'cat'])
+
+const isLight = (w: string[]): boolean => LIGHT.has(w[0] as string) && (w[0] !== 'cat' || w.length === 1 || w[1] === '>' || w.every((x, i) => i === 0 || x.startsWith('-')))
+
+/** a python heredoc that opens a file to write it: an edit through Bash */
+const PY_EDIT = /\bpython3?\s+-\s*<</
+const PY_WRITES = /open\([^)]*,\s*['"][wa]|\.write(?:_text)?\(/
+
+/** the shape of one Bash command line */
+export function commandShape(command: string): string {
+    const stmts = statements(command.trim()).map(wordsOf).filter((w) => w.length > 0)
+    if (stmts.length === 0) return '(empty)'
+    const shape = pick(stmts) ?? (base(stmts[0]?.[0] ?? '') || '(empty)')
+    if (shape.startsWith('python') && !shape.includes(' ') && PY_EDIT.test(command) && PY_WRITES.test(command)) return `${shape} (edit)`
+    return shape
+}
+
+/** the statement the time belongs to, shaped: loops by what they run */
+function pick(stmts: string[][]): string | null {
+    let light: string[] | null = null
+    for (let i = 0; i < stmts.length; i++) {
+        const w = stmts[i] as string[]
+        const head = w[0] as string
+        if (head === 'for' || head === 'while' || head === 'until' || head === 'select') return loopShape(head, w, stmts.slice(i + 1))
+        if (head === 'if') return '(if)'
+        if (/^[A-Za-z_][A-Za-z0-9_-]*\(\)/.test(head) || head === 'function') return '(function)'
+        if (SETUP.has(head) || head === 'do' || head === 'done' || head === 'then' || head === 'fi') continue
+        if (isLight(w)) {
+            light ??= w
+            continue
+        }
+        return shapeOfWords(w)
+    }
+    return light == null ? null : shapeOfWords(light)
+}
+
+/** `(for) bun <file>`: a for loop by its body, a while or until loop by its
+ *  condition (a `[ … ]` test says nothing, so by its body then) */
+function loopShape(head: string, w: string[], after: string[][]): string {
+    const label = head === 'select' ? 'for' : head
+    const doAt = after.findIndex((x) => x[0] === 'do')
+    const body = doAt === -1 ? [] : [after[doAt]?.slice(1) ?? [], ...after.slice(doAt + 1)].filter((x) => x.length > 0)
+    const end = body.findIndex((x) => x[0] === 'done')
+    const inner = pick(end === -1 ? body : body.slice(0, end))
+    if (label === 'for') return `(for) ${inner ?? '…'}`
+    const cond = w.slice(1).filter((x) => x !== '!').map((x, i) => (i === 0 ? x.replace(/^[A-Za-z_][A-Za-z0-9_]*=\$\(/, '') : x))
+    const condShape = cond.length === 0 || cond[0] === '[' || cond[0] === '[[' || cond[0] === 'test' || cond[0] === 'true' || cond[0] === ':' ? null : shapeOfWords(cond)
+    return `(${label}) ${condShape ?? inner ?? '…'}`
+}
+
+function shapeOfWords(input: string[]): string {
+    let words = input
+    // unwrap `nice -n 15 timeout 60 env X=1 <cmd>`
+    for (;;) {
+        const head = words[0]
+        if (head == null || !(head in WRAPPERS)) break
+        let i = 1
+        const eats = ARG_FLAGS[head]
+        while (i < words.length && (words[i] as string).startsWith('-')) i += eats?.has(words[i] as string) ? 2 : 1
+        i += WRAPPERS[head] as number
+        while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i] as string)) i++
+        if (i >= words.length) break
+        words = words.slice(i)
+    }
+
+    if (words.length === 0) return '(empty)'
+    if (isScript(words[0] as string)) return base(words[0] as string)
+    let program = base(words[0] as string)
+    let rest = words.slice(1)
+    if ((program === 'bunx' || program === 'npx' || program === 'pnpx') && rest.length > 0) {
+        const pkg = rest.findIndex((w) => !w.startsWith('-'))
+        if (pkg !== -1) {
+            program = `${program} ${base(rest[pkg] as string)}`
+            rest = rest.slice(pkg + 1)
+        }
+    }
+    if (program.startsWith('python')) {
+        if (rest[0] === '-c' || rest[0] === '-m') return `${program} ${rest[0]}${rest[0] === '-m' && rest[1] != null ? ` ${rest[1]}` : ''}`
+        return rest.some((w) => isPathLike(w)) ? `${program} <file>` : program
+    }
+    if ((program === 'sed' || program === 'perl') && rest.some((w) => /^-[a-zA-Z]*i/.test(w) || w === '--in-place')) return `${program} -i (edit)`
+    if (program === 'cat' && rest[0] === '>') return 'cat > (write)'
+    if (NO_SUBCOMMAND.has(program)) return program
+
+    const parts = [program]
+    const eats = ARG_FLAGS[program]
+    const depth = TWO_LEVELS.has(program) || program === 'bun' || program === 'npm' || program === 'pnpm' ? 2 : 1
+    let subs = 0
+    for (let i = 0; i < rest.length; i++) {
+        const w = rest[i] as string
+        if (w.startsWith('-')) {
+            if (eats?.has(w)) i++
+            if (subs > 0) break
+            continue
+        }
+        if (isWord(w) && subs < depth) {
+            parts.push(w)
+            subs++
+            // `bun test x`: one level, then the argument is what it runs.
+            // `bun run x y` and `bun x y` (a package script, often the
+            // project CLI) keep the script and its first word
+            if (program === 'bun' && subs === 1 && BUN_BUILTINS.has(w) && w !== 'run') break
+            if (program === 'bun' && subs === 2 && parts[1] === 'run' && i + 1 < rest.length && isWord(rest[i + 1] as string)) {
+                parts.push(rest[i + 1] as string)
+                break
+            }
+            if ((program === 'npm' || program === 'pnpm') && subs === 1 && w !== 'run') break
+            continue
+        }
+        if (isPathLike(w) && subs === 0) parts.push('<file>')
+        break
+    }
+    if ((program === 'sk' || program === 'shipkit') && parts[1] === 'ci') {
+        const only = onlyValues(rest)
+        if (only.length > 0) return `${program} ci --only ${only.join(',')}`
+    }
+    if (program === 'bun' && parts[1] === 'test' && parts.length === 2 && rest.some((w) => isPathLike(w))) parts.push('<file>')
+    return parts.join(' ')
+}
+
+/** the `--only` values of an `sk ci` line, sorted: `--only a --only b,c` */
+function onlyValues(words: string[]): string[] {
+    const out: string[] = []
+    for (let i = 0; i < words.length; i++) {
+        const w = words[i] as string
+        if (w === '--only' && words[i + 1] != null) out.push(...(words[++i] as string).split(','))
+        else if (w.startsWith('--only=')) out.push(...w.slice(7).split(','))
+    }
+    return [...new Set(out.filter((x) => x !== ''))].sort()
+}
+
+/** the shape of any tool call: Bash by its command, a sub-agent by its type,
+ *  a skill by its name, everything else by the tool name */
+export function toolShape(name: string, detail: string): string {
+    if (name === 'Bash') return commandShape(detail)
+    if (name === 'Agent' || name === 'Task') return `Agent ${detail.split(':')[0] || 'general-purpose'}`
+    if (name === 'Skill' && detail !== '') return `Skill ${detail}`
+    return name
+}