rvlib-shipkit 2.3.0 → 2.5.0

package/src/home/home-routes.ts

@@ -7,6 +7,7 @@ import { existsSync } from 'fs'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { installedVersion, isBehind } from '../fleet/scan-fleet.ts'
+import { heldNow, heldText } from '../core/last-good.ts'
 import { LIB_VERSION } from '../core/lib-version.ts'
 import { projectGutter, type ProjectRow } from '../serve/project-gutter-route.ts'
 import type { WiredRepo } from '../serve/project-gutter.ts'
@@ -20,6 +21,7 @@ import { ActivityCache, repoActivity, windowMinutes } from './activity.ts'
 import { devRepos, InsightsCache, type Scope } from './insights.ts'
 import { GLOBAL_CONTEXT_EVERY_MS, houseContext, writeIfChanged } from './global-context.ts'
 import { HouseRuns } from '../serve/house-runs.ts'
+import { pushFleet } from '../fleet/push-fleet.ts'
 
 /** how far back a repo's git page lists its commits */
 export const GIT_PAGE_MS = 7 * 24 * 3600_000
@@ -38,6 +40,8 @@ export type HomeAnswer = {
     /** repo → its installed shipkit, for every repo behind this home's */
     behind: Record<string, string>
     modernize: Record<string, ModernizeView>
+    /** the daemon runs older code than its tree, and why (core/last-good.ts) */
+    held?: string | null
 }
 
 export type HomeDeps = {
@@ -156,7 +160,8 @@ export function homeRoutes(d: HomeDeps) {
         }
         const modernize: Record<string, ModernizeView> = {}
         for (const [k, m] of modernizing) modernize[k] = { status: m.status, code: m.code, tail: tailLines(m.log, 40) }
-        return { version: LIB_VERSION, workers: d.hubs.views(repos), active: d.state.data.active, behind, modernize }
+        const h = heldNow()
+        return { version: LIB_VERSION, workers: d.hubs.views(repos), active: d.state.data.active, behind, modernize, held: h == null ? null : heldText(h) }
     }
 
     const find = (name: unknown): WiredRepo | null => repos.find((r) => r.name === name) ?? null
@@ -171,9 +176,14 @@ export function homeRoutes(d: HomeDeps) {
         }
         if (path === '/hub.json')
             // the identity a client probes (homeUp), through the web or here
-            return Response.json({ hub: 'shipkit-home', name: d.name, root: d.root, version: LIB_VERSION }, { headers: { 'access-control-allow-origin': '*' } })
+            return Response.json({ hub: 'shipkit-home', name: d.name, root: d.root, version: LIB_VERSION, held: heldNow() == null ? null : heldText(heldNow()!) }, { headers: { 'access-control-allow-origin': '*' } })
         if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the home page', { status: 403 })
         if (path.startsWith('/api/projects')) return d.gutter.handle(req, path)
+        // the activity page's push button: every house repo with unpushed commits, never a force (fleet/push-fleet.ts)
+        if (path === '/api/home/push-all' && req.method === 'POST') {
+            if (repos.length === 0) await refresh()
+            return Response.json(await pushFleet(repos.map((r) => ({ name: r.name, path: r.path }))))
+        }
         // the web asks which page routes to serve: one per house repo
         if (path === '/api/home/repos.json') {
             if (repos.length === 0) await refresh()

package/src/home/lib-watch.ts

@@ -5,10 +5,14 @@
 // started through cli.ts holds every command (one edit would restart all
 // three). This watch covers the lib source, filtered to the files the role's
 // own entry module reaches, and says a change once the burst of writes settles.
-import { existsSync, readFileSync, watch, type FSWatcher } from 'fs'
+// A restart lands only on code that loads (core/load-probe.ts): while a file
+// of the tree fails, the role keeps its running image and says why once. The
+// daemon also keeps the last good copy of the tree (core/last-good.ts).
+import { existsSync, readFileSync, realpathSync, statSync, watch, type FSWatcher } from 'fs'
 import { dirname, extname, join, relative, resolve } from 'path'
-import { LIB_ROOT } from '../core/lib-root.ts'
-import { diskLibVersion, LIB_VERSION } from '../core/lib-version.ts'
+import { copyStamp, heldNow, homeLib, LAST_GOOD_ENV, lastGood, OWN_LIB, setHeld, takeLastGood } from '../core/last-good.ts'
+import { LIB_VERSION } from '../core/lib-version.ts'
+import { bootEntries, probeLoad, TreeProbe } from '../core/load-probe.ts'
 import { reexecBlocker, reexecSelf } from '../core/reexec.ts'
 import { StaleRestart } from '../serve/stale-restart.ts'
 
@@ -56,6 +60,9 @@ export function libGraph(entry: string, o: { bundles?: boolean } = {}): Set<stri
 export class LibWatch {
     private w: FSWatcher | null = null
     private last: { file: string; at: number } | null = null
+    private any: { file: string; at: number } | null = null
+    /** every code write under src, own or not */
+    seq = 0
     readonly error: string | null = null
     private now: () => number
     private settleMs: number
@@ -64,11 +71,25 @@ export class LibWatch {
     constructor(private root: string, o: { settleMs?: number; now?: () => number; only?: Set<string> } = {}) {
         this.now = o.now ?? Date.now
         this.settleMs = o.settleMs ?? 1_000
+        // an APFS clone of the tree (the last good copy, a scratch checkout)
+        // fires a change on every source file it reads: only a moved mtime,
+        // or a file gone, is a write
+        const mtimes = new Map<string, number>()
+        const mtimeOf = (f: string): number | null => {
+            try { return statSync(f).mtimeMs } catch { return null }
+        }
+        for (const f of new Bun.Glob('**/*').scanSync(join(root, 'src'))) if (CODE.test(f)) mtimes.set(join(root, 'src', f), mtimeOf(join(root, 'src', f)) ?? -1)
         try {
             this.w = watch(join(root, 'src'), { recursive: true }, (_ev, file) => {
                 if (file == null || !CODE.test(String(file))) return
+                const full = join(root, 'src', String(file))
+                const m = mtimeOf(full)
+                if (m != null && m === mtimes.get(full)) return
+                mtimes.set(full, m ?? -1)
+                this.seq++
+                this.any = { file: String(file), at: this.now() }
                 if (o.only != null && !o.only.has(join(root, 'src', String(file)))) return
-                this.last = { file: String(file), at: this.now() }
+                this.last = this.any
             })
         } catch (e) {
             this.error = (e as Error).message
@@ -86,41 +107,92 @@ export class LibWatch {
         return `the shipkit source moved (src/${this.last.file})`
     }
 
+    /** no write anywhere under src for settleMs */
+    settled(): boolean {
+        return this.any == null || this.now() - this.any.at >= this.settleMs
+    }
+
+    /** one line on the last write anywhere under src, once settled, else null */
+    whyAny(): string | null {
+        return this.any == null || !this.settled() ? null : `the shipkit source moved (src/${this.any.file})`
+    }
+
     close(): void {
         this.w?.close()
         this.w = null
     }
 }
 
+/** how often the daemon may probe the tree to keep its last good copy */
+export const KEEP_EVERY_MS = 60_000
+
+const realOf = (p: string): string => {
+    try { return realpathSync(p) } catch { return p }
+}
+
+const versionAt = (root: string): string => {
+    try { return (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { version?: string }).version ?? '?' } catch { return '?' }
+}
+
 /** a machine process restarts itself in place, same pid, once its own code
- *  moved and nothing it runs is in flight. `before` tears down what must not
- *  outlive the image (its server); what it started detached keeps running */
+ *  moved, nothing it runs is in flight and the new code loads. `before`
+ *  tears down what must not outlive the image (its server); what it started
+ *  detached keeps running. On the last good copy it watches the tree and
+ *  goes back to it once it loads. `keep`: this process keeps the copy */
 export function reloadOnOwnCode(o: {
-    role: string
+    role: 'pm' | 'daemon' | 'web'
     /** the role's runner module: its graph is what the role reloads on */
     entry: string
     bundles?: boolean
     busy?: () => boolean
     before: () => void
+    keep?: boolean
     io: { print: (l: string) => void; printErr: (l: string) => void }
 }): { stop: () => void; files: number } {
-    const graph = libGraph(o.entry, { bundles: o.bundles })
-    const lib = new LibWatch(LIB_ROOT, { only: graph })
+    const onCopy = copyStamp(OWN_LIB) != null
+    const tree = homeLib()
+    const graph = libGraph(onCopy ? join(tree, relative(OWN_LIB, o.entry)) : o.entry, { bundles: o.bundles })
+    const lib = new LibWatch(tree, { only: onCopy ? undefined : graph })
     if (lib.error != null) o.io.printErr(`WARN no watch on the shipkit source (${lib.error}), so an edit of the ${o.role} needs a restart of it`)
+    const probe = new TreeProbe(() => probeLoad(tree, bootEntries(tree, o.role)), () => `${lib.seq}|${versionAt(tree)}`)
+    let since: number | null = null
+    let said = ''
+    const hold = (v: { file: string; error: string } | null): void => {
+        if (v == null) {
+            if (since != null) o.io.print(`ok: the shipkit source loads again`)
+            since = null
+            said = ''
+            if (!onCopy) setHeld(null)
+            return
+        }
+        since ??= heldNow()?.since ?? Date.now()
+        const text = `${v.file} fails to load (${v.error})`
+        if (text !== said) {
+            said = text
+            o.io.printErr(`FAIL: ${text}: sk runs the last good copy, and the ${o.role} keeps its running code until the tree loads again`)
+        }
+        setHeld({ since, file: v.file, error: v.error, from: tree, copyAt: lastGood(tree)?.at ?? null })
+    }
     const stale = new StaleRestart({
         boot: LIB_VERSION,
-        disk: diskLibVersion,
-        moved: () => lib.why(),
+        disk: () => versionAt(tree),
+        // on the copy, any write may heal the tree, and the first look is at once
+        moved: () => (onCopy ? (lib.whyAny() ?? (lib.seq === 0 ? 'this process runs the last good copy' : null)) : lib.why()),
         busy: o.busy ?? (() => false),
+        loads: () => probe.loads(),
+        hold,
         restart: (why) => {
             const blocked = reexecBlocker()
             if (blocked != null) throw new Error(blocked)
-            o.io.print(`ok: ${why}: the ${o.role} restarts in place`)
-            stale.stop()
-            lib.close()
+            o.io.print(`ok: ${why}: the ${o.role} restarts in place${onCopy ? ' on the tree' : ''}`)
+            stop()
             o.before()
             try {
-                reexecSelf()
+                if (!onCopy) reexecSelf()
+                const env = { ...process.env }
+                delete env[LAST_GOOD_ENV]
+                // the same script in the tree: cli.ts for most roles, run-pm.ts for pm
+                reexecSelf(env, join(tree, relative(realOf(OWN_LIB), realOf(process.argv[1] ?? join(OWN_LIB, 'src/cli.ts')))))
             } catch (e) {
                 o.io.printErr(`FAIL: the ${o.role} stopped to restart and could not: ${(e as Error).message}`)
                 process.exit(1)
@@ -128,12 +200,30 @@ export function reloadOnOwnCode(o: {
         },
         say: (text) => { if (text != null) o.io.printErr(`WARN ${text}`) },
     })
+    // the daemon keeps the copy: after a settled burst that loads, at most every KEEP_EVERY_MS
+    // once a minute counts from the last copy's own stamp (a restart keeps it), or from a try that failed
+    let kept = -1
+    let triedAt = 0
+    const keeper = o.keep === true && !onCopy
+        ? setInterval(() => {
+            if (lib.seq === kept || !lib.settled() || Date.now() - Math.max(lastGood(tree)?.at ?? 0, triedAt) < KEEP_EVERY_MS) return
+            const v = probe.loads()
+            if (v === 'pending') return
+            if (v !== 'ok') return hold(v)
+            hold(null)
+            kept = lib.seq
+            triedAt = Date.now()
+            void takeLastGood(tree).catch((e: Error) => o.io.printErr(`WARN the last good copy of the shipkit source could not be kept: ${e.message}`))
+        }, 2_000)
+        : null
+    function stop(): void {
+        stale.stop()
+        lib.close()
+        if (keeper != null) clearInterval(keeper)
+    }
     stale.start()
     return {
-        files: [...graph].filter((f) => !relative(LIB_ROOT, f).startsWith('..')).length,
-        stop: () => {
-            stale.stop()
-            lib.close()
-        },
+        files: [...graph].filter((f) => !relative(tree, f).startsWith('..')).length,
+        stop,
     }
 }

package/src/home/process-rows.ts

@@ -146,6 +146,8 @@ export const CORE_ABOUT = {
 export type CoreOpts = {
     /** the daemon's own version, asked of the daemon; null when it does not answer */
     daemonVersion?: string | null
+    /** the daemon runs older code than its tree, and why; null when it does not */
+    daemonHeld?: string | null
     /** where each listens, when pm does not say (an older pm, or pm down) */
     ports?: CorePorts | null
     /** one of shipkit's own not answering the page, and why: its row says
@@ -174,9 +176,9 @@ export function coreGroup(pm: PmAnswer | null, o: CoreOpts = {}): ProcessGroup {
         const c = pm?.children.find((x) => x.id === id)
         const port = ports?.[id] ?? null
         const version = id === 'daemon' ? (o.daemonVersion ?? null) : null
-        if (c == null) rows.push(coreRow(id, { status: 'unknown', pid: null, since: null, note: null, tail: [], version, port, restart: false }))
+        if (c == null) rows.push(coreRow(id, { status: 'unknown', pid: null, since: null, note: id === 'daemon' ? (o.daemonHeld ?? null) : null, tail: [], version, port, restart: false }))
         else {
-            const note = [c.note, c.restarts > 0 ? `${c.restarts} restart(s)` : null].filter((x) => x != null).join(', ')
+            const note = [id === 'daemon' ? (o.daemonHeld ?? null) : null, c.note, c.restarts > 0 ? `${c.restarts} restart(s)` : null].filter((x) => x != null).join(', ')
             rows.push(coreRow(id, { status: c.status, pid: c.pid, since: c.since, note: note === '' ? null : note, tail: c.tail, version, port, restart: true }))
         }
     }

package/src/home/run-daemon.ts

@@ -115,7 +115,7 @@ export async function runDaemon(root: string, io: HomeIo, o: { port?: number } =
             // the rows every gate filed land here, one commit a day at most
             also: (now) => { for (const n of landMotherhome({ now })) io.printErr(n) },
         })
-        const code = reloadOnOwnCode({ role: 'daemon', entry: fileURLToPath(import.meta.url), busy: () => hubs.busy(), before: () => { sweeps.stop(); home.stop() }, io })
+        const code = reloadOnOwnCode({ role: 'daemon', entry: fileURLToPath(import.meta.url), busy: () => hubs.busy(), before: () => { sweeps.stop(); home.stop() }, keep: true, io })
         io.print(`  ${house.repos.length} repos, state in ${dir}, reloads on ${code.files} lib files`)
         for (const sig of ['SIGINT', 'SIGTERM'] as const)
             process.on(sig, () => {

package/src/repo-config.ts

@@ -57,6 +57,9 @@ export type ServeConfig = {
          *  one failed, green when all passed. Default: the built-in md lint
          *  (orphans and dangling refs) over the repo root */
         lint?: string[]
+        /** the folder its node ids are relative to, where the wikis page reads
+         *  a page to search and preview (default: the repo root) */
+        dir?: string
     }
     /** agent/ graph entrypoint (default: index.md AND README.md) */
     agentIndex?: string

package/src/review/format.ts

@@ -19,7 +19,13 @@ const atText = (t: number | undefined): string => (t === undefined ? '' : ` at $
 
 /** each reaction to one view or tile: its place by label, its status, its comment */
 const reactionTexts = (x: ReviewItem): string[] =>
-    (verdictOf(x)?.reactions ?? []).map((q) => `${placeText(q, x.item.views)}${q.status ? ` ${q.status}` : ''}${q.comment ? `: ${flat(q.comment)}` : ''}`)
+    (verdictOf(x)?.reactions ?? []).map((q) => `${placeText(q, x.item.views)}${q.status ? ` ${q.status}` : ''}${q.stars ? ` ★${q.stars}` : ''}${q.comment ? `: ${flat(q.comment)}` : ''}`)
+
+/** the view he picked on a choice card, `picked [voice 1]`; null when he picked none */
+const pickText = (x: ReviewItem): string | null => {
+    const p = verdictOf(x)?.pick
+    return p === undefined ? null : `picked ${placeText({ view: p }, x.item.views)}`
+}
 
 /** one line per feedback, for a monitor: the status, the overall comment, each view's reaction, then each rectangle's comment */
 export function line(x: ReviewItem): string {
@@ -28,7 +34,8 @@ export function line(x: ReviewItem): string {
     const views = x.item.views
     const many = views.length > 1
     const rects = f.rects.map((q, i) => `#${i + 1}${many ? ` ${placeText(q, views)}` : ''}${q.side ? ` ${q.side}` : ''}${atText(q.t)} ${flat(q.comment) || '(no comment)'}`)
-    const parts = [...reactionTexts(x), ...rects]
+    const pick = pickText(x)
+    const parts = [...(pick ? [pick] : []), ...reactionTexts(x), ...rects]
     return `${x.item.id} ${f.status} "${x.item.title}": ${flat(f.comment) || '(no overall comment)'}${parts.length ? ` | ${parts.join(' | ')}` : ''}`
 }
 
@@ -131,7 +138,8 @@ export function detail(x: ReviewItem, dir: string, full = false, followed = fals
         ].join('\n')
     }
     if (!f) return [`${r.id}  NO VERDICT YET`, head, ...sub, ...replies].join('\n')
-    const out = [`${r.id}  ${f.status.toUpperCase()}  ${f.at}`, head, ...sub, `  comment: ${f.comment || '(none)'}`]
+    const pick = pickText(x)
+    const out = [`${r.id}  ${f.status.toUpperCase()}  ${f.at}`, head, ...sub, ...(pick ? [`  ${pick}`] : []), `  comment: ${f.comment || '(none)'}`]
     for (const t of reactionTexts(x)) out.push(`  view ${t}`)
     const px = (v: number, of: number): number => Math.round(v * of)
     const views = r.views

package/src/review/model.ts

@@ -124,6 +124,8 @@ export interface MediaView {
     clip?: ReviewClip
     audio?: ReviewAudio
     marks?: ReviewMark[]
+    /** a line on this view alone (an option's description on a choice card) */
+    note?: string
 }
 
 /** one image of a gallery view, a file of the folder (`v<n>-g<k>.<ext>`) */
@@ -168,6 +170,39 @@ export interface Item {
     light?: 'review'
     /** a draft card of a repo that shoots live: no verdict until it is ready */
     wip?: { live: string; frame: number }
+    /** a choice: every view is an option, he scores them and picks one */
+    choice?: true
+}
+
+/** a choice card: he picks one of its views */
+export const isChoice = (i: Item): boolean => i.choice === true
+
+/** a view that plays on its own: one clip or one sound, never a pair */
+export const isPlayable = (v: ReviewView | undefined): v is MediaView => v !== undefined && !isGallery(v) && !isPair(v.files) && (v.clip !== undefined || v.audio !== undefined)
+
+/** a card shown as options, one thin row a view: a choice, or two views or more that each play on their own */
+export const asOptions = (i: Item): boolean => isChoice(i) || (i.views.length >= 2 && i.views.every(isPlayable))
+
+/** the most stars a reaction gives */
+export const STARS = 5
+
+/** where a card is, for a fresh agent session in any repo: the repo as `~/dev/<repo>`, the card's url where it is open
+ *  now, and its phone url when the repo has a public host */
+export interface CardWhere {
+    root: string
+    open: string
+    phone?: string | null
+}
+
+/** one paste that hands a card to any agent session: what it is, where, the command that shows it whole, its links */
+export function pasteBlock(i: Item, state: string, w: CardWhere): string {
+    return [
+        `review card "${i.title}" (${state}), id ${i.id}`,
+        `repo: ${w.root}`,
+        `see it whole: cd ${w.root} && sk review show ${i.id}`,
+        `open: ${w.open}`,
+        ...(w.phone ? [`phone: ${w.phone}`] : []),
+    ].join('\n')
 }
 
 /** a view's name as the page and the CLI show it: its label, or « view n » */
@@ -219,6 +254,8 @@ export interface ReviewReaction {
     tile?: number
     status?: ReviewStatus
     comment: string
+    /** his score of the view, 1 to STARS */
+    stars?: number
 }
 
 /** a state change, or a read mark (`seen`, with the ids it read in `of`) */
@@ -238,6 +275,8 @@ export interface Message {
     rects?: Rect[]
     reactions?: ReviewReaction[]
     verdict?: ReviewStatus
+    /** the view he picked on a choice card, its index */
+    pick?: number
     /** a repo's own mark on a subject (stars, a song's mark): kept as written */
     rate?: { stars?: number; mark?: string; part?: string }
     op?: Op
@@ -313,6 +352,8 @@ export interface Verdict {
     comment: string
     rects: Rect[]
     reactions?: ReviewReaction[]
+    /** the view he picked, on a choice card */
+    pick?: number
     at: string
     seen: boolean
 }
@@ -338,6 +379,7 @@ export function verdictOf(x: ReviewItem): Verdict | null {
         comment: text ?? '',
         rects: rects ?? [],
         ...(m.reactions && m.reactions.length > 0 ? { reactions: m.reactions } : {}),
+        ...(m.pick !== undefined ? { pick: m.pick } : {}),
         at: m.at,
         seen: readBy(x, 'agent').has(m.id),
     }
@@ -677,6 +719,7 @@ export function itemProblems(v: unknown): string[] {
     for (const k of ['what', 'commit', 'supersedes', 'why', 'keeps']) if (v[k] !== undefined && typeof v[k] !== 'string') out.push(`${k}: a text`)
     if (v.light !== undefined && v.light !== 'review') out.push('light: review, or absent')
     if (v.wip !== undefined && !(obj(v.wip) && typeof v.wip.live === 'string' && v.wip.live !== '' && Number.isInteger(v.wip.frame))) out.push('wip: { live, frame }, or absent')
+    if (v.choice !== undefined && !(v.choice === true && Array.isArray(v.views) && v.views.length >= 2)) out.push('choice: true on a card of two views or more, or absent')
     return out
 }
 
@@ -690,6 +733,7 @@ export function messageProblems(v: unknown, name: string): string[] {
     if (v.op !== undefined && !OPS.includes(v.op as Op)) out.push(`op: one of ${OPS.join(', ')}`)
     if (v.verdict !== undefined && !STATUSES.includes(v.verdict as ReviewStatus)) out.push(`verdict: one of ${STATUSES.join(', ')}`)
     for (const k of ['text', 'image', 'note']) if (v[k] !== undefined && typeof v[k] !== 'string') out.push(`${k}: a text`)
+    if (v.pick !== undefined && !(Number.isInteger(v.pick) && (v.pick as number) >= 0 && v.verdict !== undefined)) out.push('pick: a view index, on a verdict')
     if (v.op === 'seen' && !(Array.isArray(v.of) && v.of.every((x) => typeof x === 'string'))) out.push('of: the ids a seen message read')
     if (v.op === undefined && v.verdict === undefined && v.rate === undefined && typeof v.text !== 'string' && !Array.isArray(v.rects))
         out.push('a message says something: text, rects, verdict, rate or op')
@@ -713,6 +757,7 @@ function galleryProblems(v: Record<string, unknown>, at: string): string[] {
 function viewProblems(v: Record<string, unknown>, at: string): string[] {
     const out: string[] = []
     if (typeof v.label !== 'string') out.push(`${at}label: a text`)
+    if (v.note !== undefined && typeof v.note !== 'string') out.push(`${at}note: a text`)
     const f = v.files
     const okImage = (n: unknown): boolean => typeof n === 'string' && FILE_RE.test(n) && !isClipFile(n) && !isAudioFile(n)
     const okClip = (n: unknown): boolean => typeof n === 'string' && FILE_RE.test(n) && isClipFile(n)
@@ -757,7 +802,7 @@ function viewProblems(v: Record<string, unknown>, at: string): string[] {
 }
 
 /** the verdict the page sends for an item, checked: every rectangle inside its view, a side exactly on a pair */
-export function verdictMessageOf(body: unknown, item: Item): { ok: true; message: Pick<Message, 'verdict' | 'text' | 'rects' | 'reactions'> } | { ok: false; errors: string[] } {
+export function verdictMessageOf(body: unknown, item: Item): { ok: true; message: Pick<Message, 'verdict' | 'text' | 'rects' | 'reactions' | 'pick'> } | { ok: false; errors: string[] } {
     if (!obj(body)) return { ok: false, errors: ['not an object'] }
     const errors: string[] = []
     if (!STATUSES.includes(body.status as ReviewStatus)) errors.push(`status: one of ${STATUSES.join(', ')}`)
@@ -800,7 +845,13 @@ export function verdictMessageOf(body: unknown, item: Item): { ok: true; message
         if (clip && typeof t === 'number') rect.t = t
         out.push(rect)
     }
-    const reactions = reactionsOf(body.reactions, views, errors)
+    const reactions = reactionsOf(body.reactions, views, errors, isChoice(item))
+    const pick = body.pick
+    if (pick !== undefined) {
+        if (!isChoice(item)) errors.push('pick: only on a choice card')
+        else if (!(typeof pick === 'number' && Number.isInteger(pick) && pick >= 0 && pick < views.length)) errors.push(`pick: the index of one of the card's ${views.length} views`)
+        else if (!isApproved(body.status as ReviewStatus)) errors.push('pick: goes with approved or approved-with-fix; rejecting every option is a plain rejected')
+    }
     if (errors.length > 0) return { ok: false, errors }
     const comment = typeof body.comment === 'string' ? body.comment : ''
     return {
@@ -810,13 +861,14 @@ export function verdictMessageOf(body: unknown, item: Item): { ok: true; message
             ...(comment ? { text: comment } : {}),
             ...(out.length > 0 ? { rects: out } : {}),
             ...(reactions.length > 0 ? { reactions } : {}),
+            ...(typeof pick === 'number' ? { pick } : {}),
         },
     }
 }
 
 /** the reactions the page sends, checked against the card's views: each on a view, a tile only on a gallery, one per view
  *  or tile; an empty one is dropped */
-function reactionsOf(v: unknown, views: readonly ReviewView[], errors: string[]): ReviewReaction[] {
+function reactionsOf(v: unknown, views: readonly ReviewView[], errors: string[], choice: boolean): ReviewReaction[] {
     if (v === undefined) return []
     if (!Array.isArray(v)) {
         errors.push('reactions: a list')
@@ -835,12 +887,21 @@ function reactionsOf(v: unknown, views: readonly ReviewView[], errors: string[])
         if (tile !== undefined && !(typeof tile === 'number' && Number.isInteger(tile) && tile >= 0 && tile < tiles)) errors.push(`reactions[${i}].tile: the index of one tile of a gallery view`)
         if (r.status !== undefined && !STATUSES.includes(r.status as ReviewStatus)) errors.push(`reactions[${i}].status: one of ${STATUSES.join(', ')}`)
         if (r.comment !== undefined && typeof r.comment !== 'string') errors.push(`reactions[${i}].comment: a text`)
+        const stars = r.stars
+        if (stars !== undefined && !(choice && typeof stars === 'number' && Number.isInteger(stars) && stars >= 1 && stars <= STARS))
+            errors.push(choice ? `reactions[${i}].stars: 1 to ${STARS}` : `reactions[${i}].stars: only on a choice card`)
         const key = `${String(r.view)}/${String(tile ?? '')}`
         if (seen.has(key)) errors.push(`reactions[${i}]: a second reaction on the same view or tile`)
         seen.add(key)
         const comment = typeof r.comment === 'string' ? r.comment.trim() : ''
-        if (r.status === undefined && comment === '') continue
-        out.push({ view: r.view as number, ...(typeof tile === 'number' ? { tile } : {}), ...(r.status !== undefined ? { status: r.status as ReviewStatus } : {}), comment })
+        if (r.status === undefined && comment === '' && stars === undefined) continue
+        out.push({
+            view: r.view as number,
+            ...(typeof tile === 'number' ? { tile } : {}),
+            ...(r.status !== undefined ? { status: r.status as ReviewStatus } : {}),
+            comment,
+            ...(typeof stars === 'number' ? { stars } : {}),
+        })
     }
     return out
 }

package/src/review/paste.ts

@@ -0,0 +1,30 @@
+// where a card lives, for the paste that hands it to another agent session (model.ts pasteBlock): the repo's path as
+// `~/dev/<repo>`, the house page's url, the phone's url through the repo's public host. Node side: the page reads it
+// from /api/review/spec
+import { homedir } from 'node:os'
+import { homePort } from '../home/home-paths.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import { defaultHubPort } from '../serve/hub-port.ts'
+
+export interface PasteHosts {
+    /** the repo's path, `~` for the home folder */
+    root: string
+    /** the house page of the repo, `#page:review:<id>` goes after it */
+    open: string
+    /** the repo's hub through its public host, null when it has none */
+    phone: string | null
+}
+
+export async function pasteHosts(root: string): Promise<PasteHosts> {
+    const c = await loadRepoConfig(root)
+    const home = homedir()
+    const host = c.serve?.publicHost
+    return {
+        root: root.startsWith(`${home}/`) ? `~${root.slice(home.length)}` : root,
+        open: `http://localhost:${homePort()}/r/${encodeURIComponent(c.name)}/`,
+        phone: host ? `http://${host}:${c.serve?.port ?? defaultHubPort(c.name)}/` : null,
+    }
+}
+
+/** a card's url under a hub base */
+export const cardUrl = (base: string, id: string): string => `${base}#page:review:${id}`

package/src/review/project.ts

@@ -2,12 +2,12 @@
 // walked dirs' times and its text, imported, its spec bound to the store; its sources pulled, its kinds' facts and data
 // view computed on the server, so the hub never bundles project code
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { isAbsolute, join, relative, resolve } from 'node:path'
 import { importFresh, repoUnitFiles } from '../core/discover-checks.ts'
 import { LAYOUT } from '../core/layout.ts'
 import type { ReviewItem } from './model.ts'
 import { bindSpec, readAll, storeDir } from './store.ts'
-import { specOfUnit, type Fact, type Link, type ReviewUnit, type ViewText } from './unit.ts'
+import { specOfUnit, type Fact, type Link, type ReviewUnit, type ViewPart, type ViewText } from './unit.ts'
 
 /** the walk's answer kept in the cache: the unit files and every dir it read, each with its time; a dir whose time moved
  *  means a file came or went, so the walk runs again */
@@ -90,7 +90,12 @@ export function factLines(unit: ReviewUnit | null, x: ReviewItem): string[] {
 }
 
 /** a kind's data view of one item, what the hub draws: its facts, links, live url and text; a function that throws says so as a fact */
-export function viewOfItem(unit: ReviewUnit | null, x: ReviewItem): { facts: Fact[]; links: Link[]; live: string | null; text: ViewText | null } {
+/** a part as the page reads it: its media a file of the item's `part-<n>` route, with its kind */
+export type PartData = Omit<ViewPart, 'media'> & { media?: 'image' | 'video' }
+
+const VIDEO = /\.(mp4|webm|mov|m4v)$/i
+
+export function viewOfItem(unit: ReviewUnit | null, x: ReviewItem): { facts: Fact[]; links: Link[]; live: string | null; text: ViewText | null; parts: PartData[] } {
     const k = unit?.kinds?.[x.item.subject.kind]
     const tryOr = <T>(what: string, f: (() => T) | undefined, none: T, errors: Fact[]): T => {
         try {
@@ -106,5 +111,16 @@ export function viewOfItem(unit: ReviewUnit | null, x: ReviewItem): { facts: Fac
     const links = tryOr('links', k?.links && (() => k.links?.(x) ?? []), [] as Link[], errors)
     const live = tryOr<string | null>('live', k?.live && (() => k.live?.(x) ?? null), null, errors)
     const text = tryOr<ViewText | null>('text', k?.text && (() => k.text?.(x) ?? null), null, errors)
-    return { facts: [...facts, ...source, ...errors], links, live, text }
+    const parts = tryOr('parts', k?.parts && (() => k.parts?.(x) ?? []), [] as ViewPart[], errors).map(({ media, ...p }): PartData => (media ? { ...p, media: VIDEO.test(media) ? 'video' : 'image' } : p))
+    return { facts: [...facts, ...source, ...errors], links, live, text, parts }
+}
+
+/** the repo file of part `n` of item `x`'s subject, inside the repo; null when the part names none or it is not there */
+export function partFile(root: string, unit: ReviewUnit | null, x: ReviewItem, n: number): string | null {
+    const media = unit?.kinds?.[x.item.subject.kind]?.parts?.(x)[n]?.media
+    if (!media) return null
+    const abs = resolve(root, media)
+    const rel = relative(root, abs)
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return null
+    return existsSync(abs) ? abs : null
 }

package/src/review/routes.ts

@@ -3,12 +3,13 @@
 // relative to the repo hub's base. null: not a path of these
 import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { extname, join } from 'node:path'
+import { dirname, extname, join } from 'node:path'
 import { isAnimFormat, isAnimLabels, isAnimMode, pairAnimation } from './anim.ts'
 import { startAuto } from './auto.ts'
 import { bad, KEEP, NO_STORE, ranged, TYPES } from './http.ts'
 import type { Rect, Subject } from './model.ts'
-import { openReview, viewOfItem } from './project.ts'
+import { pasteHosts } from './paste.ts'
+import { openReview, partFile, viewOfItem } from './project.ts'
 import { roleOf } from './role.ts'
 import { addMessage, imageFile, markRead, raiseItem, rateSubject, readAllCached, readItem, specOf, storeDir, storeStamp, threadImage, writeVerdict } from './store.ts'
 import { trailerRoutes } from './trailer-routes.ts'
@@ -110,8 +111,14 @@ async function reviewRoute(req: Request, path: string, dir: string, unit: Review
     }
     if (path === '/api/review/watchers' && req.method === 'GET') return Response.json(liveWatchers(dir), { headers: NO_STORE })
     // the unit's words, the dispatcher's holder: what the page draws the list's filters, labels and board with
-    if (path === '/api/review/spec' && req.method === 'GET')
-        return Response.json({ ...specData(specOf(dir)), role: roleOf(dir), sources: (unit?.sources ?? []).map((s) => s.id), auto: (unit?.auto ?? []).map((r) => ({ id: r.id, every: r.every })) }, { headers: NO_STORE })
+    if (path === '/api/review/spec' && req.method === 'GET') {
+        // where a card lives, for the paste that hands it to another agent session; a config that does not load leaves it out
+        const where = await pasteHosts(dirname(dirname(dir))).catch(() => null)
+        return Response.json(
+            { ...specData(specOf(dir)), role: roleOf(dir), sources: (unit?.sources ?? []).map((s) => s.id), auto: (unit?.auto ?? []).map((r) => ({ id: r.id, every: r.every })), where },
+            { headers: NO_STORE },
+        )
+    }
     if ((path === '/api/review/raise' || path === '/api/review/rate') && req.method === 'POST') {
         let img: ReturnType<typeof dataUrlFile> = null
         try {
@@ -196,6 +203,17 @@ async function reviewRoute(req: Request, path: string, dir: string, unit: Review
             return bad(e)
         }
     }
+    // a part's media (a draft's clip beside its text): the file the unit names for that part, never a path the page sends
+    const part = /^part-(\d+)$/.exec(name)
+    if (part) {
+        try {
+            const x = readItem(dir, id)
+            const f = x ? partFile(join(dir, '..', '..'), unit, x, Number(part[1])) : null
+            return f ? ranged(req, f) : bad(`no media for part ${part[1]} of ${id}`, 404)
+        } catch (e) {
+            return bad(e)
+        }
+    }
     if (name === 'anim') {
         const q = new URL(req.url).searchParams
         const mode = q.get('mode') ?? 'fade'