rvlib-shipkit 2.2.0 → 2.4.0

package/src/cli/kit/verb.ts

@@ -61,6 +61,14 @@ export type Verb = {
     essential?: Essential
     /** filmable: takes `--out <path>`, a clip also `--seconds <n>` (a trailer `film` line calls it) */
     film?: Film
+    /** with film: the row's take version, a bump films every trailer take of the row again */
+    version?: number | string
+    /** with film: `own`, a clip that films as long as it plays (no `--seconds`) */
+    length?: 'own'
+    /** with film: the words it takes and their types (trailer/words.ts), each checked at its line of a .trailer */
+    words?: Record<string, unknown>
+    /** with film: the paths its takes film, their world */
+    stamp?: string[]
 }
 
 /** the argv a row runs */
@@ -120,6 +128,10 @@ export function verbs(rows: Verb[]): CommandClass[] {
             static override usage = Command.Usage({ category: v.category, description: v.description, details: v.details, examples: v.examples })
             static essential = v.essential
             static film = v.film
+            static filmVersion = v.version
+            static filmLength = v.length
+            static filmWords = v.words
+            static filmStamp = v.stamp
             args = Option.Proxy()
             async execute(): Promise<number> {
                 const { root, cwd } = this.context
@@ -148,10 +160,16 @@ export function verbs(rows: Verb[]): CommandClass[] {
 
 /** the marks a command class carries: set by `verbs()` from its row, or
  *  declared as statics on a hand written class */
-export function marksOf(c: object): { essential?: Essential; film?: Film } {
-    const o = c as { essential?: unknown; film?: unknown }
-    const out: { essential?: Essential; film?: Film } = {}
+export function marksOf(c: object): { essential?: Essential; film?: Film; version?: number | string; length?: 'own'; words?: Record<string, unknown>; stamp?: string[] } {
+    const o = c as { essential?: unknown; film?: unknown; filmVersion?: unknown; filmLength?: unknown; filmWords?: unknown; filmStamp?: unknown }
+    const out: { essential?: Essential; film?: Film; version?: number | string; length?: 'own'; words?: Record<string, unknown>; stamp?: string[] } = {}
     if (typeof o.essential === 'object' && o.essential !== null) out.essential = o.essential as Essential
-    if (o.film === 'still' || o.film === 'clip') out.film = o.film
+    if (o.film === 'still' || o.film === 'clip') {
+        out.film = o.film
+        if (typeof o.filmVersion === 'number' || typeof o.filmVersion === 'string') out.version = o.filmVersion
+        if (o.filmLength === 'own') out.length = 'own'
+        if (typeof o.filmWords === 'object' && o.filmWords !== null) out.words = o.filmWords as Record<string, unknown>
+        if (Array.isArray(o.filmStamp)) out.stamp = o.filmStamp.map(String)
+    }
     return out
 }

package/src/cli.ts

@@ -8,6 +8,7 @@ import { AskNewCommand, AsksCheckCommand, AsksCommand } from './cli/cmd_Asks.ts'
 import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand } from './cli/cmd_Assets.ts'
 import { BumpCommand } from './cli/cmd_Bump.ts'
 import { CallsCommand } from './cli/cmd_Calls.ts'
+import { TimeCommand } from './cli/cmd_Time.ts'
 import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
@@ -39,7 +40,9 @@ import { SmokeCommand } from './cli/cmd_Smoke.ts'
 import { ShotCommand } from './cli/cmd_Shot.ts'
 import { StatusCommand } from './cli/cmd_Status.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
-import { TrailerCheckCommand, TrailerCommand, TrailerShotCommand } from './cli/cmd_Trailer.ts'
+import { TRAILER_COMMANDS } from './cli/cmd_Trailer.ts'
+import { SOUND_COMMANDS } from './cli/cmd_Sound.ts'
+import { REVIEW_COMMANDS } from './cli/cmd_Review.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 
@@ -70,9 +73,9 @@ export function buildCli(): Cli {
     cli.register(MvCommand)
     cli.register(CheckCommand)
     cli.register(TuiCommand)
-    cli.register(TrailerCommand)
-    cli.register(TrailerCheckCommand)
-    cli.register(TrailerShotCommand)
+    for (const c of TRAILER_COMMANDS) cli.register(c)
+    for (const c of SOUND_COMMANDS) cli.register(c)
+    for (const c of REVIEW_COMMANDS) cli.register(c)
     cli.register(ServeCommand)
     cli.register(PmCommand)
     cli.register(DaemonCommand)
@@ -117,6 +120,7 @@ export function buildCli(): Cli {
     cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
     cli.register(CallsCommand)
+    cli.register(TimeCommand)
     cli.register(ConfigKeysCommand)
 
     return cli

package/src/collections/collection-types.ts

@@ -31,7 +31,12 @@ export const NO_CHECK = 'in no check'
  *  section a row lives under (hub-app/tree-build.ts KIND_SECTION). There is no
  *  catch all kind: a row belongs to an owner, and what belongs to the hub
  *  itself is its status (serve/hub-problems.ts), never a row */
-export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection', 'process'] as const
+export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection', 'process', 'card', 'cut'] as const
+
+/** the collection of the review cards that wait on him (collections/review.ts) */
+export const REVIEW_COL = 'review'
+/** the collection of the trailer cuts, one row a cut (collections/review.ts) */
+export const TRAILER_COL = 'trailers'
 
 export type ResourceType = (typeof RESOURCE_TYPES)[number]
 

package/src/collections/providers.ts

@@ -27,6 +27,7 @@ import { mdBody } from './md-body.ts'
 import { socialPostsCollection } from './posts.ts'
 import { assetState, secretState, type SecretLevel, type SecretProbe } from './state-rules.ts'
 import { reflectionsCollection } from './reflections.ts'
+import { reviewCollection, trailersCollection } from './review.ts'
 import { testsCollection } from './tests.ts'
 import { checksCollection } from './checks.ts'
 import { LAYOUT } from '../core/layout.ts'
@@ -417,5 +418,7 @@ export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit |
         socialPostsCollection(root),
         reflectionsCollection(root),
         testsCollection(root, c),
+        // only where the repo has a review store or a trailer folder: the section of a repo with none is greyed
+        ...[reviewCollection(root), trailersCollection(root)].filter((x): x is Collection => x !== null),
     ]
 }

package/src/collections/review.ts

@@ -0,0 +1,70 @@
+// the review store and the trailer cuts as tree rows (wiki build/shipkit/review.md). Under the review section, one row a
+// card that waits on HIM (the owner's verdict, his answer to a question): yellow, so `sk needs` lists it too. Under the trailer
+// section, one row a cut, its open frame notes in the slot: they wait on agents, never on him, so a cut is never yellow.
+// Each collection exists only where the repo has its folder, so a repo with none draws the section greyed
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { STATUS_LABEL, isFrame, stateOf } from '../review/model.ts'
+import { readAllCached, storeDir } from '../review/store.ts'
+import { statusOf, waitingOnOwner } from '../review/threads.ts'
+import { cutsOf, trailerIds } from '../review/trailer-desk.ts'
+import { REVIEW_COL, TRAILER_COL, type Collection, type Instance } from './collection-types.ts'
+
+export function reviewCollection(root: string): Collection | null {
+    const dir = storeDir(root)
+    if (!existsSync(dir)) return null
+    return {
+        id: REVIEW_COL,
+        title: 'review',
+        kind: 'card',
+        media: 'image',
+        list: async () => {
+            const { items } = readAllCached(dir)
+            return waitingOnOwner(items).map(({ head: x }): Instance => ({
+                id: `card:${x.item.id}`,
+                text: `${x.item.title} (${STATUS_LABEL[statusOf(x, items)]})`,
+                label: x.item.title,
+                slot: x.item.origin.by === 'agent' ? (x.item.origin.lane ?? 'card') : 'question',
+                type: 'card',
+                path: `.shipkit/review/${x.item.id}`,
+                severity: 'yellow',
+                verbs: ['approve'],
+            }))
+        },
+    }
+}
+
+export function trailersCollection(root: string): Collection | null {
+    const ids = trailerIds(root)
+    if (ids.length === 0) return null
+    return {
+        id: TRAILER_COL,
+        title: 'trailer',
+        kind: 'cut',
+        media: 'image',
+        list: async () => {
+            const dir = storeDir(root)
+            const items = existsSync(dir) ? readAllCached(dir).items : []
+            const open = new Map<string, number>()
+            for (const x of items) {
+                const s = x.item.subject
+                if (isFrame(s) && stateOf(x, false).state !== 'closed') open.set(`${s.trailer}/${s.cut}`, (open.get(`${s.trailer}/${s.cut}`) ?? 0) + 1)
+            }
+            return ids.flatMap((id) =>
+                cutsOf(join(root, 'trailer', id)).map((c): Instance => {
+                    const n = open.get(`${id}/${c.cut}`) ?? 0
+                    const rendered = existsSync(join(root, 'trailer', id, 'out', `${c.name}.mp4`))
+                    return {
+                        id: `cut:${id}/${c.cut}`,
+                        text: `${id} ${c.cut}${rendered ? '' : ' (not rendered)'}${n > 0 ? `, ${n} open note${n > 1 ? 's' : ''}` : ''}`,
+                        label: ids.length > 1 ? `${id} · ${c.cut}` : c.cut,
+                        slot: n > 0 ? `${n} open` : rendered ? '' : 'no render',
+                        type: 'cut',
+                        path: c.trailer === null ? `trailer/${id}/out/${c.name}.mp4` : `trailer/${id}/${c.cut}.trailer`,
+                        state: rendered ? 'idle' : 'quiet',
+                    }
+                }),
+            )
+        },
+    }
+}

package/src/core/app-icon.ts

@@ -10,8 +10,9 @@ import { identityOfName, identityOfText, type Identity } from './identity-color.
 import { configName, CONFIG_FILE } from './identity.ts'
 import { LAYOUT } from './layout.ts'
 
-/** the mark an app wears: the repo's own, largest first. Rasters only */
-export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, 'public/logo.png', 'public/favicon.png']
+/** the mark an app wears: the repo's own, largest first; an svg mark is drawn
+ *  as an image too (the canvas decodes it) */
+export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, `${LAYOUT.identity}/icon.svg`, 'public/logo.png', 'public/favicon.png']
 
 export function appIconOf(root: string): string | null {
     for (const f of APP_ICON_FILES) if (existsSync(join(root, f))) return join(root, f)
@@ -133,15 +134,18 @@ export async function drawAppIcon(bytes: Uint8Array, id: Identity): Promise<{ ca
     return { canvas: out, plate: colour }
 }
 
-/** the icon as pngs, one per size asked, drawn once */
-export async function appIconPngs(bytes: Uint8Array, id: Identity, sizes: number[] = [ICON_PX]): Promise<Buffer[]> {
+/** the icon as pngs, one per size asked, drawn once. `plate` crops the macOS
+ *  grid's margin away, the rounded plate edge to edge (the hub's rail) */
+export async function appIconPngs(bytes: Uint8Array, id: Identity, sizes: number[] = [ICON_PX], crop: 'canvas' | 'plate' = 'canvas'): Promise<Buffer[]> {
     const { canvas } = await drawAppIcon(bytes, id)
+    const o = crop === 'plate' ? (ICON_PX - PLATE) / 2 : 0
+    const side = crop === 'plate' ? PLATE : ICON_PX
     return sizes.map((px) => {
-        if (px === ICON_PX) return canvas.toBuffer('image/png')
+        if (px === ICON_PX && crop === 'canvas') return canvas.toBuffer('image/png')
         const small = createCanvas(px, px)
         const ctx = small.getContext('2d')
         ctx.imageSmoothingQuality = 'high'
-        ctx.drawImage(canvas, 0, 0, px, px)
+        ctx.drawImage(canvas, o, o, side, side, 0, 0, px, px)
         return small.toBuffer('image/png')
     })
 }

package/src/core/layout.ts

@@ -36,6 +36,8 @@ export const LAYOUT = {
     discord: sk('discord'),
     // a review with no output file named by its caller (YYYYMMDD-HHMMSS-<name>.md)
     reviews: sk('reviews'),
+    // the one feedback store: review cards and frame notes, one folder an item (review/store.ts)
+    review: sk('review'),
     // gitignored scratch, never a plan home: logs, leases, detached runs, screenshots
     tmp: sk('tmp'),
     // a CLI's call log, `<cli>-calls.jsonl`: local, never tracked

package/src/reflect/prompt-corpus.ts

@@ -2,13 +2,12 @@
 // Transcripts live at <configRoot>/projects/<slug>/*.jsonl where <slug> is the
 // repo's absolute path with EVERY non-alphanumeric char replaced by '-'.
 //
-// A corpus is only as good as what it excludes: the harness writes many
-// user-role entries the human never typed (tool results, command wrappers,
-// compaction summaries, subagent prompts). Every filter below exists because
-// one of them polluted a real extraction pass.
+// What counts as typed is the shared transcript reader's call (transcript.ts):
+// this module finds the files, dedupes and renders.
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { homedir } from 'os'
 import { basename, join, resolve } from 'path'
+import { isTypedPrompt, readTranscriptLine } from './transcript.ts'
 
 export type PromptEntry = {
     uuid: string
@@ -56,126 +55,23 @@ export function discoverConfigRoots(home: string = homedir()): ConfigRoot[] {
 /** Claude Code slugs EVERY non-alphanumeric char to '-', not just '/' */
 export const projectSlug = (repoPath: string): string => resolve(repoPath).replace(/[^a-zA-Z0-9]/g, '-')
 
-// wrappers the harness injects as user-role entries — none of them are typed
-const NOISE_PREFIXES = [
-    '<local-command-caveat>',
-    '<local-command-stdout>',
-    '<command-name>',
-    '<command-message>',
-    '<system-reminder>',
-    '<task-notification>',
-    'Caveat: The messages below',
-    '[Request interrupted',
-    'This session is being continued from a previous conversation',
-    // model output parked in the queue (or wrapped as a meta entry): a
-    // sub-agent's hand-back, and a message another Claude session sent
-    '<agent-message',
-    '<cross-session-message',
-    'Another Claude session sent a message',
-]
-
-export function isTypedPrompt(text: string): boolean {
-    const trimmed = text.trim()
-    if (trimmed === '') return false
-    return !NOISE_PREFIXES.some((p) => trimmed.startsWith(p))
-}
-
-type RawEntry = {
-    type?: unknown
-    entrypoint?: unknown
-    uuid?: unknown
-    timestamp?: unknown
-    sessionId?: unknown
-    isMeta?: unknown
-    isSidechain?: unknown
-    isCompactSummary?: unknown
-    /** queue-operation entries only */
-    operation?: unknown
-    content?: unknown
-    message?: { role?: unknown; content?: unknown }
-}
-
-/** the typed prompt out of one transcript line, or null when the line is not one
- * he typed. isSidechain = a subagent prompt the AGENT wrote; isMeta and
- * isCompactSummary = harness-generated. Content is a string for a plain prompt,
- * an array of blocks when the message carried pastes or attachments (the text
- * blocks in there are still his). */
-export function promptTextOf(line: string): { text: string; entry: RawEntry } | null {
-    let parsed: unknown
-    try {
-        parsed = JSON.parse(line)
-    } catch {
-        return null // truncated tail line of a live session
-    }
-    if (parsed == null || typeof parsed !== 'object') return null
-    const entry = parsed as RawEntry
-    if (entry.type !== 'user') return null
-    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true) return null
-    if (entry.entrypoint === 'sdk-cli') return null // a script drove this session, nobody typed it
-    if (entry.message?.role !== 'user') return null
-    const content = entry.message.content
-    let text: string
-    if (typeof content === 'string') text = content
-    else if (Array.isArray(content)) {
-        const parts = content
-            .filter((b): b is { type: string; text: string } => b?.type === 'text' && typeof b?.text === 'string')
-            .map((b) => b.text)
-        if (parts.length === 0) return null // pure tool_result turn
-        text = parts.join('\n')
-    } else return null
-    // the harness appends reminder blocks INSIDE real prompts — strip, keep the text
-    text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
-    // a slash-command entry is a harness WRAPPER around typed text:
-    // <command-name>/cmd</command-name><command-args>THE TEXT</command-args>.
-    // Dropping the whole entry throws away real instructions and repro pastes.
-    const args = text.match(/<command-args>([\s\S]*?)<\/command-args>/)
-    if (args?.[1] != null) {
-        const body = args[1].trim()
-        if (body === '') return null // bare invocation, nothing typed
-        const name = text.match(/<command-name>([\s\S]*?)<\/command-name>/)
-        text = name?.[1] == null ? body : `${name[1].trim()} ${body}`
-    }
-    if (!isTypedPrompt(text)) return null
-    return { text, entry }
-}
-
-/** A prompt he typed while the agent was still working: the harness parks it as
- * `{type:'queue-operation', operation:'enqueue', content}` and, if the run ends
- * first, it may NEVER become a user message. Skipping these loses exactly the
- * mid-flight corrections and standing conventions a retrospective is for */
-export function queuedTextOf(line: string): { text: string; entry: RawEntry } | null {
-    let parsed: unknown
-    try {
-        parsed = JSON.parse(line)
-    } catch {
-        return null
-    }
-    if (parsed == null || typeof parsed !== 'object') return null
-    const entry = parsed as RawEntry
-    if (entry.type !== 'queue-operation' || entry.operation !== 'enqueue') return null
-    if (typeof entry.content !== 'string') return null
-    const text = entry.content.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
-    if (!isTypedPrompt(text)) return null
-    return { text, entry }
-}
+export { isTypedPrompt } from './transcript.ts'
 
 export function extractPrompts(jsonl: string, ctx: { sessionId: string; account: string }): PromptEntry[] {
     const out: PromptEntry[] = []
     for (const line of jsonl.split('\n')) {
         if (line.trim() === '') continue
-        const queued = queuedTextOf(line)
-        const hit = queued ?? promptTextOf(line)
-        if (hit == null) continue
-        const timestamp = typeof hit.entry.timestamp === 'string' ? hit.entry.timestamp : ''
-        const fallbackId = `${queued == null ? 'typed' : 'queue'}:${ctx.sessionId}:${timestamp}`
-        out.push({
-            uuid: typeof hit.entry.uuid === 'string' ? hit.entry.uuid : fallbackId,
-            timestamp,
-            sessionId: typeof hit.entry.sessionId === 'string' ? hit.entry.sessionId : ctx.sessionId,
-            account: ctx.account,
-            text: hit.text,
-            origin: queued == null ? 'typed' : 'queued',
-        })
+        for (const ev of readTranscriptLine(line)) {
+            if (ev.kind !== 'prompt') continue
+            out.push({
+                uuid: ev.uuid ?? `${ev.origin === 'typed' ? 'typed' : 'queue'}:${ctx.sessionId}:${ev.timestamp}`,
+                timestamp: ev.timestamp,
+                sessionId: ev.sessionId ?? ctx.sessionId,
+                account: ctx.account,
+                text: ev.text,
+                origin: ev.origin,
+            })
+        }
     }
     return out
 }

package/src/reflect/transcript.ts

@@ -0,0 +1,254 @@
+// THE transcript reader: one Claude Code jsonl line in, the events it holds out.
+// `sk reflect` keeps the prompts, `sk time` keeps everything. One parser for
+// both, so a harness shape fixed here is fixed for every reader.
+//
+// A line is one entry. An assistant entry holds ONE content block (thinking,
+// text or tool_use), the user entry after a tool_use holds its tool_result,
+// and the harness writes many user-role entries the human never typed (tool
+// results, command wrappers, compaction summaries, sub-agent hand-backs).
+// Every prompt filter below exists because one of them polluted a real pass.
+
+export type PromptOrigin = 'typed' | 'queued'
+
+/** how a call was allowed: by the human (`user`), by the auto mode
+ *  classifier (a model call before the tool runs), by a rule or a hook, by the
+ *  permission mode, or not recorded */
+export type Perm = 'user' | 'classifier' | 'rule' | 'mode' | ''
+
+export function permOf(d: { source?: unknown; reasonType?: unknown } | undefined): Perm {
+    if (d == null) return ''
+    if (typeof d.source === 'string' && d.source.startsWith('user')) return 'user'
+    if (d.reasonType === 'classifier') return 'classifier'
+    if (d.reasonType === 'mode') return 'mode'
+    return typeof d.source === 'string' ? 'rule' : ''
+}
+
+/** the harness's wrapper around a message relayed into a running agent */
+const RELAYED = /^[^\n]{1,80}? sent (?:a new |a )?message while you were working\b/
+
+/** how a tool call ended, read from its tool_result */
+export type Outcome = 'ok' | 'exit' | 'timeout' | 'blocked' | 'denied' | 'interrupted' | 'error'
+
+export type TranscriptEvent =
+    /** a prompt the human typed; `queued` = typed while the agent worked */
+    | { kind: 'prompt'; at: number; timestamp: string; uuid: string | null; sessionId: string | null; text: string; origin: PromptOrigin }
+    /** a user-role turn nobody typed that wakes the agent: a task notification,
+     *  a sub-agent hand-back, a peer message, a script-driven prompt */
+    | { kind: 'wake'; at: number }
+    /** a message relayed into the agent (the coordinator, the human, another
+     *  session "sent a message while you were working"): it can end a park of
+     *  hours after the agent handed back */
+    | { kind: 'message'; at: number }
+    | { kind: 'use'; at: number; id: string; name: string; detail: string }
+    /** `perm`: how the call was allowed; `user` = it waited for the human, so its time is his */
+    | { kind: 'result'; at: number; id: string; outcome: Outcome; code: number | null; perm: Perm }
+    /** an assistant text block: the agent talking, which can end its turn */
+    | { kind: 'reply'; at: number }
+
+// wrappers the harness injects as user-role entries: none of them are typed
+const NOISE_PREFIXES = [
+    '<local-command-caveat>',
+    '<local-command-stdout>',
+    '<command-name>',
+    '<command-message>',
+    '<system-reminder>',
+    '<task-notification>',
+    'Caveat: The messages below',
+    '[Request interrupted',
+    'This session is being continued from a previous conversation',
+    // model output parked in the queue (or wrapped as a meta entry): a
+    // sub-agent's hand-back, and a message another Claude session sent
+    '<agent-message',
+    '<cross-session-message',
+    'Another Claude session sent a message',
+]
+
+export function isTypedPrompt(text: string): boolean {
+    const trimmed = text.trim()
+    if (trimmed === '') return false
+    return !NOISE_PREFIXES.some((p) => trimmed.startsWith(p))
+}
+
+type Block = { type?: unknown; text?: unknown; id?: unknown; name?: unknown; input?: unknown; tool_use_id?: unknown; is_error?: unknown; content?: unknown }
+
+export type RawEntry = {
+    type?: unknown
+    entrypoint?: unknown
+    uuid?: unknown
+    timestamp?: unknown
+    sessionId?: unknown
+    isMeta?: unknown
+    isSidechain?: unknown
+    isCompactSummary?: unknown
+    /** `peer` on a sub-agent hand-back or another session's message */
+    turnOrigin?: unknown
+    /** queue-operation entries only */
+    operation?: unknown
+    content?: unknown
+    message?: { role?: unknown; content?: unknown }
+    toolUseResult?: unknown
+    /** on a tool_result entry: who allowed the call (`config`, `user_temporary`, …) */
+    permissionDecision?: { source?: unknown; reasonType?: unknown }
+}
+
+const stripReminders = (text: string): string => text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
+
+/** the user text of a user entry, reminders stripped, a slash command's typed
+ *  args rescued; null when it carries no text at all (a pure tool_result turn).
+ *  Content is a string for a plain prompt, an array of blocks when the message
+ *  carried pastes or attachments (the text blocks in there are still his). */
+function userText(entry: RawEntry): string | null {
+    const content = entry.message?.content
+    let text: string
+    if (typeof content === 'string') text = content
+    else if (Array.isArray(content)) {
+        const parts = (content as Block[]).filter((b) => b?.type === 'text' && typeof b?.text === 'string').map((b) => b.text as string)
+        if (parts.length === 0) return null
+        text = parts.join('\n')
+    } else return null
+    text = stripReminders(text)
+    // a slash-command entry is a harness WRAPPER around typed text:
+    // <command-name>/cmd</command-name><command-args>THE TEXT</command-args>.
+    // Dropping the whole entry throws away real instructions and repro pastes.
+    const args = text.match(/<command-args>([\s\S]*?)<\/command-args>/)
+    if (args?.[1] != null) {
+        const body = args[1].trim()
+        if (body === '') return ''
+        const name = text.match(/<command-name>([\s\S]*?)<\/command-name>/)
+        text = name?.[1] == null ? body : `${name[1].trim()} ${body}`
+    }
+    return text
+}
+
+/** the typed prompt out of a parsed user entry, or null when he did not type
+ *  it. isSidechain = a subagent prompt the AGENT wrote; isMeta and
+ *  isCompactSummary = harness-generated; entrypoint sdk-cli = a script drove it */
+export function typedPromptOf(entry: RawEntry): string | null {
+    if (entry.type !== 'user') return null
+    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true) return null
+    if (entry.entrypoint === 'sdk-cli') return null
+    if (entry.message?.role !== 'user') return null
+    const text = userText(entry)
+    if (text == null || !isTypedPrompt(text)) return null
+    return text
+}
+
+/** A prompt he typed while the agent was still working: the harness parks it as
+ *  `{type:'queue-operation', operation:'enqueue', content}` and, if the run ends
+ *  first, it may NEVER become a user message. Skipping these loses exactly the
+ *  mid-flight corrections and standing conventions a retrospective is for */
+export function queuedPromptOf(entry: RawEntry): string | null {
+    if (entry.type !== 'queue-operation' || entry.operation !== 'enqueue') return null
+    if (typeof entry.content !== 'string') return null
+    const text = stripReminders(entry.content)
+    return isTypedPrompt(text) ? text : null
+}
+
+const BASH_EXIT = /^Exit code (\d+)/
+const BLOCKED = [/^PreToolUse:/, /^Permission to use /, /^Permission for this action was denied/, /auto mode classifier/i, /hook error/i]
+
+/** how a tool call ended. The harness marks every failure `is_error`, and the
+ *  text says which kind: a non zero exit, a hook or permission block, the
+ *  human saying no, a timeout (now moved to the background), anything else */
+export function outcomeOf(r: { isError: boolean; text: string; extra: unknown }): { outcome: Outcome; code: number | null } {
+    const extra = r.extra != null && typeof r.extra === 'object' ? (r.extra as Record<string, unknown>) : {}
+    if (typeof extra.timedOutAfterMs === 'number' || /^Command timed out after/.test(r.text)) return { outcome: 'timeout', code: null }
+    if (extra.interrupted === true || r.text.startsWith('[Request interrupted')) return { outcome: 'interrupted', code: null }
+    if (!r.isError) return { outcome: 'ok', code: null }
+    const exit = BASH_EXIT.exec(r.text)
+    if (exit?.[1] != null) return { outcome: 'exit', code: Number(exit[1]) }
+    if (/^The user doesn't want to proceed/.test(r.text) || /^The user (rejected|denied)/.test(r.text)) return { outcome: 'denied', code: null }
+    if (BLOCKED.some((re) => re.test(r.text))) return { outcome: 'blocked', code: null }
+    return { outcome: 'error', code: null }
+}
+
+const DETAIL_MAX = 400
+const clip = (s: string): string => (s.length > DETAIL_MAX ? s.slice(0, DETAIL_MAX) : s)
+
+/** a long command keeps its head and its tail: what runs after a heredoc
+ *  (`cat > x.ts <<EOF … EOF` then `bun x.ts`) is at the end */
+const clipMiddle = (s: string): string => (s.length > 2 * DETAIL_MAX ? `${s.slice(0, DETAIL_MAX)}\n${s.slice(-DETAIL_MAX)}` : s)
+
+/** the one input field that says what a call did: the Bash command, the
+ *  sub-agent type and its description, the skill, the url */
+export function detailOf(name: string, input: unknown): string {
+    const i = input != null && typeof input === 'object' ? (input as Record<string, unknown>) : {}
+    const str = (k: string): string => (typeof i[k] === 'string' ? (i[k] as string) : '')
+    if (name === 'Bash') return clipMiddle(str('command'))
+    if (name === 'Agent' || name === 'Task') return clip(`${str('subagent_type') || 'general-purpose'}: ${str('description')}`)
+    if (name === 'Skill') return clip(str('skill'))
+    if (name === 'WebFetch') return clip(str('url'))
+    if (name === 'Monitor' || name === 'TaskOutput' || name === 'TaskStop') return clip(str('description') || str('task_id'))
+    return ''
+}
+
+const resultText = (content: unknown): string => {
+    if (typeof content === 'string') return content
+    if (Array.isArray(content)) {
+        const first = (content as Block[]).find((b) => b?.type === 'text' && typeof b.text === 'string')
+        return first == null ? '' : (first.text as string)
+    }
+    return ''
+}
+
+// the entry types that carry nothing a reader wants and make most of the
+// bytes (api-request alone is about 80 percent of a long session): a line
+// that starts with one of these is skipped before JSON.parse
+const KEPT_TYPE_PREFIXES = ['{"type":"user"', '{"type":"assistant"', '{"type":"queue-operation"']
+
+/** every event one transcript line holds; [] for anything else, a truncated
+ *  tail line of a live session included */
+export function readTranscriptLine(line: string): TranscriptEvent[] {
+    if (line.startsWith('{"type":"') && !KEPT_TYPE_PREFIXES.some((p) => line.startsWith(p))) return []
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(line)
+    } catch {
+        return []
+    }
+    if (parsed == null || typeof parsed !== 'object') return []
+    return eventsOf(parsed as RawEntry)
+}
+
+export function eventsOf(entry: RawEntry): TranscriptEvent[] {
+    const timestamp = typeof entry.timestamp === 'string' ? entry.timestamp : ''
+    const at = Date.parse(timestamp)
+    const uuid = typeof entry.uuid === 'string' ? entry.uuid : null
+    const sessionId = typeof entry.sessionId === 'string' ? entry.sessionId : null
+    const prompt = (text: string, origin: PromptOrigin): TranscriptEvent => ({ kind: 'prompt', at, timestamp, uuid, sessionId, text, origin })
+
+    if (entry.type === 'queue-operation') {
+        const q = queuedPromptOf(entry)
+        return q == null ? [] : [prompt(q, 'queued')]
+    }
+    if (Number.isNaN(at) && entry.type !== 'user') return []
+    if (entry.type === 'assistant') {
+        const blocks = Array.isArray(entry.message?.content) ? (entry.message.content as Block[]) : []
+        const out: TranscriptEvent[] = []
+        for (const b of blocks) {
+            if (b?.type === 'tool_use' && typeof b.id === 'string' && typeof b.name === 'string') out.push({ kind: 'use', at, id: b.id, name: b.name, detail: detailOf(b.name, b.input) })
+            else if (b?.type === 'text') out.push({ kind: 'reply', at })
+        }
+        return out
+    }
+    if (entry.type !== 'user') return []
+    const out: TranscriptEvent[] = []
+    const content = entry.message?.content
+    if (Array.isArray(content)) {
+        const perm = permOf(entry.permissionDecision)
+        for (const b of content as Block[]) {
+            if (b?.type !== 'tool_result' || typeof b.tool_use_id !== 'string' || Number.isNaN(at)) continue
+            const o = outcomeOf({ isError: b.is_error === true, text: resultText(b.content), extra: entry.toolUseResult })
+            out.push({ kind: 'result', at, id: b.tool_use_id, ...o, perm })
+        }
+    }
+    const typed = typedPromptOf(entry)
+    if (typed != null) out.push(prompt(typed, 'typed'))
+    else if (out.length === 0 && !Number.isNaN(at) && entry.isMeta === true && RELAYED.test(userText(entry) ?? '')) out.push({ kind: 'message', at })
+    // a peer message (a sub-agent hand-back, another session's message) is written isMeta, yet it wakes the agent
+    else if (out.length === 0 && !Number.isNaN(at) && (entry.isMeta !== true || entry.turnOrigin === 'peer') && entry.isCompactSummary !== true) {
+        const text = userText(entry)
+        if (text != null && text !== '') out.push({ kind: 'wake', at })
+    }
+    return out
+}