jackherd 1.8.1 → 1.10.0

package/src/plans/texts.ts

@@ -3,13 +3,13 @@ import { CHECK_NAME_LENGTH, CHECKS, type ChecksState, type PullRequest } from '.
 import { shownWithMore } from './shown-with-more'
 import { MODEL_MARK, NO_AGENT_WORD, PHASE_COUNT } from './symbols'
 
-/** The words of an open lane: its section labels, the age of a running phase, the wave, the finished phases not merged yet, and the pointer of a phase with only its review gate open. */
+/** The words of an open lane: the age of a running phase, the words before the open phases that wait and the finished ones, and the pointer of a phase with only its review gate open. */
 export type HerdTexts = {
-  sections: { session: string; chips: string; now: string; next: string; later: string; done: string }
   minutesAgo: (minutes: number) => string
-  wave: (wave: number) => string
-  notMerged: string
+  next: string
+  done: string
   reviewGate: string
+  gate: string
 }
 
 /**
@@ -23,7 +23,14 @@ export type PlanTexts = {
   noPlan: string
   noWorktree: string
   noRow: string
+  /** The heads of the blocks on top of the herd. */
+  waitingHeading: string
+  appointmentHeading: string
   notInPlan: string
+  /** Before a task an agent reports that no task of the plan names. */
+  now: string
+  /** Before the description of a running subagent that names no phase and sits on none. */
+  subagent: string
   /** In place of the count of a phase whose only open box is the documentation box of its review gate. */
   allButDocs: string
   tickedSummary: (count: number) => string
@@ -34,7 +41,13 @@ export type PlanTexts = {
   herd: HerdTexts
   checks: Record<ChecksState, string>
   hint: string
+  /** The notice when `a` is pressed with no phase open, where the key changes nothing on screen. */
+  showDoneNeedsPhase: string
   legend: string[]
+  /** The footer line when the coordinator could not be asked to put a question, with the reason. */
+  notAsked: (reason: string) => string
+  /** The footer line when the coordinator `name` was asked to put `subject`, `question <id>` or `board row <key>`. */
+  asked: (name: string, subject: string) => string
 }
 
 /** The words of the watcher's badges and of the header notice when they are missing. */
@@ -64,6 +77,7 @@ export const boardTexts = (term: string) => ({
   pageNotWritten: (reason: string) => `${term} page not written: ${reason}`,
   pageNotOpenedReason: (reason: string) => `${term} page: ${reason}`,
   notReadable: (reason: string) => `${term} not readable: ${reason}`,
+  notOpened: (reason: string) => `could not open: ${reason}`,
 })
 
 const ALL_BUT_DOCS = 'docs open'
@@ -75,18 +89,22 @@ export const TEXTS: PlanTexts = {
   noPlan: 'no plan',
   noWorktree: 'no worktree',
   noRow: 'no row in lanes',
+  waitingHeading: 'Waiting for you',
+  appointmentHeading: 'Appointments',
   notInPlan: 'not in the plan',
+  now: 'now:',
+  subagent: 'Subagent:',
   allButDocs: ALL_BUT_DOCS,
   tickedSummary: (count) => `${count} ticked · click or a lists them`,
   draft: 'draft · ',
   privateLink: 'private',
   phaseTally: (done, total) => (total > 0 ? `${done}/${total} ph` : ''),
   herd: {
-    sections: { session: 'SESSION', chips: '📎', now: 'NOW', next: 'NEXT', later: 'LATER', done: 'DONE' },
     minutesAgo: (minutes) => (minutes === 0 ? '· just now' : `· ${minutes} min ago`),
-    wave: (wave) => `wave ${wave}:`,
-    notMerged: 'not merged',
+    next: 'next',
+    done: 'done',
     reviewGate: 'Review gate',
+    gate: '· gate',
   },
   planned: (phases, plans) =>
     `planned (${phases} ${phases === 1 ? 'phase' : 'phases'} in ${plans} ${plans === 1 ? 'plan' : 'plans'})`,
@@ -96,15 +114,19 @@ export const TEXTS: PlanTexts = {
     [CHECKS.pending]: '… checks',
     [CHECKS.none]: 'no checks',
   },
-  hint: '↑↓ select  →← open  a show ticked  s html  q quit  ? help',
+  hint: '↑↓ select  →← open  a ticked tasks  s html  q quit  ? help',
+  showDoneNeedsPhase: 'a lists the ticked tasks inside an open phase: open one with → or a click',
   legend: [
-    'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a 📎 chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
-    '● working · ◆ blocked, waits for you · ◉ done = the agent finished its answer, not the lane · ○ idle · (·) no agent = a worktree nobody works in · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · working and blocked lanes open by themselves, → ← overrule until the status changes',
-    `▸ ▾ open and close · NOW ▶ the phases whose boxes or task lines moved in the last ${STALE_ACTIVITY_MINUTES} min, the one moved last first, · n min ago since then, → the task each is on (Review gate = only its review gate is open) · NEXT the next wave · LATER the other open phases · DONE ✓ the finished ones, not merged = ticked in the worktree, not on the base branch yet · ${ALL_BUT_DOCS} = only the documentation box is open · the lane line names the phase moved last · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a lists the ticked checkboxes one by one · s opens every lane and plan as one HTML page`,
-    `◐ progress over the lane's plans · n/m = m checkboxes, n ticked · n/m ph = n of m phases finished · n/n in green = all ticked · 🥣 share of the context window used · Sonnet ${MODEL_MARK.differs} Opus in amber = the phase's subagent ran on another model than the plan's`,
-    '↗ pull request · 💬 new feedback · ✋ changes requested · 🌐 preview · 📡 ticket: chip 📡 T-1 · status under 📎, 📡 <n> in amber on a folded lane when tickets are new',
-    "SESSION: the agent's title · ⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main",
+    'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a link chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
+    '● working · ◆ blocked, waits for you · ◉ done = the agent finished its answer, not the lane · ○ idle · (·) no agent = a worktree nobody works in · • state unknown · only blocked wears its word in the lane line, the symbol says the rest · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · a working or blocked lane opens by itself only when it first appears, after that → ← and clicks are yours alone',
+    `▸ ▾ open and close · an open lane's branches, top down: the agent's title and ⎇ its branch, ↗ its pull requests, its link chips, the phases it works on, next, done · a lane shows only the phases its board rows name · a phase row = some of its tasks are ticked, one of its boxes was ticked in the last ${STALE_ACTIVITY_MINUTES} min, or an agent reports working on it, by number · n min ago since the last tick or report, · gate = only the review gate is open · ▶ teal = a task an agent reported (its task list or jh task; its name dim at the right edge when several agents work in the lane), ▷ dim = only guessed from the words of its log · now: <text> = a reported task no plan task names · a running review sits on the gate box that names it, in the phase it names or else the lane's current one · Subagent: <text> = a running subagent that names no phase and sits on none · next = the other open phases, as ranges · done = the finished ones · ${ALL_BUT_DOCS} = only the documentation box is open · a folded lane line names the phase moved last, +n more active ones, and its count · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a lists the ticked checkboxes of an open phase one by one · s opens every lane and plan as one HTML page`,
+    `the bar = progress over the lane's plans · n/m = m checkboxes, n ticked · n/m ph = n of m phases finished · n/n in green = all ticked · 🥣 share of the context window used, on a folded lane only once it warns · Sonnet ${MODEL_MARK.differs} Opus in amber = the phase's subagent ran on another model than the plan's`,
+    '↗ pull request · 💬 new feedback · ✋ changes requested · 🌐 preview · 📡 ticket: chip 📡 T-1 · status among the link chips, 📡 <n> in amber on a folded lane when tickets are new',
+    '▌ on top = waits for your answer: 📎 a file or an Artifact that was sent (click: a cut-off row expands, then it opens), ? a question of the board or one a session left in its dialog (a click on its text only expands and folds it; [ask] at the right edge of a question asks the coordinator to put it) · it goes when the board row is closed or `jh waiting close <id>` · `Waiting for you` heads the block (click: fold; click on +n: show all, on ▴ n: five) · ◷ the appointments of the board in a grey bar below it (click: fold)',
+    '⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main',
   ],
+  notAsked: (reason) => `no coordinator to ask: ${reason}`,
+  asked: (name, subject) => `asked ${name} for ${subject}`,
 }
 
 /** The mark of a running lane the board has no row for; null for a lane it lists. */

package/src/plans/unlisted-lanes.ts

@@ -2,8 +2,8 @@ import { isAbsolute, relative, sep } from 'node:path'
 import type { SprintLane } from '../plan-format'
 import type { LaneAgent } from '../terminal'
 
-/** A worktree with an agent that has no row in the sprint table; `name` is its directory below the worktree directory. */
-export type UnlistedLane = { name: string; agent: LaneAgent }
+/** A worktree with an agent, or only a subagent of the coordinator, that has no row in the sprint table; `name` is its directory below the worktree directory. */
+export type UnlistedLane = { name: string; agent: LaneAgent | null }
 
 type PlacedAgent = { lane: string; agent: LaneAgent }
 
@@ -25,21 +25,26 @@ const placed = (agents: readonly LaneAgent[], worktreeDirectory: string): Placed
 
 /**
  * The lanes that run but are missing from the sprint table: one per worktree below `worktreeDirectory` with an
- * agent in it. A worktree counts as listed when the table names it, or names any agent running in it. The first
- * agent of a worktree stands for it; the lanes come in name order.
+ * agent in it, or a subagent of the coordinator at work in it (`subagentLanes`, no agent then). A worktree counts as
+ * listed when the table names it, or names any agent running in it. The first agent of a worktree stands for it; the
+ * lanes come in name order.
  */
 export const unlistedLanes = (
   agents: readonly LaneAgent[],
   listed: ReadonlySet<string>,
   worktreeDirectory: string,
+  subagentLanes: ReadonlySet<string> = new Set(),
 ): UnlistedLane[] => {
   const inWorktrees = placed(agents, worktreeDirectory)
   const listedWorktrees = new Set(
     inWorktrees.filter(({ lane, agent }) => listed.has(lane) || listed.has(agent.name)).map(({ lane }) => lane),
   )
-  const byLane = new Map<string, LaneAgent>()
+  const byLane = new Map<string, LaneAgent | null>()
   for (const { lane, agent } of inWorktrees) {
     if (!listedWorktrees.has(lane) && !byLane.has(lane)) byLane.set(lane, agent)
   }
+  for (const lane of subagentLanes) {
+    if (!listed.has(lane) && !byLane.has(lane)) byLane.set(lane, null)
+  }
   return [...byLane].sort(([left], [right]) => left.localeCompare(right)).map(([name, agent]) => ({ name, agent }))
 }

package/src/plans/view.ts

@@ -1,3 +1,4 @@
+import { ARTIFACT_LINK_KIND } from '../config/link-kinds'
 import { fit, plainText } from '../terminal/text'
 import { renderSelected, type Screen } from './layout'
 import type { Options } from './options'
@@ -20,7 +21,9 @@ const paneRows = (): number => process.stdout.rows ?? Number.MAX_SAFE_INTEGER
 export const bodyRows = (screen: Screen): number =>
   Math.max(paneRows() - screen.header.length - screen.footer.length, 1)
 
-export const clockOf = (locale: string): string => new Date().toLocaleTimeString(locale)
+/** The time as `HH:MM`, in the header and in the refresh error alike: a frame differs only once a minute. */
+export const clockOf = (locale: string, now: Date = new Date()): string =>
+  now.toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' })
 
 export const renderSnapshot = (
   snapshot: Snapshot,
@@ -37,6 +40,9 @@ export const renderSnapshot = (
       planned: snapshot.planned,
       watch: snapshot.watch,
       watchesTickets: snapshot.watchesTickets,
+      awaiting: snapshot.waiting,
+      appointments: snapshot.appointments,
+      unplaced: snapshot.unplaced,
     },
     selection,
     width,
@@ -45,24 +51,26 @@ export const renderSnapshot = (
 }
 
 export const startSelection = (snapshot: Snapshot, options: Options): Selection =>
-  options.lane
-    ? laneSelection(snapshot.views[0]?.progress, snapshot.views[0]?.status.agent ?? null)
-    : overviewSelection()
+  options.lane ? laneSelection(snapshot.views[0]?.progress) : overviewSelection()
 
 /** Header and footer stay put; the body shows `bodyRows` lines from `top`, padded so the footer sits at the bottom. */
-export const draw = (screen: Screen, top: number): void => {
-  const width = paneWidth()
-  const rows = bodyRows(screen)
+export const frameOutput = (screen: Screen, top: number, width: number, rows: number): string => {
   const body = screen.body.lines.slice(top, top + rows)
   const padding = Array.from({ length: Math.max(rows - body.length, 0) }, () => '')
   const lines = [...screen.header, ...body, ...padding, ...screen.footer]
-  process.stdout.write(
-    `${CURSOR_HOME}${lines.map((line) => `${fit(line, width)}${CLEAR_LINE_END}`).join('\r\n')}${CLEAR_BELOW}`,
-  )
+  return `${CURSOR_HOME}${lines.map((line) => `${fit(line, width)}${CLEAR_LINE_END}`).join('\r\n')}${CLEAR_BELOW}`
 }
 
-/** One frame as text; ANSI styling is dropped when stdout is not a terminal. */
+/** The frame to write, or null when the terminal already shows it; a null `previous` means the terminal content is unknown. */
+export const frameToWrite = (previous: string | null, next: string): string | null => (previous === next ? null : next)
+
+const ARTIFACT_ADDRESS = new RegExp(ARTIFACT_LINK_KIND.pattern)
+
+/**
+ * One frame as text; ANSI styling is dropped when stdout is not a terminal, and links are written out as their
+ * address, except an Artifact's, which is long and would push the rest of its line past the pane.
+ */
 export const frameText = (screen: Screen, isTerminal: boolean): string => {
   const lines = [...screen.header, ...screen.body.lines, ...screen.footer]
-  return (isTerminal ? lines : lines.map(plainText)).join('\n')
+  return (isTerminal ? lines : lines.map((line) => plainText(line, (url) => !ARTIFACT_ADDRESS.test(url)))).join('\n')
 }

package/src/plans/waiting-click.ts

@@ -0,0 +1,231 @@
+import { WAITING_KIND, type WaitingItem } from '../plan-format/waiting'
+import { fit, padVisible, wrap } from '../terminal/text'
+import { textWidth } from '../terminal/width'
+import { ASK_KIND, type AskTarget } from './ask-target'
+import { plain } from './layout-phase'
+import { MOUSE_BUTTON, type MouseEvent } from './selection'
+import { shortTitle } from './task-name'
+
+/**
+ * One row of a block of the herd as drawn: its plain text lines (more than one while it is expanded; the first starts
+ * with `mark` and a blank and, for a row with `[ask]`, is padded to leave the button its cells), whether its text is wider than the pane (`cut`), whether it is expanded, and the address a
+ * click opens.
+ */
+export type BlockRow = {
+  key: string
+  mark: string
+  lines: string[]
+  cut: boolean
+  expanded: boolean
+  url: string | null
+  /** What the coordinator can be asked to put: a dialog question or a row of the board; null for files and appointments. */
+  ask: AskTarget | null
+  /** The screen column (1-based) `[ask]` starts in on the first line, five cells wide; null for a row without one. */
+  askColumn: number | null
+  /** What the folded block shows of the row: the time column, if any, and the short title, without the mark. */
+  preview: string
+  /** Per line, the index in it where the part behind the short title starts; the line's length where none of it is. */
+  dimFrom: number[]
+}
+
+/** What a click does: expand or fold the row (its key), open an address, ask the coordinator to put the row, or nothing (null). */
+export type BlockClick = { toggle: string } | { open: string } | { ask: AskTarget }
+
+/**
+ * One row of a block of the herd before it is drawn: the key it expands by, the `mark` that starts it (kept apart so
+ * the block can paint it), its text, and what a click may do.
+ */
+export type BlockItem = {
+  key: string
+  mark: string
+  /** A column before the text, padded by the caller to the widest of the block (the time of an appointment). */
+  lead?: string
+  text: string
+  /** What the row shows while folded; the whole `text` when absent. */
+  title?: string
+  url: string | null
+  ask: AskTarget | null
+}
+
+/**
+ * What a click on a block is matched against, built from the block as it was drawn: `firstLine` is the screen line
+ * (0-based) of the first row, the line above it is the block's head; `rows` and `moreKey` are empty and null while the
+ * block is folded; `keys` are all its points, what a fold of the block remembers.
+ */
+export type BlockHit = {
+  firstLine: number
+  rows: readonly BlockRow[]
+  moreKey: string | null
+  keys: readonly string[]
+}
+
+/** How many rows a block of the herd (for-you, appointments) draws; the rest is one `+<n>` line. */
+export const SHOWN_BLOCK_ROWS = 5
+/** The key in the herd's expanded set that shows every point of the for-you block instead of the first five. */
+export const WAITING_MORE_KEY = 'more>waiting'
+/** The same for the appointment block. */
+export const APPOINTMENT_MORE_KEY = 'more>appointment'
+/** The bar and the blank that start every line of a for-you row. */
+export const WAITING_MARK = '▌'
+
+/** The button at the right edge of a question or a board row; a click on it, and only on it, asks the coordinator. */
+export const ASK_BUTTON = '[ask]'
+const ASK_GAP = 1
+const FILE_MARK = '📎'
+const QUESTION_MARK = '?'
+const OPENABLE = /^(https?|file):\/\//
+
+/** The key of a row in the herd's expanded set: the record's id, else its text. */
+export const waitingKey = ({ id, item }: WaitingItem): string => `waiting>${id ?? item}`
+
+/** The keys of all open points, the shown ones and the `+<n>` rest alike: what the fold of the block remembers. */
+export const waitingKeys = (items: readonly WaitingItem[]): string[] => items.map(waitingKey)
+
+const BAR_WIDTH = textWidth(`${WAITING_MARK} `)
+
+const roomOf = (width: number): number => Math.max(width - BAR_WIDTH, 1)
+
+/** The cells a row's text may take and the screen column `[ask]` starts in; no column for a row without a button. */
+const askLayout = (ask: AskTarget | null, width: number): { room: number; askColumn: number | null } => {
+  if (!ask) return { room: roomOf(width), askColumn: null }
+  const room = Math.max(roomOf(width) - (textWidth(ASK_BUTTON) + ASK_GAP), 1)
+  return { room, askColumn: BAR_WIDTH + room + ASK_GAP + 1 }
+}
+
+const askOf = (item: WaitingItem): AskTarget | null => {
+  if (item.kind === WAITING_KIND.file) return null
+  if (item.kind === WAITING_KIND.question) return item.id ? { kind: ASK_KIND.question, id: item.id } : null
+  return { kind: ASK_KIND.boardRow, since: item.since, item: item.item }
+}
+
+/** The text wrapped to `room` cells behind `start` (the mark and the time column), the other lines indented to the column of the text. */
+const hangingLines = (start: string, text: string, room: number): string[] => {
+  const hang = textWidth(start)
+  const [first, ...rest] = wrap(text, Math.max(room - hang, 1))
+  return [`${start}${first}`, ...rest.map((line) => `${' '.repeat(hang)}${line}`)]
+}
+
+/**
+ * Per line, the index where the part behind the short title starts (the line's length while none of it is on the
+ * line): the title may take several lines, and the rest starts on the line where it ends. `titleLength` is 0 for a
+ * row without a short title.
+ */
+const dimStarts = (lines: readonly string[], start: string, titleLength: number): number[] => {
+  let remaining = titleLength
+  return lines.map((line, index) => {
+    if (titleLength === 0) return line.length
+    const from = index === 0 ? start.length : textWidth(start)
+    const content = line.length - from
+    if (remaining > content) {
+      remaining -= content + 1
+      return line.length
+    }
+    const dimFrom = from + Math.max(remaining, 0)
+    remaining = 0
+    return dimFrom
+  })
+}
+
+const itemOf = (item: WaitingItem): BlockItem => ({
+  key: waitingKey(item),
+  mark: item.kind === WAITING_KIND.file ? FILE_MARK : QUESTION_MARK,
+  text: plain(item.item),
+  title: shortTitle(plain(item.item)),
+  url: item.kind === WAITING_KIND.file && item.url && OPENABLE.test(item.url) ? item.url : null,
+  ask: askOf(item),
+})
+
+const rowOf = (
+  { key, mark, lead, text, title = text, url, ask }: BlockItem,
+  expandedKeys: ReadonlySet<string>,
+  width: number,
+): BlockRow => {
+  const { room, askColumn } = askLayout(ask, width)
+  const leadText = lead === undefined ? '' : `${lead} `
+  const start = `${mark} ${leadText}`
+  const cut = title !== text || textWidth(`${start}${text}`) > room
+  const expanded = cut && expandedKeys.has(key)
+  const [first, ...rest] = expanded ? hangingLines(start, text, room) : [fit(`${start}${title}`, room)]
+  const lines = ask ? [padVisible(first, room + ASK_GAP), ...rest] : [first, ...rest]
+  const dimFrom = dimStarts([first, ...rest], start, expanded && title !== text ? title.length : 0)
+  return { key, mark, lines, cut, expanded, url, ask, askColumn, preview: `${leadText}${title}`, dimFrom }
+}
+
+/**
+ * The rows a block of the herd draws: the first five, or all of them while `moreKey` is in the expanded set; each
+ * folded to one line unless expanded.
+ */
+export const blockRows = (
+  items: readonly BlockItem[],
+  expandedKeys: ReadonlySet<string>,
+  width: number,
+  moreKey: string,
+): BlockRow[] =>
+  (expandedKeys.has(moreKey) ? items : items.slice(0, SHOWN_BLOCK_ROWS)).map((item) => rowOf(item, expandedKeys, width))
+
+/** The rows the herd draws for what waits on the user. */
+export const waitingRows = (
+  items: readonly WaitingItem[],
+  expandedKeys: ReadonlySet<string>,
+  width: number,
+): BlockRow[] => blockRows(items.map(itemOf), expandedKeys, width, WAITING_MORE_KEY)
+
+/** The key of the `+<n>` line of a block with `count` points, null while the block has no more than it shows. */
+export const moreKeyOf = (count: number, key: string): string | null => (count > SHOWN_BLOCK_ROWS ? key : null)
+
+const rowAt = (
+  rows: readonly BlockRow[],
+  firstLine: number,
+  line: number,
+): { row: BlockRow; onFirstLine: boolean } | null => {
+  let first = firstLine
+  for (const row of rows) {
+    if (line < first + row.lines.length) return line >= first ? { row, onFirstLine: line === first } : null
+    first += row.lines.length
+  }
+  return null
+}
+
+const onAskButton = ({ askColumn }: BlockRow, column: number | undefined): boolean =>
+  askColumn !== null && column !== undefined && column >= askColumn && column < askColumn + textWidth(ASK_BUTTON)
+
+const clickOn = (row: BlockRow, onFirstLine: boolean, column: number | undefined): BlockClick | null => {
+  const { key, cut, expanded, url, ask } = row
+  if (ask && onFirstLine && onAskButton(row, column)) return { ask }
+  if (url) return cut && !expanded ? { toggle: key } : { open: url }
+  return cut ? { toggle: key } : null
+}
+
+/** Whether a plain left click hit the head line of a block, which folds and opens it. `headLine` is 0-based. */
+export const blockHeadClick = (
+  headLine: number,
+  { button, row, pressed }: Pick<MouseEvent, 'button' | 'row' | 'pressed'>,
+): boolean => pressed && button === MOUSE_BUTTON.left && row - 1 === headLine
+
+/**
+ * What a plain left click on a block does. A click on the `[ask]` button of a question or a board row (the columns of
+ * its first line) asks the coordinator, whatever the fold. Any other click on a row that is cut off expands or folds it,
+ * except that a file or Artifact opens on the click after it expanded; a row that fits opens its file or does nothing.
+ * The `+<n>` line, the line right
+ * under the rows, toggles `moreKey` (all points or the first five); `moreKey` is null while the block has no such
+ * line. Other lines, a click with a modifier (ctrl is left to the terminal's own link opening), a release and the
+ * wheel do nothing. `firstLine` is the screen line (0-based) of the first row, as `renderScreen` returns it.
+ */
+export const blockClick = (
+  rows: readonly BlockRow[],
+  firstLine: number,
+  {
+    button,
+    row,
+    pressed,
+    column,
+  }: Pick<MouseEvent, 'button' | 'row' | 'pressed'> & Partial<Pick<MouseEvent, 'column'>>,
+  moreKey: string | null = null,
+): BlockClick | null => {
+  if (!pressed || button !== MOUSE_BUTTON.left) return null
+  const line = row - 1
+  const moreLine = firstLine + rows.reduce((sum, { lines }) => sum + lines.length, 0)
+  if (moreKey !== null && line === moreLine) return { toggle: moreKey }
+  const target = rowAt(rows, firstLine, line)
+  return target ? clickOn(target.row, target.onFirstLine, column) : null
+}

package/src/plans/waiting-records.ts

@@ -0,0 +1,39 @@
+import { openWaitingItems, type WaitingItem } from '../plan-format/waiting'
+import type { PlanLanguage } from '../vocabulary'
+import { type QuestionRecord, questionWaitingItems } from './question-records'
+import { readQuestionRecords } from './questions-read'
+import { type SentFileRecord, sentWaitingItems } from './sent-files'
+import { readSentRecords } from './sent-files-read'
+
+/** The two logs that wait on the user, as read from the main checkout. */
+export type WaitingRecords = { sent: SentFileRecord[]; questions: QuestionRecord[] }
+
+/** The files sent to the user and the questions left unanswered that no one closed, files first. */
+export const waitingItemsOfRecords = (
+  sent: readonly SentFileRecord[],
+  questions: readonly QuestionRecord[],
+  now: number,
+): WaitingItem[] => [...sentWaitingItems(sent, now), ...questionWaitingItems(questions, now)]
+
+/** What waits on the user: the board's own rows (none when `board` is null), then the sends and questions. */
+export const waitingItemsOf = (
+  board: string | null,
+  language: PlanLanguage,
+  { sent, questions }: WaitingRecords,
+  now: number,
+): WaitingItem[] => [
+  ...(board === null ? [] : openWaitingItems(board, language)),
+  ...waitingItemsOfRecords(sent, questions, now),
+]
+
+/** Both logs read from `root`; each file is read once, whoever uses it. */
+export const readWaitingRecords = (root: string): WaitingRecords => ({
+  sent: readSentRecords(root),
+  questions: readQuestionRecords(root),
+})
+
+/** The files sent to the user and the questions left unanswered that no one closed, files first, read from `root`. */
+export const recordWaitingItems = (root: string, now: number): WaitingItem[] => {
+  const { sent, questions } = readWaitingRecords(root)
+  return waitingItemsOfRecords(sent, questions, now)
+}

package/src/plans/waiting-window.ts

@@ -0,0 +1,8 @@
+import { DAY_MS } from '../plan-format/clock'
+
+/** A question or a sent file waits on the user this long at most; a later answer or `jh waiting close` ends it earlier. */
+const WAITING_DAYS = 3
+
+/** Whether a record that was closed at `closedAt` (null: never) and began at `at` still waits on the user at `now`. */
+export const isStillWaiting = (closedAt: number | null, at: number, now: number): boolean =>
+  closedAt === null && now - at <= WAITING_DAYS * DAY_MS

package/src/preview/command.ts

@@ -0,0 +1,105 @@
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import { pageDirectoryOf, systemLocation } from '../shared/private-location'
+import { openInBrowser } from '../terminal/open'
+import { runGh } from '../watch/gh'
+import { embedExternalImages, fetchImage } from './embed'
+import { rewriteImages } from './images'
+import { mediaTypeOf } from './open'
+import { asksForHelp, PREVIEW_USAGE, parsePreviewOptions } from './options'
+import { previewPage } from './page'
+import { renderMarkdown, repositorySlugOf } from './render'
+
+type PackageFacts = { root: string; name: string }
+
+const packageOf = (file: string): PackageFacts | null => {
+  for (let directory = dirname(file); ; directory = dirname(directory)) {
+    const manifest = join(directory, 'package.json')
+    if (existsSync(manifest)) {
+      const name = (JSON.parse(readFileSync(manifest, 'utf8')) as { name?: unknown }).name
+      if (typeof name === 'string') return { root: directory, name }
+    }
+    if (dirname(directory) === directory) return null
+  }
+}
+
+const remoteSlugOf = (directory: string): string | null => {
+  const result = Bun.spawnSync(['git', '-C', directory, 'remote', 'get-url', 'origin'], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  return result.exitCode === 0 ? repositorySlugOf(result.stdout.toString()) : null
+}
+
+/** Whether `file` is a regular file whose real path, links followed, lies under the real path of `root`. */
+const isRegularFileUnder = (root: string, file: string): boolean => {
+  if (!existsSync(file)) return false
+  return realpathSync(file).startsWith(`${realpathSync(root)}/`) && statSync(file).isFile()
+}
+
+/**
+ * The image at `path` under `root` as a data address; null when it is missing, no image, no regular file, or outside
+ * `root` once links are followed, so a link in the working tree cannot put a file from elsewhere into the page.
+ */
+export const inlineImage = (root: string, path: string): string | null => {
+  const file = resolve(root, path)
+  const type = mediaTypeOf(file)
+  if (type === null || !file.startsWith(`${root}/`) || !isRegularFileUnder(root, file)) return null
+  return `data:${type};base64,${readFileSync(file).toString('base64')}`
+}
+
+/**
+ * Writes the page to `out` when the user named one, else to `preview-<name>.html` in the user's private page directory
+ * (verified by `ensurePrivateDirectory`, written through `writePrivateFile`), never to a fixed name in the shared
+ * temporary directory; returns the path written.
+ */
+export const writePreviewPage = (
+  file: string,
+  page: string,
+  out: string | null,
+  pageDirectory: string = pageDirectoryOf(systemLocation()),
+): string => {
+  if (out !== null) {
+    const chosen = resolve(out)
+    writeFileSync(chosen, page)
+    return chosen
+  }
+  ensurePrivateDirectory(pageDirectory)
+  const path = join(pageDirectory, `preview-${basename(file, '.md')}.html`)
+  writePrivateFile(path, page)
+  return path
+}
+
+/**
+ * `jh preview <markdown-file> [--out <path>] [--open]`: renders the file through GitHub's markdown API and writes a
+ * page that shows it in GitHub and in npm style, light and dark, and at phone width. The package's own images come
+ * from the working tree, so the preview shows what is not published yet. External images (badges) are embedded as data addresses, so the page is complete where it may load nothing from outside; one that cannot be fetched stays linked, with one warning. Prints the path of the page; `--open`
+ * opens it. `--help` prints the usage. Exit 0 written, 1 failed (`gh` missing or not signed in, file unreadable).
+ */
+export const run = async (args: string[]): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(PREVIEW_USAGE)
+    return 0
+  }
+  try {
+    const options = parsePreviewOptions(args)
+    const file = resolve(options.file)
+    if (!existsSync(file)) throw new Error(`${options.file} does not exist`)
+    const facts = packageOf(file)
+    const html = await renderMarkdown(readFileSync(file, 'utf8'), remoteSlugOf(dirname(file)), dirname(file), runGh)
+    const own = facts ?? { root: dirname(file), name: '' }
+    const local = rewriteImages(html, own.name, (path) => inlineImage(own.root, path))
+    const { html: rewritten, failed } = await embedExternalImages(local, fetchImage)
+    if (failed > 0)
+      console.error(`${failed} external ${failed === 1 ? 'image' : 'images'} could not be embedded and stay linked`)
+    const out = writePreviewPage(file, previewPage({ title: basename(file), html: rewritten }), options.out)
+    console.log(out)
+    const reason = options.open ? openInBrowser(out) : null
+    if (reason) console.error(`could not open the page: ${reason}`)
+    return 0
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}