rvlib-shipkit 2.2.0 → 2.3.0

package/src/agent-time/store.ts

@@ -0,0 +1,379 @@
+// THE AGENT TIME INDEX: every Claude Code transcript on this machine, every
+// config root, read once into one sqlite file, `~/.shipkit/agent-time.sqlite`.
+// A file is read again only when it changed, and a live session only from
+// where the last read stopped, so a warm query reads a few new lines.
+//
+// The index KEEPS what Claude Code prunes: a transcript deleted by retention
+// stays here, so the history grows past the harness's window.
+//
+// The constraint a reader breaks first: the rows hold his commands and prompts.
+// The file is machine local, under $HOME, never in a repo, and every line
+// printed from it goes through mask.ts.
+//
+// Several agents query at once: each file is indexed inside one immediate
+// transaction that reads its row again first, so two indexers never both
+// append the same lines, and a killed build resumes at the next file.
+import { Database } from 'bun:sqlite'
+import { closeSync, existsSync, mkdirSync, openSync, readSync, readdirSync, statSync } from 'fs'
+import { homedir } from 'os'
+import { basename, dirname, join } from 'path'
+import { ensureWal } from '../ledger/db.ts'
+import { type ConfigRoot, discoverConfigRoots } from '../reflect/prompt-corpus.ts'
+import { type TranscriptEvent, readTranscriptLine } from '../reflect/transcript.ts'
+import { SHAPE_VERSION, toolShape } from './shape.ts'
+import { READ_VERSION, isReadOnly } from './turns.ts'
+import type { Call, Mark } from './timeline.ts'
+
+export const AGENT_TIME_DB_ENV = 'SHIPKIT_AGENT_TIME_DB'
+
+/** bumped when what a row holds changes: every file is read again */
+export const INDEX_VERSION = 6
+
+export function agentTimeDbPath(): string {
+    const env = process.env[AGENT_TIME_DB_ENV]
+    if (env != null && env !== '') return env
+    return join(homedir(), '.shipkit', 'agent-time.sqlite')
+}
+
+const SCHEMA = `
+create table if not exists files (
+    id integer primary key,
+    path text not null unique,
+    account text not null,
+    project text not null,
+    session text not null,
+    agent text not null,
+    size integer not null,
+    mtime integer not null,
+    offset integer not null,
+    version integer not null,
+    first_at integer,
+    last_at integer,
+    gone integer not null default 0
+);
+create index if not exists files_project on files (project);
+create table if not exists calls (
+    file_id integer not null,
+    id text not null,
+    start integer not null,
+    end integer,
+    tool text not null,
+    shape text not null,
+    cmd text not null,
+    outcome text,
+    code integer,
+    approval integer not null default 0,
+    perm text not null default '',
+    read integer not null default 0
+);
+create index if not exists calls_file on calls (file_id, start);
+create table if not exists marks (
+    file_id integer not null,
+    at integer not null,
+    kind text not null
+);
+create index if not exists marks_file on marks (file_id, at);
+create table if not exists prompts (
+    file_id integer not null,
+    at integer not null,
+    uuid text,
+    origin text not null,
+    text text not null
+);
+create index if not exists prompts_file on prompts (file_id, at);
+create table if not exists meta (key text primary key, value text not null);
+`
+
+export function openIndex(path = agentTimeDbPath()): Database {
+    mkdirSync(dirname(path), { recursive: true })
+    const db = new Database(path, { create: true, readwrite: true })
+    db.exec('pragma busy_timeout = 30000')
+    ensureWal(db, 5_000)
+    db.exec('pragma synchronous = normal')
+    db.exec(SCHEMA)
+    migrate(db)
+    return db
+}
+
+/** columns added after the first build, added in place: the rows of pruned
+ *  transcripts cannot be read again, so a migration never drops a table */
+function migrate(db: Database): void {
+    const cols = (db.query('pragma table_info(calls)').all() as { name: string }[]).map((c) => c.name)
+    if (!cols.includes('approval')) db.exec('alter table calls add column approval integer not null default 0')
+    if (!cols.includes('perm')) db.exec("alter table calls add column perm text not null default ''")
+    if (!cols.includes('read')) db.exec('alter table calls add column read integer not null default 0')
+    // a tool use id is unique on the machine: a session copied into a second
+    // account (to resume it there) holds the same calls, written once
+    const unique = db.query("select 1 from sqlite_master where type = 'index' and name = 'calls_id'").get()
+    if (unique == null) {
+        db.exec('drop index if exists calls_open')
+        db.exec('delete from calls where rowid not in (select min(rowid) from calls group by id)')
+        db.exec('create unique index calls_id on calls (id)')
+    }
+    const row = db.query("select value from meta where key = 'shape'").get() as { value: string } | null
+    if (row?.value === RULES_VERSION) return
+    reshape(db)
+}
+
+/** the shape rules and the read rules, one stamp: either changing reshapes */
+const RULES_VERSION = `${SHAPE_VERSION}.${READ_VERSION}`
+
+/** a shape or read rule changed: every call is shaped and judged again from
+ *  its stored command, pruned transcripts included, no file read */
+function reshape(db: Database): void {
+    const rows = db.query('select rowid, tool, cmd, shape, read from calls').all() as { rowid: number; tool: string; cmd: string; shape: string; read: number }[]
+    const set = db.query('update calls set shape = ?, read = ? where rowid = ?')
+    db.transaction(() => {
+        for (const r of rows) {
+            const shape = toolShape(r.tool, r.cmd)
+            const read = isReadOnly({ tool: r.tool, shape, cmd: r.cmd }) ? 1 : 0
+            if (shape !== r.shape || read !== r.read) set.run(shape, read, r.rowid)
+        }
+        db.query("insert or replace into meta (key, value) values ('shape', ?)").run(RULES_VERSION)
+    })()
+}
+
+/** one transcript file on disk */
+export type TranscriptFile = { path: string; account: string; project: string; session: string; agent: string; size: number; mtime: number }
+
+/** what the index remembers of a file */
+export type IndexedFile = { size: number; mtime: number; offset: number; version: number }
+
+export type Freshness = 'skip' | 'append' | 'rebuild'
+
+/** what a file needs: nothing, its new tail, or a full read. A transcript only
+ *  grows, so a larger file with the same start is read from where the last
+ *  read stopped; anything else is read again from the top */
+export function freshness(prev: IndexedFile | null, now: { size: number; mtime: number }, version = INDEX_VERSION): Freshness {
+    if (prev == null || prev.version !== version) return 'rebuild'
+    if (now.size === prev.size && now.mtime === prev.mtime) return 'skip'
+    if (now.size > prev.size && prev.offset <= now.size) return 'append'
+    return 'rebuild'
+}
+
+/** the projects of the repos asked for: the repo's slug and its worktrees */
+export type ProjectFilter = (project: string) => boolean
+
+/** every transcript file under every config root: sessions, and the sub-agent
+ *  runs under `<session>/subagents/` */
+export function listTranscripts(roots: ConfigRoot[] = discoverConfigRoots(), keep: ProjectFilter = () => true): TranscriptFile[] {
+    const out: TranscriptFile[] = []
+    const add = (path: string, account: string, project: string, session: string, agent: string): void => {
+        try {
+            const st = statSync(path)
+            out.push({ path, account, project, session, agent, size: st.size, mtime: Math.floor(st.mtimeMs) })
+        } catch { /* deleted between the listing and the stat */ }
+    }
+    for (const root of roots) {
+        let projects: string[]
+        try { projects = readdirSync(root.projects) } catch { continue }
+        for (const project of projects) {
+            if (!keep(project)) continue
+            const dir = join(root.projects, project)
+            let entries: string[]
+            try { entries = readdirSync(dir) } catch { continue }
+            const sessions = new Set(entries.filter((e) => e.endsWith('.jsonl')).map((e) => e.slice(0, -6)))
+            for (const s of sessions) add(join(dir, `${s}.jsonl`), root.account, project, s, '')
+            for (const e of entries) {
+                if (e.endsWith('.jsonl') || e.includes('.')) continue
+                const sub = join(dir, e, 'subagents')
+                let agents: string[]
+                try { agents = readdirSync(sub) } catch { continue }
+                for (const a of agents) if (a.endsWith('.jsonl')) add(join(sub, a), root.account, project, e, a.slice(0, -6))
+            }
+        }
+    }
+    return out
+}
+
+const CHUNK_BYTES = 32 * 1024 * 1024
+
+/** every complete line of a file from `offset`, read in chunks so a session
+ *  of half a gigabyte never becomes one string. Returns the offset after the
+ *  last newline, so a half written tail line is read next time */
+function eachLine(path: string, offset: number, size: number, onLine: (line: string) => void): number {
+    const fd = openSync(path, 'r')
+    let pos = offset
+    let carry: Buffer | null = null
+    try {
+        while (pos < size) {
+            const want = Math.min(CHUNK_BYTES, size - pos)
+            const fresh = Buffer.allocUnsafe(want)
+            const n = readSync(fd, fresh, 0, want, pos)
+            if (n <= 0) break
+            pos += n
+            const buf: Buffer = carry == null ? fresh.subarray(0, n) : Buffer.concat([carry, fresh.subarray(0, n)])
+            let start = 0
+            for (;;) {
+                const end = buf.indexOf(10, start)
+                if (end === -1) break
+                if (end > start) onLine(buf.toString('utf8', start, end))
+                start = end + 1
+            }
+            carry = start < buf.length ? Buffer.from(buf.subarray(start)) : null
+        }
+    } finally {
+        closeSync(fd)
+    }
+    return pos - (carry?.length ?? 0)
+}
+
+type Stmts = ReturnType<typeof statements>
+const statements = (db: Database) => ({
+    get: db.query('select id, size, mtime, offset, version from files where path = ?'),
+    insFile: db.query('insert into files (path, account, project, session, agent, size, mtime, offset, version, first_at, last_at) values (?, ?, ?, ?, ?, 0, 0, 0, 0, null, null) returning id'),
+    setFile: db.query('update files set size = ?, mtime = ?, offset = ?, version = ?, first_at = coalesce(first_at, ?), last_at = coalesce(?, last_at), gone = 0 where id = ?'),
+    clear: [db.query('delete from calls where file_id = ?'), db.query('delete from marks where file_id = ?'), db.query('delete from prompts where file_id = ?')],
+    resetFile: db.query('update files set offset = 0, first_at = null, last_at = null where id = ?'),
+    insCall: db.query('insert or ignore into calls (file_id, id, start, end, tool, shape, cmd, outcome, code, approval, perm, read) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)'),
+    endCall: db.query('update calls set end = ?, outcome = ?, code = ?, approval = ?, perm = ? where id = ? and end is null'),
+    insMark: db.query('insert into marks (file_id, at, kind) values (?, ?, ?)'),
+    insPrompt: db.query('insert into prompts (file_id, at, uuid, origin, text) values (?, ?, ?, ?, ?)'),
+})
+
+/** write the events of a chunk of lines: a call is written once its result
+ *  is in this chunk or the chunk ends, and only once on the machine (a copy of
+ *  the session in another account is ignored); a result for a call written by
+ *  an earlier read, or by the copy, closes that row */
+function writeEvents(st: Stmts, fileId: number, events: TranscriptEvent[]): { first: number | null; last: number | null } {
+    const pending = new Map<string, { id: string; start: number; end: number | null; tool: string; detail: string; outcome: string | null; code: number | null; perm: string }>()
+    let first: number | null = null
+    let last: number | null = null
+    const seen = (at: number): void => {
+        if (Number.isNaN(at)) return
+        if (first == null || at < first) first = at
+        if (last == null || at > last) last = at
+    }
+    for (const e of events) {
+        seen(e.at)
+        if (e.kind === 'use') pending.set(e.id, { id: e.id, start: e.at, end: null, tool: e.name, detail: e.detail, outcome: null, code: null, perm: '' })
+        else if (e.kind === 'result') {
+            const p = pending.get(e.id)
+            if (p != null) Object.assign(p, { end: e.at, outcome: e.outcome, code: e.code, perm: e.perm })
+            else st.endCall.run(e.at, e.outcome, e.code, e.perm === 'user' ? 1 : 0, e.perm, e.id)
+        } else if (e.kind === 'prompt') {
+            if (!Number.isNaN(e.at)) st.insPrompt.run(fileId, e.at, e.uuid, e.origin, e.text)
+            if (e.origin === 'typed' && !Number.isNaN(e.at)) st.insMark.run(fileId, e.at, 'prompt')
+        } else st.insMark.run(fileId, e.at, e.kind)
+    }
+    for (const p of pending.values()) {
+        const shape = toolShape(p.tool, p.detail)
+        st.insCall.run(fileId, p.id, p.start, p.end, p.tool, shape, p.detail, p.outcome, p.code, p.perm === 'user' ? 1 : 0, p.perm, isReadOnly({ tool: p.tool, shape, cmd: p.detail }) ? 1 : 0)
+    }
+    return { first, last }
+}
+
+export type IndexProgress = { files: number; done: number; bytes: number; doneBytes: number }
+
+export type IndexResult = { scanned: number; read: number; bytes: number; ms: number; gone: number }
+
+/** bring the index up to date for the files listed: unchanged files cost a
+ *  stat, a grown one its new lines. `onProgress` fires after each file read */
+export function indexTranscripts(db: Database, files: TranscriptFile[], onProgress?: (p: IndexProgress) => void): IndexResult {
+    const t0 = performance.now()
+    const st = statements(db)
+    const prevOf = (path: string) => st.get.get(path) as ({ id: number } & IndexedFile) | null
+    const toRead = new Map<string, number>()
+    for (const f of files) {
+        const prev = prevOf(f.path)
+        const how = freshness(prev, f)
+        if (how !== 'skip') toRead.set(f.path, how === 'append' && prev != null ? f.size - prev.offset : f.size)
+    }
+    const todo = files.filter((f) => toRead.has(f.path))
+    const total = todo.reduce((a, f) => a + (toRead.get(f.path) ?? 0), 0)
+    let doneBytes = 0
+    let readBytes = 0
+    todo.forEach((f, i) => {
+        db.exec('begin immediate')
+        try {
+            let row = prevOf(f.path)
+            const how = freshness(row, f)
+            if (how !== 'skip') {
+                if (row == null) {
+                    const ins = st.insFile.get(f.path, f.account, f.project, f.session, f.agent) as { id: number }
+                    row = { id: ins.id, size: 0, mtime: 0, offset: 0, version: 0 }
+                }
+                let from = row.offset
+                if (how === 'rebuild') {
+                    for (const q of st.clear) q.run(row.id)
+                    st.resetFile.run(row.id)
+                    from = 0
+                }
+                const events: TranscriptEvent[] = []
+                const next = eachLine(f.path, from, f.size, (line) => {
+                    for (const e of readTranscriptLine(line)) events.push(e)
+                })
+                readBytes += next - from
+                const span = writeEvents(st, row.id, events)
+                st.setFile.run(f.size, f.mtime, next, INDEX_VERSION, span.first, span.last, row.id)
+            }
+            db.exec('commit')
+        } catch (e) {
+            db.exec('rollback')
+            throw e
+        }
+        doneBytes += toRead.get(f.path) ?? 0
+        onProgress?.({ files: todo.length, done: i + 1, bytes: total, doneBytes })
+    })
+    return { scanned: files.length, read: todo.length, bytes: readBytes, ms: Math.round(performance.now() - t0), gone: 0 }
+}
+
+/** the files the index holds that are no longer on disk, marked so the
+ *  report can say how much history outlived the harness */
+export function markGone(db: Database, onDisk: TranscriptFile[], keep: ProjectFilter): number {
+    const present = new Set(onDisk.map((f) => f.path))
+    const rows = db.query('select id, path, project, gone from files').all() as { id: number; path: string; project: string; gone: number }[]
+    let gone = 0
+    const set = db.query('update files set gone = ? where id = ?')
+    db.transaction(() => {
+        for (const r of rows) {
+            if (!keep(r.project)) continue
+            const isGone = present.has(r.path) ? 0 : 1
+            if (isGone !== r.gone) set.run(isGone, r.id)
+            gone += isGone
+        }
+    })()
+    return gone
+}
+
+export type FileRow = { id: number; path: string; account: string; project: string; session: string; agent: string; first_at: number | null; last_at: number | null; gone: number }
+
+export type Loaded = { files: FileRow[]; calls: Map<number, Call[]>; marks: Map<number, Mark[]>; prompts: { file_id: number; at: number; origin: 'typed' | 'queued'; text: string }[] }
+
+/** every row of the matching projects with activity in [from, to] */
+export function loadWindow(db: Database, keep: ProjectFilter, from: number, to: number): Loaded {
+    const all = db.query('select id, path, account, project, session, agent, first_at, last_at, gone from files').all() as FileRow[]
+    const files = all.filter((f) => keep(f.project) && f.last_at != null && f.last_at >= from && (f.first_at ?? 0) <= to)
+    const ids = files.map((f) => f.id)
+    const calls = new Map<number, Call[]>()
+    const marks = new Map<number, Mark[]>()
+    const prompts: Loaded['prompts'] = []
+    const CHUNK = 500
+    for (let i = 0; i < ids.length; i += CHUNK) {
+        const part = ids.slice(i, i + CHUNK)
+        const inList = part.map(() => '?').join(',')
+        for (const c of db.query(`select file_id, id, start, end, tool, shape, cmd, outcome, code, approval = 1 as approval, perm, read = 1 as read from calls where file_id in (${inList}) and start between ? and ?`).all(...part, from, to) as (Call & { file_id: number })[]) {
+            const list = calls.get(c.file_id) ?? []
+            list.push(c)
+            calls.set(c.file_id, list)
+        }
+        for (const m of db.query(`select file_id, at, kind from marks where file_id in (${inList}) and at between ? and ?`).all(...part, from, to) as (Mark & { file_id: number })[]) {
+            const list = marks.get(m.file_id) ?? []
+            list.push(m)
+            marks.set(m.file_id, list)
+        }
+        prompts.push(...(db.query(`select file_id, at, origin, text from prompts where file_id in (${inList}) and at between ? and ?`).all(...part, from, to) as Loaded['prompts']))
+    }
+    return { files, calls, marks, prompts }
+}
+
+/** the repo a project dir belongs to: its slug without the worktree suffix,
+ *  named by what follows the home dev folder when it sits there */
+export function repoOfProject(project: string, home = homedir()): string {
+    const bare = project.replace(/--claude-worktrees-.*$/, '')
+    const devSlug = join(home, 'dev').replace(/[^a-zA-Z0-9]/g, '-')
+    return bare.startsWith(`${devSlug}-`) ? bare.slice(devSlug.length + 1) : bare
+}
+
+export const fileLabel = (path: string): string => basename(path).replace(/\.jsonl$/, '')
+

package/src/agent-time/timeline.ts

@@ -0,0 +1,218 @@
+// The time math of one transcript stream (a session, or one sub-agent run):
+// how long each tool call took, and where the wall time went.
+//
+// The constraint a reader breaks first: parallel calls overlap. A call's own
+// time is end minus start, and a sum of those is CALL time, which can exceed
+// the wall. The wall is cut once, by a sweep over every boundary, so a second
+// of wall lands in exactly one bucket.
+import type { Outcome } from '../reflect/transcript.ts'
+
+export type Call = {
+    id: string
+    start: number
+    /** null while its result has not arrived (a live call, or one never answered) */
+    end: number | null
+    tool: string
+    shape: string
+    cmd: string
+    outcome: Outcome | null
+    code: number | null
+    /** it waited for the human to allow it */
+    approval: boolean
+    /** how it was allowed (transcript.ts Perm) */
+    perm: string
+    /** it only read (turns.ts isReadOnly, judged when indexed) */
+    read: boolean
+}
+
+export type Mark = { at: number; kind: 'prompt' | 'wake' | 'message' | 'reply' }
+
+export type Stream = { calls: Call[]; marks: Mark[] }
+
+/** where a slice of wall time went */
+export type Bucket = 'model' | 'tools' | 'approval' | 'subagent' | 'background' | 'human' | 'idle'
+
+export type Breakdown = Record<Bucket, number>
+
+/** a wait on him longer than this is the session parked, not a wait */
+export const IDLE_MS = 30 * 60 * 1000
+
+export const emptyBreakdown = (): Breakdown => ({ model: 0, tools: 0, approval: 0, subagent: 0, background: 0, human: 0, idle: 0 })
+
+/** a foreground sub-agent call: the session waits on another agent's work */
+export const isAgentCall = (c: Call): boolean => c.tool === 'Agent' || c.tool === 'Task'
+
+/** the first value of a sorted list above `t`, by bisection */
+function firstAfter(sorted: number[], t: number): number | undefined {
+    let lo = 0
+    let hi = sorted.length
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1
+        if ((sorted[mid] as number) <= t) lo = mid + 1
+        else hi = mid
+    }
+    return sorted[lo]
+}
+
+/** the end every call is measured to: its result, else the next prompt or wake
+ *  after it (the human moved on, so it was interrupted), else the stream's last
+ *  event. `open` says the end was inferred */
+export type Closed = Call & { stop: number; open: boolean }
+
+/** sorted by start */
+export function closeCalls(s: Stream): Closed[] {
+    const turns = s.marks.filter((m) => m.kind !== 'reply').map((m) => m.at).sort((a, b) => a - b)
+    let last = 0
+    for (const m of s.marks) if (m.at > last) last = m.at
+    for (const c of s.calls) if ((c.end ?? c.start) > last) last = c.end ?? c.start
+    return s.calls
+        .map((c): Closed => {
+            if (c.end != null) return { ...c, stop: Math.max(c.start, c.end), open: false }
+            const next = firstAfter(turns, c.start)
+            return { ...c, stop: next ?? last, open: true }
+        })
+        .sort((a, b) => a.start - b.start)
+}
+
+/** the call's own duration in ms */
+export const callMs = (c: { start: number; stop: number }): number => Math.max(0, c.stop - c.start)
+
+type Point = { at: number; d: 'start' | 'stop' | Mark['kind']; lane: 'tool' | 'agent' | 'approval'; ix: number }
+
+/** the wall of one stream cut into buckets, clipped to [from, to]. Between two
+ *  boundaries: a tool in flight → tools; only calls waiting for his allow →
+ *  approval; only a sub-agent in flight → subagent;
+ *  nothing in flight and the next thing is his prompt → human (idle past
+ *  IDLE_MS); the next thing is a wake (a task notification, a hand-back) →
+ *  background; a message relayed in counts as a prompt (a sub-agent that
+ *  handed back sits parked until the coordinator or he writes to it); anything else → the model was working.
+ *
+ *  `turnModel` (one slot per closed call) receives the model stretch that
+ *  ended in each call: the turn that issued it, split evenly over the calls
+ *  of one batch. A stretch that ends in his prompt or a wake was the final
+ *  reply and goes to no call */
+export function wallBreakdown(s: Stream, from = -Infinity, to = Infinity, idleMs = IDLE_MS, closed: Closed[] = closeCalls(s), turnModel?: Float64Array): Breakdown {
+    const out = emptyBreakdown()
+    const points: Point[] = []
+    closed.forEach((c, ix) => {
+        const lane = isAgentCall(c) ? 'agent' : c.approval ? 'approval' : 'tool'
+        points.push({ at: c.start, d: 'start', lane, ix }, { at: c.stop, d: 'stop', lane, ix })
+    })
+    for (const m of s.marks) points.push({ at: m.at, d: m.kind, lane: 'tool', ix: -1 })
+    points.sort((a, b) => a.at - b.at)
+    let tools = 0
+    let agents = 0
+    let approvals = 0
+    let pending = 0
+    const issued: number[] = []
+    let i = 0
+    while (i < points.length) {
+        const at = (points[i] as Point).at
+        issued.length = 0
+        let ended = false
+        while (i < points.length && (points[i] as Point).at === at) {
+            const p = points[i] as Point
+            const n = p.d === 'start' ? 1 : p.d === 'stop' ? -1 : 0
+            if (p.lane === 'agent') agents += n
+            else if (p.lane === 'approval') approvals += n
+            else tools += n
+            if (p.d === 'start') issued.push(p.ix)
+            else if (p.d === 'prompt' || p.d === 'wake' || p.d === 'message') ended = true
+            i++
+        }
+        if (turnModel != null) {
+            if (issued.length > 0) for (const ix of issued) turnModel[ix] = (turnModel[ix] ?? 0) + pending / issued.length
+            if (issued.length > 0 || ended) pending = 0
+        }
+        if (i >= points.length) break
+        const nextAt = (points[i] as Point).at
+        const a = Math.max(at, from)
+        const b = Math.min(nextAt, to)
+        if (b <= a) continue
+        const len = b - a
+        let bucket: Bucket
+        if (tools > 0) bucket = 'tools'
+        else if (approvals > 0) bucket = 'approval'
+        else if (agents > 0) bucket = 'subagent'
+        else {
+            let next = i
+            let prompt = false
+            let wake = false
+            while (next < points.length && (points[next] as Point).at === nextAt) {
+                const d = (points[next] as Point).d
+                if (d === 'prompt' || d === 'message') prompt = true
+                if (d === 'wake') wake = true
+                next++
+            }
+            const gap = nextAt - at
+            bucket = prompt ? (gap > idleMs ? 'idle' : 'human') : wake ? 'background' : 'model'
+        }
+        out[bucket] += len
+        if (bucket === 'model') pending += len
+    }
+    return out
+}
+
+export const addBreakdown = (into: Breakdown, b: Breakdown): Breakdown => {
+    for (const k of Object.keys(into) as Bucket[]) into[k] += b[k]
+    return into
+}
+
+/** a failed call is retried when the next call of the same shape in the
+ *  stream comes within this window */
+export const RETRY_MS = 10 * 60 * 1000
+
+export const FAILED: ReadonlySet<Outcome> = new Set<Outcome>(['exit', 'error', 'timeout'])
+
+export type Retry = { failed: Closed; next: Closed; blind: boolean }
+
+/** every failed call followed by the same shape again: `blind` when the
+ *  command is the exact same text, so nothing changed between the two.
+ *  `calls` sorted by start (closeCalls) */
+export function retries(calls: Closed[]): Retry[] {
+    const out: Retry[] = []
+    const nextOfShape = new Map<string, Closed>()
+    for (let i = calls.length - 1; i >= 0; i--) {
+        const c = calls[i] as Closed
+        const next = nextOfShape.get(c.shape)
+        nextOfShape.set(c.shape, c)
+        if (c.outcome == null || !FAILED.has(c.outcome)) continue
+        if (next == null || next.start - c.stop > RETRY_MS) continue
+        out.push({ failed: c, next, blind: next.cmd.trim() === c.cmd.trim() })
+    }
+    return out.reverse()
+}
+
+/** a call that ran longer than this before a complaint is not looked for */
+const LOOKBACK_MS = 3 * 60 * 60 * 1000
+
+/** what the agent ran in the minutes before `at`: calls in flight at that
+ *  moment or started in the window, cut at `at`, longest first. `calls`
+ *  sorted by start (closeCalls) */
+export function ranBefore(calls: Closed[], at: number, windowMs = 10 * 60 * 1000): Closed[] {
+    let lo = 0
+    let hi = calls.length
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1
+        if ((calls[mid] as Closed).start <= at) lo = mid + 1
+        else hi = mid
+    }
+    const out: Closed[] = []
+    for (let i = lo - 1; i >= 0; i--) {
+        const c = calls[i] as Closed
+        if (c.start < at - LOOKBACK_MS) break
+        if (c.stop >= at - windowMs) out.push({ ...c, stop: Math.min(c.stop, at) })
+    }
+    return out.sort((a, b) => callMs(b) - callMs(a))
+}
+
+/** p in [0, 1] of a list of ms, nearest rank */
+export function quantile(xs: number[], p: number): number {
+    return quantileSorted([...xs].sort((a, b) => a - b), p)
+}
+
+/** the same over a list already sorted ascending */
+export function quantileSorted(s: number[], p: number): number {
+    if (s.length === 0) return 0
+    return s[Math.min(s.length - 1, Math.max(0, Math.ceil(p * s.length) - 1))] ?? 0
+}