rvlib-shipkit 2.2.0 → 2.4.0

package/src/cli/cmd_Review.ts

@@ -0,0 +1,974 @@
+// sk review: an agent shows the owner something as one card of the one store and reads his answer; a dispatcher routes
+// what he, a player or a rule raised, a worker claims and closes it (review/store.ts, wiki build/shipkit/review.md).
+// Every module loads inside execute: the cli registers this file on every `sk` call
+import { Command, Option } from 'clipanion'
+
+const DETAILS = `the one feedback store, .shipkit/review/<id>/: one subject is one card (other angles are views of it, a follow up --supersedes it), he answers it in the hub's review entry (approved, ok with a fix, rejected, archived, rectangles, reactions per view), you read his answer with inbox or watch. What he, a player or a rule raises is an item of the same store: a dispatcher routes it to a topic, a worker claims it and closes it. The repo's review unit names its kinds, topics, sources and rules. SK_AGENT names your lane. Page: wiki build/shipkit/review.md`
+
+type Ctx = { stdout: NodeJS.WritableStream; stderr: NodeJS.WritableStream }
+type Unit = import('../review/unit.ts').ReviewUnit
+type Say = import('../review/format.ts').Say
+
+/** what a verb works on: the store, its repo's unit (null when the verb reads no unit, or the repo has none), and how the unit's lines print */
+interface Here {
+    dir: string
+    unit: Unit | null
+    say: Say
+    out: (l: string) => void
+    err: (l: string) => void
+}
+
+/** the store of the repo this runs in, its unit read when the verb needs it, and the body; a refusal is one FAIL line with its reason, exit 1 */
+async function run(context: Ctx, body: (h: Here) => Promise<number> | number, o: { unit?: boolean } = {}): Promise<number> {
+    const { findRepoRoot } = await import('../ts/config.ts')
+    const out = (l: string): void => void context.stdout.write(`${l}\n`)
+    const err = (l: string): void => void context.stderr.write(`${l}\n`)
+    try {
+        const root = findRepoRoot(process.cwd())
+        if (o.unit === false) {
+            const { storeDir } = await import('../review/store.ts')
+            return await body({ dir: storeDir(root), unit: null, say: { spec: (await import('../review/model.ts')).NO_SPEC, more: () => [] }, out, err })
+        }
+        const { openReview, factLines } = await import('../review/project.ts')
+        const { specOf } = await import('../review/store.ts')
+        const { dir, unit } = await openReview(root)
+        return await body({ dir, unit, say: { spec: specOf(dir), more: (x) => factLines(unit, x) }, out, err })
+    } catch (e) {
+        err(`FAIL: review: ${e instanceof Error ? e.message : String(e)}`)
+        return 1
+    }
+}
+
+const isHelp = (a: string): boolean => a === '--help' || a === '-h'
+
+/** the agent that acts: --as, else SK_AGENT; `need` refuses an unnamed one */
+function actor(as: string | undefined, need: boolean, verb: string): string {
+    const n = as?.trim() || process.env.SK_AGENT?.trim()
+    if (n === 'owner') throw new Error('the owner acts from the hub, not from here')
+    if (n) return n
+    if (need) throw new Error(`${verb} needs --as <name> (or SK_AGENT)`)
+    return 'agent'
+}
+
+/** an item id or a player report's ref (`live#3`) to its item id */
+async function idOf(dir: string, ref: string): Promise<string> {
+    const { itemOfRef } = await import('../review/store.ts')
+    const x = itemOfRef(dir, ref)
+    if (!x) throw new Error(`no item ${ref}`)
+    return x.item.id
+}
+
+/** the sources pulled before a read: a line per source down, said once a process */
+const downSaid = new Set<string>()
+async function pull(h: Here): Promise<void> {
+    if (!h.unit?.sources?.length) return
+    const { pullSources } = await import('../review/project.ts')
+    const now = new Set<string>()
+    const got = await pullSources(h.dir, h.unit, (l) => {
+        now.add(l)
+        if (!downSaid.has(l)) h.err(l)
+    })
+    downSaid.clear()
+    for (const l of now) downSaid.add(l)
+    if (got.length > 0) h.err(`review: ${got.length} new items pulled`)
+}
+
+/** a gallery tile as given: `<label>=<file>`, or a file labelled by its name */
+function tileOf(arg: string): { file: string; label: string } {
+    const eq = arg.lastIndexOf('=')
+    if (eq > 0) return { label: arg.slice(0, eq), file: arg.slice(eq + 1) }
+    const name = arg.split('/').pop() ?? arg
+    return { file: arg, label: name.replace(/\.[a-z0-9]+$/i, '') }
+}
+
+type ViewInput = import('../review/store.ts').ViewInput
+
+/** `--view "<label>" a.png [b.png] [--note "<text>"]` and `--gallery "<label>" a.png b.png …` out of the args */
+function takeViews(args: readonly string[]): { views: ViewInput[]; rest: string[] } {
+    const views: ViewInput[] = []
+    const rest: string[] = []
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] ?? ''
+        if (a !== '--gallery' && a !== '--view') {
+            rest.push(a)
+            continue
+        }
+        const label = args[i + 1]
+        const files: string[] = []
+        for (let j = i + 2; j < args.length && (a === '--gallery' || files.length < 2) && !(args[j] ?? '').startsWith('--'); j++) files.push(args[j] ?? '')
+        if (label === undefined || label.startsWith('--') || files.length === 0) throw new Error(a === '--gallery' ? '--gallery "<label>" a.png b.png …: a label, then its images' : '--view "<label>" a.png [b.png]: a label, then an image or a before and an after')
+        if (a === '--gallery') views.push({ label, gallery: files.map(tileOf) })
+        else views.push(files.length === 1 ? { label, image: files[0] } : { label, before: files[0], after: files[1] })
+        i += 1 + files.length
+        if (args[i + 1] === '--note') {
+            const note = args[i + 2]
+            if (note === undefined || note.startsWith('--')) throw new Error(`--view "${label}" … --note "<text>": a line on that view`)
+            const v = views[views.length - 1]
+            if (v) v.note = note
+            i += 2
+        }
+    }
+    return { views, rest }
+}
+
+/** the flags of `add`, parsed by name: a value flag repeats where it says so */
+function flagsOf(args: readonly string[], values: readonly string[], repeat: readonly string[], bools: readonly string[]): { one: Record<string, string>; many: Record<string, string[]>; on: Set<string>; positionals: string[] } {
+    const one: Record<string, string> = {}
+    const many: Record<string, string[]> = {}
+    const on = new Set<string>()
+    const positionals: string[] = []
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] ?? ''
+        if (!a.startsWith('--')) {
+            positionals.push(a)
+            continue
+        }
+        const name = a.slice(2)
+        if (bools.includes(name)) {
+            on.add(name)
+            continue
+        }
+        if (!values.includes(name) && !repeat.includes(name)) throw new Error(`${a}: no such flag (sk review add --help)`)
+        const v = args[i + 1]
+        if (v === undefined) throw new Error(`${a}: needs a value`)
+        i++
+        if (repeat.includes(name)) (many[name] ??= []).push(v)
+        else one[name] = v
+    }
+    return { one, many, on, positionals }
+}
+
+const ADD_FLAGS = `flags:
+  --title "<title>"                   one short line: what he looks at
+  --what "<what>"                     what changed and why, short markdown: one line, then - bullets
+  --image <a.png>                     the subject; a clip (webm, mp4) goes anywhere an image goes
+  --video <clip.mp4>                  a clip
+  --audio <sound.wav>                 a sound: a waveform and a player (wav, mp3, flac, ogg, opus, m4a)
+  --before <a.png> --after <b.png>    a before and after: two images, two clips of one size, or two sounds
+  --label "<label>"                   the first view's label
+  --view "<label>" <a.png> [<b.png>]  another view of the same subject (repeat it); --note "<text>" right after it: a line on that view
+  --choice                            every view is an option he scores and picks one of (two --view or more)
+  --gallery "<label>" <a.png> …       a grid of small images; "<tile label>=<c.png>" names a tile (repeat it)
+  --topic <topic>                     what part of the project it is about (sk review topics)
+  --subject <kind>                    what is judged (default shot; the repo's unit names its kinds)
+  --commit <sha>                      the commit it shows
+  --lane <id>                         the lane that made it; else SK_AGENT
+  --supersedes <id>                   the card it follows up, after his answer
+  --answers <id | live#3>             the item it answers (a note he raised, a player's report), one thread (repeat it)
+  --keeps "<what stays>"              with --supersedes on an approved look: what of it stays
+  --new --why "<reason>"              a new card beside an active one of the same subject`
+
+/** the help of add or add-view, then the flags this repo's review unit adds (any kind's, then each kind's under
+ *  `--subject <kind>`); a repo with no unit, or one that does not load, says so on one line */
+async function helpWithUnit(context: Ctx, usage: string, kinds: boolean): Promise<number> {
+    context.stdout.write(usage)
+    await run(context, (h) => {
+        const lines = Object.entries(h.unit?.flags ?? {}).map(([k, d]) => `  --${k} ${d}`)
+        if (kinds) for (const [name, k] of Object.entries(h.unit?.kinds ?? {})) for (const [f, d] of Object.entries(k.flags ?? {})) lines.push(`  --${f} ${d} (with --subject ${name})`)
+        h.out(lines.length > 0 ? `\nthis repo's review unit adds:\n${lines.join('\n')}` : "\nthis repo's review unit adds no flags")
+        return 0
+    })
+    return 0
+}
+
+export class ReviewAddCommand extends Command {
+    static override paths = [['review', 'add']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: 'show the owner a change as one card he answers in the hub: an image, a clip, a pair, views',
+        details: `${DETAILS}\n\n${ADD_FLAGS}`,
+        examples: [
+            ['one image', 'sk review add --title "the new menu" --what "the menu, bigger" --image shots/menu.png'],
+            ['a before and after', 'sk review add --title "lamps lit" --what "..." --before a.png --after b.png'],
+            ['a second version after his answer', 'sk review add --title "lamps lit" --what "..." --image c.png --supersedes <id>'],
+            ['a pick among three voices', 'sk review add --choice --title "the narrator" --what "..." --view "voice 0" a.flac --note "low, breathy" --view "voice 1" b.flac --view "voice 2" c.flac'],
+        ],
+    })
+    args = Option.Proxy()
+
+    async execute(): Promise<number> {
+        if (this.args.some(isHelp)) {
+            return helpWithUnit(this.context, this.cli.usage(ReviewAddCommand, { detailed: true }), true)
+        }
+        return run(this.context, async (h) => {
+            const { addItem } = await import('../review/store.ts')
+            const { views, rest } = takeViews(this.args)
+            // the repo's own flags: the subject kind's (--where), and the unit's for any kind (--mark), each repeatable
+            const kindName = rest[rest.indexOf('--subject') + 1]
+            const kind = rest.includes('--subject') && kindName ? h.unit?.kinds?.[kindName] : undefined
+            const own = [...Object.keys(kind?.flags ?? {}), ...Object.keys(h.unit?.flags ?? {})]
+            const f = flagsOf(rest, ['title', 'what', 'image', 'video', 'audio', 'before', 'after', 'label', 'topic', 'subject', 'commit', 'lane', 'supersedes', 'keeps', 'why', 'live'], ['answers', ...own], ['new', 'wip', 'choice'])
+            if (f.positionals.length > 0) throw new Error(`unexpected ${f.positionals.join(' ')}`)
+            const o = f.one
+            const repoFlags = Object.fromEntries(own.flatMap((k) => (f.many[k] ? [[k, f.many[k]]] : [])))
+            const parsed = kind?.parse ? kind.parse(Object.fromEntries(Object.keys(kind.flags ?? {}).map((k) => [k, f.many[k] ?? []]))) : null
+            if (f.on.has('wip') !== (o.live !== undefined)) throw new Error('--wip --live <name>: a draft card names its live shot, and a live shot makes a draft card')
+            let wipViews: ViewInput[] = []
+            if (o.live !== undefined) {
+                if (!h.unit?.live) throw new Error("--live: the repo's review unit declares no live shots (live: { frames })")
+                if (o.image || o.video || o.audio || o.before || o.after || views.length > 0) throw new Error('--wip: the card shows the live shot alone, no --image, --video, pair or --view beside it')
+                const fr = h.unit.live.frames(o.live)
+                wipViews = [{ label: '', image: fr.image }, ...(fr.history.length > 0 ? [{ label: 'history', gallery: fr.history }] : [])]
+            }
+            const answers = await Promise.all((f.many.answers ?? []).map((a) => idOf(h.dir, a)))
+            const topic = o.topic ?? parsed?.topic
+            let input: import('../review/store.ts').AddInput = {
+                title: o.title ?? '',
+                what: o.what ?? '',
+                ...(parsed ? { subject: parsed.subject } : o.subject ? { subject: { kind: o.subject } } : {}),
+                ...(topic ? { topic } : {}),
+                ...(o.image ? { image: o.image } : {}),
+                ...(o.video ? { video: o.video } : {}),
+                ...(o.audio ? { audio: o.audio } : {}),
+                ...(o.before ? { before: o.before } : {}),
+                ...(o.after ? { after: o.after } : {}),
+                ...(o.label ? { label: o.label } : {}),
+                ...(o.commit ? { commit: o.commit } : {}),
+                ...(o.lane ? { lane: o.lane } : {}),
+                ...(o.supersedes ? { supersedes: o.supersedes } : {}),
+                ...(o.keeps ? { keeps: o.keeps } : {}),
+                ...(o.why ? { why: o.why } : {}),
+                ...(answers.length > 0 ? { answers } : {}),
+                ...(f.on.has('new') ? { fresh: true } : {}),
+                ...(f.on.has('choice') ? { choice: true } : {}),
+                ...(o.live !== undefined ? { image: wipViews[0]?.image ?? '', views: wipViews.slice(1), wip: { live: o.live } } : { views }),
+            }
+            if (h.unit?.add) input = await h.unit.add(input, repoFlags)
+            const item = await addItem(h.dir, input)
+            h.out(item.id)
+            if (item.origin.by === 'agent' && !item.origin.lane) h.err('no lane on the card: pass --lane <id> (or SK_AGENT), so the hub colours it')
+            return 0
+        })
+    }
+}
+
+export class ReviewAddViewCommand extends Command {
+    static override paths = [['review', 'add-view']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: 'another angle on a card he has not answered yet: an image, a pair, a clip or a gallery',
+        details: `${DETAILS}\n\nsk review add-view <id> "<label>" <a.png> [<b.png>] | --video <clip.mp4> | --audio <sound.wav> | --gallery <a.png> <b.png> … [--note "<a line on that view>"]`,
+        examples: [['a view from above', 'sk review add-view <id> "from above" top.png']],
+    })
+    args = Option.Proxy()
+
+    async execute(): Promise<number> {
+        if (this.args.some(isHelp)) {
+            return helpWithUnit(this.context, this.cli.usage(ReviewAddViewCommand, { detailed: true }), false)
+        }
+        return run(this.context, async (h) => {
+            const { addView } = await import('../review/store.ts')
+            const own = Object.keys(h.unit?.flags ?? {})
+            const repoFlags: Record<string, string[]> = {}
+            const args: string[] = []
+            let note: string | undefined
+            for (let i = 0; i < this.args.length; i++) {
+                const a = this.args[i] ?? ''
+                const name = a.startsWith('--') ? a.slice(2) : ''
+                if (own.includes(name)) (repoFlags[name] ??= []).push(this.args[++i] ?? '')
+                else if (name === 'note') note = this.args[++i]
+                else args.push(a)
+            }
+            if (this.args.includes('--note') && (note === undefined || note.startsWith('--'))) throw new Error('--note "<text>": a line on that view')
+            const [id, label, ...rest] = args
+            if (!id || !label) throw new Error('add-view <id> "<label>" <media>')
+            const v: ViewInput =
+                rest[0] === '--video' && rest[1]
+                    ? { label, video: rest[1] }
+                    : rest[0] === '--audio' && rest[1]
+                      ? { label, audio: rest[1] }
+                    : rest[0] === '--gallery'
+                      ? { label, gallery: rest.slice(1).map(tileOf) }
+                      : rest.length === 1
+                        ? { label, image: rest[0] }
+                        : rest.length === 2
+                          ? { label, before: rest[0], after: rest[1] }
+                          : (() => {
+                                throw new Error('add-view <id> "<label>" <a.png> [<b.png>] | --video <clip> | --gallery <a.png> …')
+                            })()
+            if (note !== undefined) v.note = note
+            const extra = h.unit?.addView ? await h.unit.addView(v, repoFlags) : {}
+            const item = await addView(h.dir, id, v, extra)
+            h.out(`${id}: view ${item.views.length} "${label}" added`)
+            return 0
+        })
+    }
+}
+
+export class ReviewLsCommand extends Command {
+    static override paths = [['review'], ['review', 'ls']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: "the store's active threads, one line each: status, id, title; `sk review <verb>` runs a unit's verb",
+        details: `${DETAILS}\n\nsk review [--all] lists; sk review <verb> … runs a verb the repo's review unit declares (verbs: {...}).`,
+        examples: [['what is open', 'sk review ls'], ['every thread', 'sk review ls --all']],
+    })
+    args = Option.Proxy()
+
+    async execute(): Promise<number> {
+        const [verb, ...rest] = this.args
+        if (verb !== undefined && isHelp(verb)) {
+            this.context.stdout.write(this.cli.usage(ReviewLsCommand, { detailed: true }))
+            return 0
+        }
+        // a word that is no flag is a verb of the repo's review unit: a report replayed, the town composer
+        if (verb !== undefined && !verb.startsWith('--'))
+            return run(this.context, async (h) => {
+                const verbs = h.unit?.verbs ?? {}
+                const v = verbs[verb]
+                if (!v) throw new Error(`no verb « ${verb} »: sk review --help lists sk's own; the repo's unit declares ${Object.keys(verbs).join(', ') || 'none'}`)
+                const { dirname } = await import('node:path')
+                return v.run(rest, { dir: h.dir, root: dirname(dirname(h.dir)), say: h.out, err: h.err })
+            })
+        const every = rest.length === 0 && verb === '--all'
+        if (verb !== undefined && !every) {
+            this.context.stderr.write(`FAIL: review: unexpected ${this.args.join(' ')} (sk review --help)\n`)
+            return 1
+        }
+        // the listing reads no unit: it stays the fast answer, and the unit's refusals show in inbox and the hub
+        return run(
+            this.context,
+            async (h) => {
+                const { readAll } = await import('../review/store.ts')
+                const { isActive, orderedThreads, statusOf } = await import('../review/threads.ts')
+                const all = readAll(h.dir)
+                for (const b of all.broken) h.err(`review: FAIL ${b.id}: ${b.error}`)
+                const threads = orderedThreads(all.items).filter((t) => every || isActive(t))
+                if (threads.length === 0) h.out(every ? 'review: the store is empty' : 'review: nothing active (--all shows every thread)')
+                for (const t of threads) h.out(`${statusOf(t.head, all.items).padEnd(17)} ${t.head.item.id}  ${t.head.item.title}${t.versions.length > 1 ? ` (v${t.versions.length})` : ''}`)
+                return all.broken.length > 0 ? 1 : 0
+            },
+            { unit: false },
+        )
+    }
+}
+
+export class ReviewShowCommand extends Command {
+    static override paths = [['review', 'show']]
+    static override usage = Command.Usage({ category: 'Review', description: 'one item and its thread: the verdict, rectangles, reactions, the whole conversation', details: `${DETAILS}\n\nTakes an item id or a player report's ref (live#3).` })
+    id = Option.String()
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { readAllCached } = await import('../review/store.ts')
+            const { threadDetail, detail } = await import('../review/format.ts')
+            const { threadOfItem, threadsOf } = await import('../review/threads.ts')
+            const id = await idOf(h.dir, this.id)
+            const all = readAllCached(h.dir)
+            const x = all.items.find((y) => y.item.id === id)
+            if (!x) throw new Error(`no item ${this.id}`)
+            const t = threadOfItem(x.item.id, threadsOf(all.items))
+            h.out(t && (t.head.item.id === x.item.id || t.answers.length > 0) ? threadDetail(t, h.dir, true, h.say) : detail(x, h.dir, true, false, h.say))
+            return 0
+        })
+    }
+}
+
+/** --mine or --session <id>: only the cards that session opened; null keeps every item */
+async function sessionOf(mine: boolean, session: string | undefined): Promise<string | null> {
+    if (session !== undefined) return session
+    if (!mine) return null
+    const { sessionId } = await import('../review/store.ts')
+    const s = sessionId()
+    if (s === null) throw new Error('--mine: no Claude Code session here (CLAUDE_CODE_SESSION_ID): --session <id>')
+    return s
+}
+
+export class ReviewInboxCommand extends Command {
+    static override paths = [['review', 'inbox']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: 'every answer not marked seen and every open item he raised, frame notes included',
+        details: DETAILS,
+        examples: [['what waits on you', 'sk review inbox'], ['his notes on trailer frames', 'sk review inbox --subject frame'], ['the cards this session sent', 'sk review inbox --mine']],
+    })
+    mine = Option.Boolean('--mine', false, { description: "only this Claude Code session's cards" })
+    session = Option.String('--session', { description: "only that session's cards" })
+    subject = Option.String('--subject', { description: 'only items of this subject kind (frame, shot…)' })
+    all = Option.Boolean('--all', false, { description: 'a plain approval too, not only the counted line' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { liveWatchers } = await import('../review/watchers.ts')
+            const { readAll } = await import('../review/store.ts')
+            const { BUILTIN_KINDS, coversCard, moveOf, stateOf, unreadBy, untakenOf, verdictOf } = await import('../review/model.ts')
+            const { followedIds, threadOfItem, threadsOf, unseen } = await import('../review/threads.ts')
+            const { detail, threadDetail, untakenLine } = await import('../review/format.ts')
+            const kinds = [...Object.keys(h.say.spec.kinds), ...Object.keys(BUILTIN_KINDS)]
+            if (this.subject !== undefined && Object.keys(h.say.spec.kinds).length > 0 && !kinds.includes(this.subject)) throw new Error(`--subject: one of ${kinds.join(', ')}`)
+            const session = await sessionOf(this.mine, this.session)
+            await pull(h)
+            const all = readAll(h.dir)
+            for (const b of all.broken) h.err(`review: FAIL ${b.id}: ${b.error}`)
+            const of = (x: (typeof all.items)[number]): boolean => coversCard({ session, lane: null }, x) && (this.subject === undefined || x.item.subject.kind === this.subject)
+            const news = unseen(all.items).filter(of)
+            const followed = followedIds(all.items)
+            // what he or a player raised and nobody closed is the agents' move, read or not
+            const open = all.items.filter((x) => of(x) && x.item.origin.by !== 'agent' && moveOf(stateOf(x, followed.has(x.item.id)).state) === 'agents' && !news.includes(x))
+            // a plain approval (no comment, no rectangle, no reaction, no pick, no reply) asks for no work: counted on one
+            // line unless --all
+            const plain = (x: (typeof news)[number]): boolean => {
+                const v = verdictOf(x)
+                return v?.status === 'approved' && !v.seen && !v.comment && v.rects.length === 0 && !v.reactions && v.pick === undefined && unreadBy(x, 'agent').length === 0
+            }
+            const shown = [...(this.all ? news : news.filter((x) => !plain(x))), ...open]
+            if (shown.length === 0 && news.length === 0) h.out('review: no unseen feedback or reply')
+            const threads = threadsOf(all.items)
+            const printed = new Set<string>()
+            for (const x of shown) {
+                const t = threadOfItem(x.item.id, threads)
+                if (t && printed.has(t.head.item.id)) continue
+                if (t) printed.add(t.head.item.id)
+                h.out(`${t ? threadDetail(t, h.dir, false, h.say) : detail(x, h.dir, false, false, h.say)}\n`)
+            }
+            const watchers = liveWatchers(h.dir)
+            const untaken = all.items.flatMap((x) => {
+                const why = untakenOf(x, followed.has(x.item.id), watchers, new Date(), h.say.spec.dispatcher)
+                return why === null ? [] : [untakenLine(x, why, null)]
+            })
+            if (untaken.length > 0) h.out(`not taken:\n${untaken.join('\n')}\n`)
+            const approvals = this.all ? [] : news.filter(plain)
+            if (approvals.length > 0) h.out(`review: ${approvals.length} plain approval(s), nothing to do: sk review seen ${approvals.map((x) => x.item.id).join(' ')}`)
+            if (shown.length > 0) h.out('mark each handled: sk review seen <id>; close a raised one: sk review fixed <id> --note "<what was done>"')
+            return all.broken.length > 0 ? 1 : 0
+        })
+    }
+}
+
+export class ReviewSeenCommand extends Command {
+    static override paths = [['review', 'seen']]
+    static override usage = Command.Usage({ category: 'Review', description: 'mark his answers and replies on these items read, once you acted on them', details: DETAILS })
+    ids = Option.Rest({ required: 1 })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { markSeen } = await import('../review/store.ts')
+            let bad = 0
+            for (const ref of this.ids) {
+                const id = await idOf(h.dir, ref).catch(() => ref)
+                if (markSeen(h.dir, id)) h.out(`${ref}: seen`)
+                else {
+                    h.err(`FAIL: review: ${ref}: no such item, or nothing of his to read on it`)
+                    bad++
+                }
+            }
+            return bad > 0 ? 1 : 0
+        })
+    }
+}
+
+export class ReviewReplyCommand extends Command {
+    static override paths = [['review', 'reply']]
+    static override usage = Command.Usage({ category: 'Review', description: "your message on a card's thread: what you changed, the answer to his question", details: DETAILS })
+    id = Option.String()
+    text = Option.String()
+    image = Option.String('--image', { description: 'an image beside the words' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { addMessage, agentName } = await import('../review/store.ts')
+            const id = await idOf(h.dir, this.id)
+            const m = addMessage(h.dir, id, agentName(), this.text, this.image)
+            h.out(`${id}: ${m.id}`)
+            return 0
+        })
+    }
+}
+
+export class ReviewWithdrawCommand extends Command {
+    static override paths = [['review', 'withdraw']]
+    static override usage = Command.Usage({ category: 'Review', description: 'take an unanswered card back, with the reason', details: DETAILS })
+    ids = Option.Rest({ required: 1 })
+    why = Option.String('--why', { required: true, description: 'why it goes' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { withdraw } = await import('../review/store.ts')
+            for (const id of this.ids) if (!withdraw(h.dir, id, this.why)) throw new Error(`${id}: no such card, or he answered it already`)
+            h.out(`review: ${this.ids.length} withdrawn`)
+            return 0
+        })
+    }
+}
+
+export class ReviewReopenCommand extends Command {
+    static override paths = [['review', 'reopen']]
+    static override usage = Command.Usage({ category: 'Review', description: 'an answered card waits for his answer again; the old verdict stays in the thread', details: DETAILS })
+    ids = Option.Rest({ required: 1 })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { reopen } = await import('../review/store.ts')
+            for (const id of this.ids) if (!reopen(h.dir, id)) throw new Error(`${id}: no such card, or no answer to reopen`)
+            h.out(`review: ${this.ids.length} reopened`)
+            return 0
+        })
+    }
+}
+
+type ActOp = 'fixed' | 'wontfix' | 'claim' | 'release' | 'blocked' | 'done' | 'dispatch' | 'ask' | 'drop' | 'reassign'
+
+/** one state change: by a worker on its claim, or by the dispatcher on what it routes; the item, then the new state */
+function actCommand(op: ActOp, description: string, o: { note?: 'required' | 'optional'; text?: string; topic?: 'required' | 'optional'; named: boolean; examples: [string, string][] }) {
+    return class extends Command {
+        static override paths = [['review', op]]
+        static override usage = Command.Usage({ category: 'Review', description, details: `${DETAILS}\n\nTakes an item id or a player report's ref (live#3). ${o.named ? 'Who acts: --as <name>, else SK_AGENT.' : 'Who acts: --as, else SK_AGENT, else agent.'}`, examples: o.examples })
+        id = Option.String()
+        words = o.text !== undefined || o.topic !== undefined ? Option.String({ required: false, name: o.text ?? 'topic' }) : undefined
+        note = o.note === 'required' ? Option.String('--note', { required: true, description: 'what was done, why not, or what is needed' }) : Option.String('--note', { description: 'what was done, or the reason' })
+        commit = Option.String('--commit', { description: 'the commit that holds the fix' })
+        as = Option.String('--as', { description: 'who acts (else SK_AGENT)' })
+
+        async execute(): Promise<number> {
+            return run(this.context, async (h) => {
+                const { act, readItem } = await import('../review/store.ts')
+                const { stateOf } = await import('../review/model.ts')
+                const { detail } = await import('../review/format.ts')
+                if (this.words !== undefined && o.text === undefined && o.topic === undefined) throw new Error(`unexpected ${this.words}`)
+                if (o.text && !this.words?.trim()) throw new Error(`${op} <id> "<${o.text}>"`)
+                if (o.topic === 'required' && !this.words) throw new Error(`${op} <id> <topic> (sk review topics)`)
+                const id = await idOf(h.dir, this.id)
+                const who = actor(this.as, o.named, op)
+                act(h.dir, id, op, who, {
+                    ...(this.note ? { note: this.note } : {}),
+                    ...(op === 'ask' && this.words ? { text: this.words } : {}),
+                    ...(op === 'done' && this.words ? { note: this.words } : {}),
+                    ...(o.topic && this.words ? { topic: this.words } : {}),
+                    ...(this.commit ? { commit: this.commit } : {}),
+                })
+                const x = readItem(h.dir, id)
+                const st = x ? stateOf(x, false) : null
+                h.out(`${id} ${op}: ${st ? `${st.state}${st.why ? ` (${st.why})` : ''}${st.topic ? ` ${st.topic}` : ''}${st.worker ? ` ${st.worker}` : ''}` : 'gone'}`)
+                if (op === 'claim' && x) h.out(detail(x, h.dir, false, false, h.say))
+                return 0
+            })
+        }
+    }
+}
+
+export const ReviewFixedCommand = actCommand('fixed', 'close an item he raised as done: the note says what was done (and --commit where)', { note: 'optional', named: false, examples: [['done, with its commit', 'sk review fixed <id> --note "the lamp lit" --commit abc1234']] })
+export const ReviewWontfixCommand = actCommand('wontfix', 'close an item he raised as not done, with the reason', { note: 'required', named: false, examples: [['not done', 'sk review wontfix <id> --note "the room is gone"']] })
+export const ReviewClaimCommand = actCommand('claim', 'take an item to work on it: the hub shows the card in work by your lane', { named: true, examples: [['take it', 'sk review claim <id> --as L12']] })
+export const ReviewReleaseCommand = actCommand('release', 'give back an item you claimed', { note: 'optional', named: true, examples: [['give it back', 'sk review release <id> --as L12']] })
+export const ReviewBlockedCommand = actCommand('blocked', 'an item you claimed goes back to the owner with what is needed', { note: 'required', named: true, examples: [['his decision is needed', 'sk review blocked <id> --note "which of the two doors?" --as L12']] })
+export const ReviewDoneCommand = actCommand('done', 'an « ok with a fix » card made with no new card: closed, the words say what changed', { text: 'what changed', named: false, examples: [['the fix made', 'sk review done <id> "the sign moved one tile up"']] })
+export const ReviewDispatchCommand = actCommand('dispatch', 'the dispatcher sends a raised item to a topic', { note: 'optional', topic: 'required', named: true, examples: [['to a topic', 'sk review dispatch <id> lieux --as orchestrator']] })
+export const ReviewAskCommand = actCommand('ask', 'the dispatcher asks the owner a question on a raised item; his reply answers it', { text: 'question', named: true, examples: [['a question', 'sk review ask <id> "which tower?" --as orchestrator']] })
+export const ReviewDropCommand = actCommand('drop', 'the dispatcher closes a raised item with the reason (a duplicate, already fixed)', { note: 'required', named: true, examples: [['a duplicate', 'sk review drop <id> --note "same as <other id>" --as orchestrator']] })
+export const ReviewReassignCommand = actCommand('reassign', 'the dispatcher takes a claim back, or sends the item to another topic', { note: 'optional', topic: 'optional', named: true, examples: [['a stale claim', 'sk review reassign <id> --as orchestrator']] })
+
+export class ReviewDispatcherCommand extends Command {
+    static override paths = [['review', 'dispatcher']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: 'take the dispatcher role: one session at a time routes what is raised',
+        details: `${DETAILS}\n\nRefused while another holder acted in the last 30 minutes, unless --take. Only in a repo whose review unit declares a dispatcher.`,
+        examples: [['take the role', 'sk review dispatcher --as orchestrator']],
+    })
+    as = Option.String('--as', { description: 'who takes it (else SK_AGENT)' })
+    take = Option.Boolean('--take', false, { description: 'take it from an active holder' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            if (!h.say.spec.dispatcher) throw new Error('this repo routes nothing: its review unit declares no dispatcher (dispatcher: true)')
+            const { takeRole } = await import('../review/role.ts')
+            const name = actor(this.as, true, 'dispatcher')
+            const r = takeRole(h.dir, name, this.take)
+            if (!r.ok) throw new Error(r.why)
+            h.out(`${name} holds the dispatcher role${r.was && r.was.name !== name ? ` (taken from ${r.was.name})` : ''}`)
+            return 0
+        })
+    }
+}
+
+export class ReviewNextCommand extends Command {
+    static override paths = [['review', 'next']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: 'claim the oldest open item of a topic, or raised to a lane, and show it with the pages to read first',
+        details: DETAILS,
+        examples: [['the next of a topic', 'sk review next lieux --as L12'], ['the next raised to a lane', 'sk review next --lane interaction --as interaction']],
+    })
+    topic = Option.String({ required: false })
+    lane = Option.String('--lane', { description: 'the lane he or a rule raised it to' })
+    as = Option.String('--as', { description: 'who claims (else SK_AGENT)' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { claimNext } = await import('../review/store.ts')
+            const { stateOf } = await import('../review/model.ts')
+            const { detail } = await import('../review/format.ts')
+            const lane = this.lane?.trim()
+            if (!lane && !this.topic) throw new Error(`next <topic> | next --lane <lane>${Object.keys(h.say.spec.topics).length ? ` (topics: ${Object.keys(h.say.spec.topics).join(', ')})` : ''}`)
+            if (this.topic && Object.keys(h.say.spec.topics).length > 0 && !h.say.spec.topics[this.topic]) throw new Error(`no topic « ${this.topic} »: ${Object.keys(h.say.spec.topics).join(', ')}`)
+            await pull(h)
+            const got = claimNext(h.dir, lane ? { lane } : { topic: this.topic ?? '' }, actor(this.as, true, 'next'))
+            if (!got) {
+                h.out(`nothing open on ${lane ?? this.topic}`)
+                return 0
+            }
+            const topic = stateOf(got, false).topic
+            const read = topic ? h.say.spec.topics[topic]?.read : undefined
+            h.out(`${detail(got, h.dir, false, false, h.say)}${read?.length ? `\nread first: ${read.join(', ')}` : ''}`)
+            return 0
+        })
+    }
+}
+
+export class ReviewTopicsCommand extends Command {
+    static override paths = [['review', 'topics']]
+    static override usage = Command.Usage({ category: 'Review', description: 'the topics a raised item is routed to, and the pages a worker reads first', details: DETAILS })
+
+    async execute(): Promise<number> {
+        return run(this.context, (h) => {
+            const t = Object.entries(h.say.spec.topics)
+            if (t.length === 0) h.out('no topic: the repo\'s review unit declares none (topics: {...})')
+            for (const [id, v] of t) h.out(`${id.padEnd(11)} ${v.label}${v.covers ? `: ${v.covers}` : ''}${v.read?.length ? `\n${' '.repeat(12)}read: ${v.read.join(', ')}` : ''}`)
+            return 0
+        })
+    }
+}
+
+export class ReviewBoardCommand extends Command {
+    static override paths = [['review', 'board']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: 'every open raised item by state, topic and worker, stale claims marked; who is the dispatcher',
+        details: DETAILS,
+        examples: [['what is open', 'sk review board'], ['one topic, closed ones too', 'sk review board --topic lieux --all']],
+    })
+    topic = Option.String('--topic', { description: 'one topic' })
+    all = Option.Boolean('--all', false, { description: 'the closed ones too' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { readAll } = await import('../review/store.ts')
+            const { roleOf } = await import('../review/role.ts')
+            const { isMarkItem, isStale, stateOf } = await import('../review/model.ts')
+            const { followedIds } = await import('../review/threads.ts')
+            if (this.topic && Object.keys(h.say.spec.topics).length > 0 && !h.say.spec.topics[this.topic]) throw new Error(`--topic: one of ${Object.keys(h.say.spec.topics).join(', ')}`)
+            await pull(h)
+            const all = readAll(h.dir)
+            for (const b of all.broken) h.err(`review: FAIL ${b.id}: ${b.error}`)
+            if (h.say.spec.dispatcher) {
+                const role = roleOf(h.dir)
+                h.out(role ? `dispatcher: ${role.name} (since ${role.since.slice(0, 16)})` : 'dispatcher: nobody (sk review dispatcher --as <name>)')
+            }
+            const now = new Date()
+            const followed = followedIds(all.items)
+            const rows = all.items
+                .filter((x) => x.item.origin.by !== 'agent' && !isMarkItem(x))
+                .map((x) => ({ x, st: stateOf(x, followed.has(x.item.id)) }))
+                .filter((r) => (this.all || r.st.state !== 'closed') && (this.topic === undefined || r.st.topic === this.topic))
+            for (const state of ['new', 'question', 'blocked', 'open', 'claimed', 'closed'] as const) {
+                const of = rows.filter((r) => r.st.state === state)
+                if (of.length === 0) continue
+                h.out(`${state} (${of.length})`)
+                for (const { x, st } of of) h.out(`  ${x.item.id}  ${st.topic ?? ''}${st.worker ? ` ${st.worker}` : ''}${st.why ? ` (${st.why})` : ''}${isStale(x, now) ? ' (stale claim)' : ''}  ${x.item.title}`)
+            }
+            if (rows.length === 0) h.out('nothing open')
+            return all.broken.length > 0 ? 1 : 0
+        })
+    }
+}
+
+export class ReviewReadyCommand extends Command {
+    static override paths = [['review', 'ready']]
+    static override usage = Command.Usage({ category: 'Review', description: 'a draft card becomes a card he answers: its last frame, or the image given, stays', details: DETAILS })
+    id = Option.String()
+    image = Option.String('--image', { description: 'the image that stays' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { readItem, readyItem } = await import('../review/store.ts')
+            const live = readItem(h.dir, this.id)?.item.wip?.live
+            const r = await readyItem(h.dir, this.id, this.image ? { image: this.image } : {})
+            if (live !== undefined) h.unit?.live?.stop?.(live, 'ready')
+            h.out(`${r.id} ready: he can answer it`)
+            return 0
+        })
+    }
+}
+
+export class ReviewDeleteCommand extends Command {
+    static override paths = [['review', 'delete']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: "a player's test report removed at its source and here, or an item the owner raised removed here",
+        details: DETAILS,
+        examples: [['a test report', 'sk review delete live#3']],
+    })
+    refs = Option.Rest({ required: 1 })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { deleteRaised, deleteReport, itemOfRef } = await import('../review/store.ts')
+            for (const ref of this.refs) {
+                const x = itemOfRef(h.dir, ref)
+                if (!x) throw new Error(`no item ${ref}`)
+                if (x.item.origin.by === 'player') {
+                    const removers = (h.unit?.sources ?? []).filter((s) => s.remove)
+                    if (removers.length === 0) throw new Error(`${ref}: no source of the repo's review unit removes a report`)
+                    for (const s of removers) await s.remove?.(x)
+                    deleteReport(h.dir, x.item.id)
+                    h.out(`review: ${ref} deleted at its source and here`)
+                } else {
+                    deleteRaised(h.dir, x.item.id)
+                    h.out(`review: ${ref} deleted`)
+                }
+            }
+            return 0
+        })
+    }
+}
+
+export class ReviewMarksCommand extends Command {
+    static override paths = [['review', 'marks']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: "the owner's marks kept in the store: per subject its latest stars, mark and note",
+        details: DETAILS,
+        examples: [['every mark', 'sk review marks'], ['one kind, for a script', 'sk review marks --subject song --json']],
+    })
+    subject = Option.String('--subject', { description: 'one subject kind' })
+    json = Option.Boolean('--json', false, { description: 'every subject key, its latest mark and its history count' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { readAll } = await import('../review/store.ts')
+            const { marksOf } = await import('../review/marks.ts')
+            const all = readAll(h.dir)
+            for (const b of all.broken) h.err(`review: FAIL ${b.id}: ${b.error}`)
+            const marks = marksOf(all.items, h.say.spec).filter((m) => this.subject === undefined || m.kind === this.subject)
+            if (this.json) {
+                h.out(JSON.stringify(marks, null, 4))
+                return 0
+            }
+            for (const m of marks) {
+                const r = m.rate
+                const parts = Object.entries(m.parts).map(([p, s]) => `${p} ${s}★`)
+                h.out(`${(r.stars ? `${'★'.repeat(r.stars)}${'☆'.repeat(5 - r.stars)}` : (r.mark ?? '')).padEnd(8)} ${m.key}${parts.length ? `  (${parts.join(', ')})` : ''}${m.text ? `  ${m.text}` : ''}`)
+            }
+            h.out(`${marks.length} subjects marked`)
+            return 0
+        })
+    }
+}
+
+export class ReviewAnimCommand extends Command {
+    static override paths = [['review', 'anim']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: "a card's before and after as a looping animation to send: a cut, a fade or a wipe, mp4 or gif",
+        details: `${DETAILS}\n\nsk review anim <id> [--view n] | --before a.png --after b.png. Made once and kept under .shipkit/review/.anims/; --out <file | dir/> copies it out (default .shipkit/tmp/).`,
+        examples: [
+            ['a fade, mp4', 'sk review anim <id>'],
+            ['a wipe of the second view, gif', 'sk review anim <id> --view 1 --mode wipe --format gif'],
+        ],
+    })
+    id = Option.String({ required: false })
+    view = Option.String('--view', '0', { description: 'the view, 0 the first' })
+    mode = Option.String('--mode', 'fade', { description: 'cut, fade or wipe' })
+    format = Option.String('--format', 'mp4', { description: 'mp4 or gif' })
+    labels = Option.String('--labels', 'en', { description: 'the corner labels: en, fr or none' })
+    before = Option.String('--before', { description: 'an image, with --after: no card' })
+    after = Option.String('--after', { description: 'an image, with --before' })
+    out = Option.String('--out', { description: 'where it goes' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { copyFileSync, mkdirSync, statSync } = await import('node:fs')
+            const { dirname, join, resolve } = await import('node:path')
+            const { ANIM_FORMATS, ANIM_LABELS, ANIM_MODES, fileAnimation, isAnimFormat, isAnimLabels, isAnimMode, pairAnimation } = await import('../review/anim.ts')
+            const pair = this.before && this.after && !this.id ? { before: this.before, after: this.after } : undefined
+            if (!pair && (this.before || this.after || !this.id)) throw new Error('anim (<id> [--view n] | --before a.png --after b.png) [--mode cut|fade|wipe] [--format mp4|gif] [--labels en|fr|none] [--out f]')
+            const { mode, format, labels } = this
+            if (!isAnimMode(mode)) throw new Error(`--mode ${mode}: one of ${ANIM_MODES.join(', ')}`)
+            if (!isAnimFormat(format)) throw new Error(`--format ${format}: one of ${ANIM_FORMATS.join(', ')}`)
+            if (!isAnimLabels(labels)) throw new Error(`--labels ${labels}: one of ${ANIM_LABELS.join(', ')}`)
+            const root = dirname(dirname(h.dir))
+            const font = h.unit?.anim?.font ? join(root, h.unit.anim.font) : undefined
+            const ask = { view: Number(this.view) || 0, mode, format, labels, ...(font ? { font } : {}) }
+            const a = pair ? await fileAnimation(pair.before, pair.after, ask, join(root, '.shipkit/tmp/anims')) : await pairAnimation(h.dir, await idOf(h.dir, this.id ?? ''), ask)
+            const o = this.out ?? join(root, '.shipkit/tmp/')
+            const to = o.endsWith('/') ? join(o, a.name) : o
+            mkdirSync(dirname(resolve(to)), { recursive: true })
+            copyFileSync(a.file, to)
+            h.out(`${to}  ${(statSync(to).size / 1e6).toFixed(2)} MB, ${a.ms ? `${a.ms} ms` : 'cached'}`)
+            return 0
+        })
+    }
+}
+
+export class ReviewAutoCommand extends Command {
+    static override paths = [['review', 'auto']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: "the repo's auto rules: period, last run and answer, last item, next run; `auto run <id>` runs one",
+        details: `${DETAILS}\n\nsk review auto | sk review auto run <id> [--dry]. The hub's daemon runs them on their clocks.`,
+        examples: [['every rule', 'sk review auto'], ['what one would raise', 'sk review auto run veille --dry']],
+    })
+    verb = Option.String({ required: false })
+    rule = Option.String({ required: false })
+    dry = Option.Boolean('--dry', false, { description: 'print what it would raise or hold, write nothing' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { autoLogDir, nextRun, readAutoLog, runRule } = await import('../review/auto.ts')
+            const { readAll } = await import('../review/store.ts')
+            const rules = h.unit?.auto ?? []
+            if (this.verb === undefined) {
+                if (rules.length === 0) h.out("no auto rule: the repo's review unit declares none (auto: [...])")
+                const now = Date.now()
+                const ago = (t: number): string => `${Math.round(Math.abs(now - t) / 60_000)} min`
+                for (const r of rules) {
+                    const log = readAutoLog(h.dir, r.id)
+                    const next = nextRun(r, log, now)
+                    h.out(
+                        `${r.id}  every ${r.every}  ${log ? `ran ${ago(Date.parse(log.at))} ago (${log.ms.toFixed(1)} ms): ${log.answer}${log.error ? `: ${log.error}` : ''}` : 'never ran'}` +
+                            `${log?.lastRaised ? `  last item ${log.lastRaised.id}` : ''}  next ${next <= now ? 'due now' : `in ${ago(next)}`}`,
+                    )
+                }
+                if (rules.length > 0) h.out(`logs: ${autoLogDir(h.dir)}; the hub's daemon runs them`)
+                return 0
+            }
+            if (this.verb !== 'run' || !this.rule) throw new Error('auto | auto run <id> [--dry]')
+            const rule = rules.find((r) => r.id === this.rule)
+            if (!rule) throw new Error(`no auto rule « ${this.rule} »: ${rules.map((r) => r.id).join(', ') || 'none declared'}`)
+            const outcomes = await runRule(h.dir, rule, { items: readAll(h.dir).items, dry: this.dry })
+            if (outcomes.length === 0) h.out(`${rule.id}: nothing to raise`)
+            for (const o of outcomes)
+                h.out(
+                    'raised' in o
+                        ? `${rule.id}: raised ${o.raised} to ${o.raise.lane}: ${o.raise.title}`
+                        : 'held' in o
+                          ? `${rule.id}: held by ${o.held} (key ${o.key}, still open): ${o.raise.title}`
+                          : `${rule.id}: would raise to ${o.raise.lane} (key ${o.key}): ${o.raise.title}\n${o.raise.what}`,
+                )
+            return 0
+        })
+    }
+}
+
+export class ReviewWatchCommand extends Command {
+    static override paths = [['review', 'watch']]
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: 'one line per verdict, reply or raised note as it lands; every unseen one at start; never exits',
+        details: `${DETAILS}\n\nRun it under a monitor, unfiltered (a grep holds a burst's last line). It registers itself, so the hub shows who listens. An item nobody takes prints 2 minutes after its last message, then every 2 hours.`,
+        examples: [['the cards this session sent', 'sk review watch --mine'], ["one lane's items", 'sk review watch --lane interaction']],
+    })
+    mine = Option.Boolean('--mine', false, { description: "only this Claude Code session's cards" })
+    session = Option.String('--session', { description: "only that session's cards" })
+    lane = Option.String('--lane', { description: "only that lane's items" })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (h) => {
+            const { existsSync, mkdirSync, watch } = await import('node:fs')
+            const { readAll, scanStamp } = await import('../review/store.ts')
+            const { AGENT_RE, coversCard, laneOf, UNTAKEN_AGAIN_MS, untakenOf } = await import('../review/model.ts')
+            const { followedIds, unseen } = await import('../review/threads.ts')
+            const { raisedLine, untakenLine, watchLines } = await import('../review/format.ts')
+            const { liveWatchers, registerWatch } = await import('../review/watchers.ts')
+            const session = await sessionOf(this.mine, this.session)
+            const lane = this.lane?.trim() || null
+            if (lane !== null && !AGENT_RE.test(lane)) throw new Error(`--lane: « ${lane} » is no lane id (${AGENT_RE.source})`)
+            const mine = (x: Parameters<typeof coversCard>[1]): boolean => coversCard({ session, lane }, x)
+            registerWatch(h.dir, { session, lane })
+            const parent = process.ppid
+            const shown = new Set<string>()
+            const tick = (): void => {
+                const all = readAll(h.dir)
+                for (const b of all.broken) {
+                    const key = `broken ${b.id} ${b.error}`
+                    if (!shown.has(key)) h.err(`review: FAIL ${b.id}: ${b.error}`)
+                    shown.add(key)
+                }
+                for (const x of unseen(all.items).filter(mine))
+                    for (const l of watchLines(x, all.items)) {
+                        if (shown.has(l.key)) continue
+                        shown.add(l.key)
+                        h.out(l.text)
+                    }
+                for (const x of all.items.filter(mine)) {
+                    const l = raisedLine(x)
+                    if (l === null || shown.has(l.key)) continue
+                    shown.add(l.key)
+                    h.out(l.text)
+                }
+                // an item nobody takes: a --lane watch hears its own lane's, an unfiltered or --mine watch every one
+                const now = new Date()
+                const followed = followedIds(all.items)
+                const watchers = liveWatchers(h.dir)
+                for (const x of all.items) {
+                    if (lane !== null && laneOf(x) !== lane) continue
+                    const why = untakenOf(x, followed.has(x.item.id), watchers, now, h.say.spec.dispatcher)
+                    if (why === null) continue
+                    const round = Math.floor((now.getTime() - Date.parse(x.thread.at(-1)?.at ?? x.item.created)) / UNTAKEN_AGAIN_MS)
+                    const key = `untaken ${x.item.id} ${why} ${round}`
+                    if (shown.has(key)) continue
+                    shown.add(key)
+                    h.out(untakenLine(x, why, lane))
+                }
+            }
+            tick()
+            // the grace and the reminder pass with time alone: one read a minute
+            setInterval(tick, 60_000)
+            // a change under the folder asks again (debounced); a cheap stat stamp every 5 s catches a missed event
+            let soon: ReturnType<typeof setTimeout> | null = null
+            const again = (): void => {
+                if (soon) clearTimeout(soon)
+                soon = setTimeout(() => {
+                    soon = null
+                    tick()
+                }, 150)
+            }
+            if (!existsSync(h.dir)) mkdirSync(h.dir, { recursive: true })
+            watch(h.dir, { recursive: true }, again)
+            // the sources: pulled now and every 30 s, a new item lands and the tick prints it
+            await pull(h)
+            if (h.unit?.sources?.length) setInterval(() => void pull(h), 30_000)
+            let stamp = scanStamp(h.dir)
+            setInterval(() => {
+                // a watch whose parent died (a monitor's timeout) exits
+                if (process.ppid !== parent) process.exit(0)
+                const now = scanStamp(h.dir)
+                if (now !== stamp) again()
+                stamp = now
+            }, 5000)
+            return new Promise<number>(() => {})
+        })
+    }
+}
+
+export const REVIEW_COMMANDS = [
+    ReviewLsCommand,
+    ReviewAddCommand,
+    ReviewAddViewCommand,
+    ReviewShowCommand,
+    ReviewInboxCommand,
+    ReviewSeenCommand,
+    ReviewReplyCommand,
+    ReviewWithdrawCommand,
+    ReviewReopenCommand,
+    ReviewFixedCommand,
+    ReviewWontfixCommand,
+    ReviewClaimCommand,
+    ReviewReleaseCommand,
+    ReviewBlockedCommand,
+    ReviewDoneCommand,
+    ReviewDispatcherCommand,
+    ReviewDispatchCommand,
+    ReviewAskCommand,
+    ReviewDropCommand,
+    ReviewReassignCommand,
+    ReviewNextCommand,
+    ReviewTopicsCommand,
+    ReviewBoardCommand,
+    ReviewReadyCommand,
+    ReviewDeleteCommand,
+    ReviewMarksCommand,
+    ReviewAnimCommand,
+    ReviewAutoCommand,
+    ReviewWatchCommand,
+]