jackherd 1.9.0 → 1.11.0

package/src/plans/question-records.ts

@@ -0,0 +1,48 @@
+import { clockText } from '../plan-format/clock'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { WAITING_KIND, type WaitingItem } from '../plan-format/waiting'
+import { isRecordId } from './record-id'
+import { isStillWaiting } from './waiting-window'
+
+/** The record of a question that ended without an answer, as the kit hook `open-question` writes it to `.jackherd/questions/`. */
+export type QuestionRecord = {
+  id: string
+  question: string
+  askedAt: number
+  cwd: string
+  session: string
+  closedAt: number | null
+}
+
+/** Whether `value` has the shape of a question record's id: twelve lower-case hex digits. */
+export const isQuestionId = isRecordId
+
+/** The same shape as `isQuestionRecord` in the hook, which this package does not import at run time (contract test). */
+export const isQuestionRecord = (value: unknown): value is QuestionRecord => {
+  if (typeof value !== 'object' || value === null) return false
+  const record = value as Record<string, unknown>
+  return (
+    typeof record.id === 'string' &&
+    isQuestionId(record.id) &&
+    typeof record.question === 'string' &&
+    typeof record.askedAt === 'number' &&
+    typeof record.cwd === 'string' &&
+    typeof record.session === 'string' &&
+    (record.closedAt === null || typeof record.closedAt === 'number')
+  )
+}
+
+const itemOf = (record: QuestionRecord): WaitingItem => ({
+  since: clockText(record.askedAt),
+  item: terminalSafe(record.question),
+  kind: WAITING_KIND.question,
+  id: record.id,
+  open: true,
+})
+
+/** What the unanswered questions wait on: one open item per record younger than three days, oldest first. */
+export const questionWaitingItems = (records: readonly QuestionRecord[], now: number): WaitingItem[] =>
+  records
+    .filter(({ closedAt, askedAt }) => isStillWaiting(closedAt, askedAt, now))
+    .sort((left, right) => left.askedAt - right.askedAt)
+    .map(itemOf)

package/src/plans/questions-read.ts

@@ -0,0 +1,13 @@
+import { closableRecordLog } from './closable-records'
+import { isQuestionRecord } from './question-records'
+
+const log = closableRecordLog('questions', isQuestionRecord, ({ askedAt }) => askedAt)
+
+/** Every record of the question log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
+export const readQuestionRecords = log.read
+
+/** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+export const closeQuestionRecords = log.close
+
+/** Marks every open record `closedAt` and returns how many it closed. */
+export const closeAllQuestionRecords = log.closeAll

package/src/plans/read-cache.ts

@@ -0,0 +1,8 @@
+import type { StatCache } from '../shared/stat-cache'
+import type { TaskSignal } from '../task-signals/types'
+import type { PlanCache } from './plan-cache'
+
+/** What the herd keeps between its reads, so session logs and plans that did not change are not parsed again. */
+export type ReadCache = { signals: StatCache<TaskSignal[]>; plans: PlanCache }
+
+export const newReadCache = (): ReadCache => ({ signals: new Map(), plans: new Map() })

package/src/plans/record-id.ts

@@ -0,0 +1,4 @@
+const RECORD_ID = /^[0-9a-f]{12}$/
+
+/** Whether `value` has the shape of a record's id: twelve lower-case hex digits. */
+export const isRecordId = (value: string): boolean => RECORD_ID.test(value)

package/src/plans/restart-decision.ts

@@ -2,6 +2,12 @@ import { constants } from 'node:os'
 
 export const CHILD_MARKER = 'JACKHERD_PLANS_CHILD'
 
+/** The signal a newer herd view sends the older one of its terminal, so the older one ends as a wanted end. */
+export const TAKEOVER_SIGNAL = 'SIGUSR2'
+
+/** The exit code of a view that ended because a newer herd took its terminal over. */
+export const TAKEN_OVER_CODE = 75
+
 /** Milliseconds a burst of file changes is collapsed into one restart. */
 export const RESTART_DEBOUNCE_MS = 300
 
@@ -26,12 +32,15 @@ export type NextStep = 'respawn' | 'wait' | 'exit'
 
 /**
  * What the supervisor does once the child has ended. Only a wanted end stops it: a forwarded
- * signal (`stopping`) or a clean exit code 0 (`q`, Ctrl-C in raw mode). A restart we asked for
- * respawns; any other end is a crash, and the supervisor waits for the next change to the source.
+ * signal (`stopping`), a takeover by a newer herd (the exit code `TAKEN_OVER_CODE`, or the end by SIGKILL or
+ * `TAKEOVER_SIGNAL` that the newer herd causes when the child does not answer in time) or a clean exit code 0 (`q`,
+ * Ctrl-C in raw mode). A restart we asked for respawns, even when our own stopper had to SIGKILL the child; any other
+ * end is a crash, and the supervisor waits for the next change to the source.
  */
-export const nextStep = ({ restarting, stopping, code }: ChildExit): NextStep => {
-  if (stopping) return 'exit'
+export const nextStep = ({ restarting, stopping, code, signal }: ChildExit): NextStep => {
+  if (stopping || code === TAKEN_OVER_CODE) return 'exit'
   if (restarting) return 'respawn'
+  if (signal === 'SIGKILL' || signal === TAKEOVER_SIGNAL) return 'exit'
   return code === 0 ? 'exit' : 'wait'
 }
 

package/src/plans/row-actions.ts

@@ -0,0 +1,52 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import type { PlanLanguage } from '../vocabulary'
+import { boardRowKey } from './ask-target'
+import { closeAppointmentRow, closeWaitingRow } from './board-close'
+import { errorText } from './error-text'
+import { isQuestionId } from './question-records'
+import { DONE_KIND, type DoneTarget } from './row-targets'
+import { TEXTS } from './texts'
+
+/** What `closeRow` needs from the outside: the board file, its language, the clock, and the closing of log records. */
+export type CloseDependencies = {
+  sprintFile: string
+  language: PlanLanguage
+  now: Date
+  /** Closes the records of the files and questions log by id; how many it closed. */
+  closeRecords: (ids: readonly string[]) => number
+}
+
+const closeRecord = (id: string, { closeRecords }: CloseDependencies): string => {
+  if (!isQuestionId(id)) return TEXTS.notClosed('not a record id')
+  return closeRecords([id]) > 0 ? TEXTS.closed(`record ${id}`) : TEXTS.notClosed('record not found or closed already')
+}
+
+const closedBoard = (target: DoneTarget, board: string, { language, now }: CloseDependencies): string | null => {
+  if (target.kind === DONE_KIND.boardRow) return closeWaitingRow(board, language, target, now)
+  return target.kind === DONE_KIND.appointment ? closeAppointmentRow(board, language, target, now) : null
+}
+
+const subjectOfRow = (target: DoneTarget): string => {
+  if (target.kind === DONE_KIND.boardRow) return `board row ${boardRowKey(target.since, target.item)}`
+  return target.kind === DONE_KIND.appointment ? `appointment ${boardRowKey(target.when, target.action)}` : ''
+}
+
+const closeBoardRow = (target: DoneTarget, dependencies: CloseDependencies): string => {
+  try {
+    const board = readFileSync(dependencies.sprintFile, 'utf8')
+    const closed = closedBoard(target, board, dependencies)
+    if (closed === null) return TEXTS.notClosed('row not found in the board')
+    writeFileSync(dependencies.sprintFile, closed)
+    return TEXTS.closed(subjectOfRow(target))
+  } catch (error) {
+    return TEXTS.notClosed(errorText(error))
+  }
+}
+
+/**
+ * Closes what a `[done]` button names: a log record by its id, or a row of the board's file by writing the stamp into its
+ * status cell. Returns the footer line. The board is read again just before it is written, so a row the coordinator
+ * changed since the herd drew it is found by its text or not at all.
+ */
+export const closeRow = (target: DoneTarget, dependencies: CloseDependencies): string =>
+  target.kind === DONE_KIND.record ? closeRecord(target.id, dependencies) : closeBoardRow(target, dependencies)

package/src/plans/row-focus.ts

@@ -0,0 +1,148 @@
+import { ESC, RESET, stripAnsi, visibleLength } from '../terminal/text'
+import { textWidth } from '../terminal/width'
+import { isChipKey } from './link-chips'
+import type { ClickTarget, MouseEvent, Selection } from './selection'
+import type { BlockHit, BlockRow } from './waiting-click'
+
+/** A clickable row on screen: its key, the screen line (0-based, header lines first) it starts on and how many lines it takes. */
+export type FocusHit = { key: string; line: number; lines: number }
+
+export const FOCUS_MARK = '❯'
+export const FOCUS_ON = `${ESC}[48;5;238m`
+
+const BACKGROUND_LOST = new RegExp(`${ESC}\\[(?:0|49)?m`, 'g')
+const LEADING_STYLES = new RegExp(`^((?:${ESC}\\[[0-9;]*m)*)(.)`, 'u')
+/** The cells a row's lead may give up for the mark: a blank, the bar of a block, the closed chevron; an open chevron or a tree branch says more. */
+const MARKABLE_LEADS = new Set([' ', '▌', '▸'])
+
+const markedLead = (line: string): string =>
+  line.replace(LEADING_STYLES, (whole, styles: string, lead: string) =>
+    MARKABLE_LEADS.has(lead) ? `${styles}${FOCUS_MARK}` : whole,
+  )
+
+/**
+ * A row under the mouse or the selection: a light background across `width` cells, and, on the first line of the row
+ * (`marked`), the `❯` in place of the bar, blank or closed chevron that leads it. The background is laid again after
+ * every reset inside the line, so styled text and buttons keep it.
+ */
+export const focusLine = (line: string, width: number, marked: boolean): string => {
+  const shown = marked ? markedLead(line) : line
+  const padded = `${shown}${' '.repeat(Math.max(width - visibleLength(shown), 0))}`
+  return `${FOCUS_ON}${padded.replace(BACKGROUND_LOST, (reset) => `${reset}${FOCUS_ON}`)}${RESET}`
+}
+
+/** The row on screen line `line`, null where none is. */
+export const focusHitAt = (hits: readonly FocusHit[], line: number): FocusHit | null =>
+  hits.find((hit) => line >= hit.line && line < hit.line + hit.lines) ?? null
+
+/** The screen a motion report is looked up on: header lines, the body's rows and how far it is scrolled. */
+export type HoverFrame = { headerRows: number; bodyRows: number; top: number }
+
+/** The screen line (0-based, header first, the body unscrolled) under a motion report; null in the footer. */
+export const lineIndexAt = ({ row }: MouseEvent, { headerRows, bodyRows, top }: HoverFrame): number | null => {
+  const line = row - 1
+  if (line < headerRows) return line
+  const bodyLine = line - headerRows
+  return bodyLine < bodyRows ? headerRows + top + bodyLine : null
+}
+
+/** The key of the row under the mouse, null over none. */
+export const hoveredKeyAt = (hits: readonly FocusHit[], mouse: MouseEvent, frame: HoverFrame): string | null => {
+  const line = lineIndexAt(mouse, frame)
+  return line === null ? null : (focusHitAt(hits, line)?.key ?? null)
+}
+
+const BRACKET_BUTTON = /\[[^[\]]+\]/g
+
+/** The columns `[from, to)` of the square-bracket buttons in the visible text of a line. */
+export const bracketSpans = (visible: string): { from: number; to: number }[] =>
+  [...visible.matchAll(BRACKET_BUTTON)].map((match) => {
+    const from = textWidth(visible.slice(0, match.index))
+    return { from, to: from + textWidth(match[0]) }
+  })
+
+/** The column a square-bracket button under `column` starts in, null where the mouse is over none. */
+export const bracketAt = (visible: string, column: number): number | null =>
+  bracketSpans(visible).find((span) => column >= span.from && column < span.to)?.from ?? null
+
+const STYLE_OR_LINK = new RegExp(`(${ESC}\\[[0-9;]*m|${ESC}\\]8;[^;${ESC}\\x07]*;[^${ESC}\\x07]*(?:${ESC}\\\\|\\x07))`)
+const BOLD_ON = `${ESC}[1m`
+const BOLD_OFF = `${ESC}[22m`
+
+/** The line with the cells `[from, to)` bold, counted by what shows; styles and links in the line stay where they are. */
+export const boldCells = (line: string, from: number, to: number): string => {
+  let column = 0
+  return line
+    .split(STYLE_OR_LINK)
+    .map((token, index) => {
+      if (index % 2 === 1) return token
+      return [...token]
+        .map((character) => {
+          const start = column
+          column += textWidth(character)
+          const opens = start === from ? BOLD_ON : ''
+          const closes = column >= to && start < to ? BOLD_OFF : ''
+          return `${opens}${character}${closes}`
+        })
+        .join('')
+    })
+    .join('')
+}
+
+/** The line with the square-bracket button that starts in column `from` bold; the line itself where none does. */
+export const boldBracketAt = (line: string, from: number): string => {
+  const span = bracketSpans(stripAnsi(line)).find((each) => each.from === from)
+  return span ? boldCells(line, span.from, span.to) : line
+}
+
+/** The key of the hit of a line that holds links but is no row of its own: it is marked by the mouse only. */
+export const LINKS_KEY_PREFIX = 'links@'
+
+/** The selection with the row under the mouse and the button in it set; the selection itself while both are the same. */
+export const withHovered = (selection: Selection, key: string | null, from: number | null = null): Selection =>
+  (selection.hovered ?? null) === key && (selection.hoveredFrom ?? null) === from
+    ? selection
+    : { ...selection, hovered: key, hoveredFrom: from }
+
+/** Whether a row is the selected one or the one under the mouse. */
+export const isFocused = ({ selected, hovered }: Selection, key: string): boolean => key === selected || key === hovered
+
+/** Whether the buttons of a row are all bold: it is the row the arrows selected, and the mouse is not on it. */
+export const buttonsAllBold = ({ selected, hovered }: Selection, key: string): boolean =>
+  key === selected && key !== hovered
+
+/** The row of a drawn block that has `key`, null for a key of the body. */
+export const blockRowByKey = (blocks: readonly (BlockHit | null)[], key: string): BlockRow | null =>
+  blocks.flatMap((block) => block?.rows ?? []).find((row) => row.key === key) ?? null
+
+/** The rows of a block on top of the herd, from the screen line of its first row; none while the block is not drawn or folded. */
+export const focusHitsOfBlock = (block: BlockHit | null): FocusHit[] => {
+  let line = block?.firstLine ?? 0
+  return (block?.rows ?? []).map((row) => {
+    const hit = { key: row.key, line, lines: row.lines.length }
+    line += row.lines.length
+    return hit
+  })
+}
+
+/**
+ * The rows of a body from the lines its whole-line targets span, `offset` screen lines below the top; a chip is part of
+ * its row. A line with chips and no row of its own (the links under a lane) is a hit under a key made of its line.
+ */
+export const focusHitsOfTargets = (targets: readonly ClickTarget[], offset: number): FocusHit[] => {
+  const hits = new Map<string, FocusHit>()
+  for (const { key, line, wholeLine } of targets) {
+    if (!wholeLine || isChipKey(key)) continue
+    const known = hits.get(key)
+    hits.set(
+      key,
+      known ? { ...known, lines: line + 1 - (known.line - offset) } : { key, line: offset + line, lines: 1 },
+    )
+  }
+  const rowLines = new Set(targets.filter(({ wholeLine }) => wholeLine).map(({ line }) => line))
+  const linkLines = [...new Set(targets.filter(({ key }) => isChipKey(key)).map(({ line }) => line))]
+  const links = linkLines
+    .filter((line) => !rowLines.has(line))
+    .map((line) => ({ key: `${LINKS_KEY_PREFIX}${offset + line}`, line: offset + line, lines: 1 }))
+  return [...hits.values(), ...links]
+}

package/src/plans/row-targets.ts

@@ -0,0 +1,7 @@
+/** What a `[done]` button closes: a record of the files and questions log, a row of the waiting section, an appointment row. */
+export const DONE_KIND = { record: 'record', boardRow: 'boardRow', appointment: 'appointment' } as const
+
+export type DoneTarget =
+  | { kind: typeof DONE_KIND.record; id: string }
+  | { kind: typeof DONE_KIND.boardRow; since: string; item: string }
+  | { kind: typeof DONE_KIND.appointment; when: string; action: string }

package/src/plans/selection.ts

@@ -1,6 +1,7 @@
 import { currentPhase, type LaneProgress } from '../plan-format'
 import { AGENT_STATUS } from '../terminal/types'
 import { chipUrlOf, isChipKey, planUrlOf } from './link-chips'
+import { TEXTS } from './texts'
 
 /**
  * Whether a lane is drawn open. It is decided once, when the lane first appears (`autoOpen`, by its status then), and
@@ -8,6 +9,10 @@ import { chipUrlOf, isChipKey, planUrlOf } from './link-chips'
  */
 export type LaneFold = { open: boolean }
 
+/** The blocks on top of the herd, by the name their fold is remembered under. */
+export const TOP_BLOCK = { waiting: 'waiting', next: 'next', appointments: 'appointments', sources: 'sources' } as const
+export type TopBlockId = (typeof TOP_BLOCK)[keyof typeof TOP_BLOCK]
+
 /**
  * The row under the cursor and the expanded phases, both as keys, whether ticked phases and items are
  * listed one by one or summed up in one line, whether the footer shows the symbol legend, and the
@@ -15,10 +20,16 @@ export type LaneFold = { open: boolean }
  */
 export type Selection = {
   selected: string | null
+  /** The row under the mouse, null or absent while it is over none; drawn like the selected one. */
+  hovered?: string | null
+  /** The column the square-bracket button under the mouse starts in; null or absent while the mouse is over none. */
+  hoveredFrom?: number | null
   expanded: ReadonlySet<string>
   showDone: boolean
   showLegend: boolean
   laneFolds: ReadonlyMap<string, LaneFold>
+  /** Per folded top block, the keys of its points seen when it was folded; a block that is open has no entry. */
+  blockFolds?: Readonly<Partial<Record<TopBlockId, ReadonlySet<string>>>>
 }
 
 /** A lane as the folds need it: its name and the status its agent reports, null without an agent. */
@@ -70,12 +81,25 @@ export const PLANNED_KEY = 'planned'
 
 export const phaseKey = (lane: string, stepIndex: number, phaseId: string): string => `${lane}:${stepIndex}:${phaseId}`
 
+const PHASE_KEY_SHAPE = '[^@>#]+:\\d+:[^:#>]+'
+
+const PHASE_KEY = new RegExp(`^${PHASE_KEY_SHAPE}$`)
+
+/** Whether a key names a phase: not a lane, row or task key, which carry `@`, `>` or `#`. */
+const isPhaseKey = (key: string): boolean => PHASE_KEY.test(key)
+
+/** The key of a lane's `next` row, which opens to the phases that wait. */
+export const nextKey = (lane: string): string => `next>${lane}`
+
+/** The key of a lane's `✓` row, which opens to the finished phases. */
+export const finishedKey = (lane: string): string => `done>${lane}`
+
 const TICKED_KEY_PREFIX = 'ticked>'
 
 /** The key of the "N ticked" line of an open phase; it is clicked only, and a click lands on the phase. */
 export const tickedKey = (phase: string): string => `${TICKED_KEY_PREFIX}${phase}`
 
-const ITEM_KEY = /^(.+:\d+:[^:#]+)#(\d+)$/
+const ITEM_KEY = new RegExp(`^(${PHASE_KEY_SHAPE})#(\\d+)$`)
 
 /**
  * The key of a task row: its phase's key and the task's index in `phase.items`; a click or Enter opens its text.
@@ -173,13 +197,10 @@ const foldLane = (selection: Selection, lane: string, next: (open: boolean) => b
   return { ...selection, laneFolds: new Map(selection.laneFolds).set(lane, { ...fold, open: next(fold.open) }) }
 }
 
-/** Opens a task and the phase it belongs to. */
-const openTaskWithPhase = (expanded: Set<string>, phase: string, task: string): void => {
-  expanded.add(phase)
-  expanded.add(task)
-}
-
-/** Selects a row and opens it, or closes it when it is already open: a phase shows its items, a lane its phases. */
+/**
+ * Selects the row under a click. A "N ticked" line flips `showDone` and selects its phase, a lane line flips the
+ * fold of its lane, any other row opens when closed and closes when open: a phase shows its items.
+ */
 export const applyClick = (selection: Selection, key: string): Selection => {
   const phase = tickedPhaseOfKey(key)
   if (phase !== null) return { ...selection, showDone: !selection.showDone, selected: phase }
@@ -187,7 +208,7 @@ export const applyClick = (selection: Selection, key: string): Selection => {
   if (lane !== null) return { ...foldLane(selection, lane, flipped), selected: key }
   const expanded = new Set(selection.expanded)
   const itemPhase = itemPhaseOfKey(key)
-  if (itemPhase !== null && !expanded.has(itemPhase)) openTaskWithPhase(expanded, itemPhase, key)
+  if (itemPhase !== null && !expanded.has(itemPhase)) addWithPhase(expanded, key)
   else toggleIn(expanded, key)
   return { ...selection, selected: key, expanded }
 }
@@ -197,17 +218,30 @@ const toggle = (selection: Selection, keys: readonly string[]): Selection => {
   return current ? applyClick(selection, current) : selection
 }
 
-const changeSelected = (selection: Selection, keys: readonly string[], next: (open: boolean) => boolean): Selection => {
+/** Adds a key to the expanded ones, with the phase of a task. */
+const addWithPhase = (expanded: Set<string>, key: string): void => {
+  expanded.add(key)
+  const itemPhase = itemPhaseOfKey(key)
+  if (itemPhase !== null) expanded.add(itemPhase)
+}
+
+const removeKey = (expanded: Set<string>, key: string): void => {
+  expanded.delete(key)
+}
+
+/** Applies a change to the selected row: `nextFold` to the fold of a lane, `change` to the expanded keys for any other row. */
+const changeSelected = (
+  selection: Selection,
+  keys: readonly string[],
+  nextFold: (open: boolean) => boolean,
+  change: (expanded: Set<string>, key: string) => void,
+): Selection => {
   const current = selectedKey(selection, keys)
   if (!current) return selection
   const lane = laneOfKey(current)
-  if (lane !== null) return { ...foldLane(selection, lane, next), selected: current }
+  if (lane !== null) return { ...foldLane(selection, lane, nextFold), selected: current }
   const expanded = new Set(selection.expanded)
-  if (next(expanded.has(current))) {
-    expanded.add(current)
-    const itemPhase = itemPhaseOfKey(current)
-    if (itemPhase !== null) expanded.add(itemPhase)
-  } else expanded.delete(current)
+  change(expanded, current)
   return { ...selection, selected: current, expanded }
 }
 
@@ -218,9 +252,59 @@ export const toggledExpansion = (selection: Selection, key: string): Selection =
   return { ...selection, expanded }
 }
 
-const expand = (selection: Selection, keys: readonly string[]): Selection => changeSelected(selection, keys, opened)
+/**
+ * Whether `block` is drawn folded: it was folded and every point now open was there then. A point that arrived since
+ * opens it again, so folding never hides something new. Each block remembers its own points.
+ */
+export const isBlockFolded = ({ blockFolds }: Selection, block: TopBlockId, keys: readonly string[]): boolean => {
+  const folded = blockFolds?.[block]
+  return folded !== undefined && keys.every((key) => folded.has(key))
+}
+
+/**
+ * The selection with the fold of each block forgotten that a new point opened, given the points each block holds now.
+ * Without it a block that opened for a new point would fold again by itself once that point is gone. The selection
+ * itself when no fold is forgotten.
+ */
+export const settledBlockFolds = (
+  selection: Selection,
+  keysOf: Readonly<Record<TopBlockId, readonly string[]>>,
+): Selection => {
+  const folds = selection.blockFolds ?? {}
+  const opened = Object.values(TOP_BLOCK).filter(
+    (block) => folds[block] !== undefined && !isBlockFolded(selection, block, keysOf[block]),
+  )
+  if (opened.length === 0) return selection
+  const kept = Object.fromEntries(Object.entries(folds).filter(([block]) => !opened.includes(block as TopBlockId)))
+  const { blockFolds: _forgotten, ...rest } = selection
+  return Object.keys(kept).length > 0 ? { ...rest, blockFolds: kept } : rest
+}
+
+/** The selection with `block` folded over the points `keys` when it was open, and open when it was folded. */
+export const toggledBlockFold = (selection: Selection, block: TopBlockId, keys: readonly string[]): Selection => {
+  if (!isBlockFolded(selection, block, keys)) {
+    return { ...selection, blockFolds: { ...selection.blockFolds, [block]: new Set(keys) } }
+  }
+  const { blockFolds, ...rest } = selection
+  const { [block]: _folded, ...otherFolds } = blockFolds ?? {}
+  return Object.keys(otherFolds).length > 0 ? { ...rest, blockFolds: otherFolds } : rest
+}
 
-const collapse = (selection: Selection, keys: readonly string[]): Selection => changeSelected(selection, keys, closed)
+const expand = (selection: Selection, keys: readonly string[]): Selection =>
+  changeSelected(selection, keys, opened, addWithPhase)
+
+const collapse = (selection: Selection, keys: readonly string[]): Selection =>
+  changeSelected(selection, keys, closed, removeKey)
+
+/**
+ * The line for a press of `a` that changes nothing on screen, null for any other input. The key lists the ticked
+ * tasks inside an expanded phase, so it needs one among the `keys` drawn.
+ */
+export const showDoneNotice = (selection: Selection, input: string, keys: readonly string[]): string | null => {
+  if (!isInput(INPUT.showDone, input)) return null
+  const phaseOpen = keys.some((key) => isPhaseKey(key) && selection.expanded.has(key))
+  return phaseOpen ? null : TEXTS.showDoneNeedsPhase
+}
 
 export const applyKey = (selection: Selection, input: string, keys: readonly string[]): Selection => {
   if (isInput(INPUT.up, input)) return move(selection, keys, -1)
@@ -233,6 +317,9 @@ export const applyKey = (selection: Selection, input: string, keys: readonly str
   return selection
 }
 
+/** Whether an input is enter or space, which acts on the selected row. */
+export const isActivateKey = (input: string): boolean => isInput(INPUT.toggle, input)
+
 /** The key that writes the whole sprint as an HTML page and opens it. */
 export const isSprintPageKey = (input: string): boolean => isInput(INPUT.sprintPage, input)
 
@@ -242,6 +329,12 @@ export const parseMouse = (key: string): MouseEvent | null => {
   return { button: Number(match[1]), column: Number(match[2]), row: Number(match[3]), pressed: match[4] === 'M' }
 }
 
+const MOTION_BIT = 32
+
+/** Whether a report is the mouse moving (with or without a button held), not a click, a release or the wheel. */
+export const isMotion = ({ button, pressed }: MouseEvent): boolean =>
+  pressed && button >= MOTION_BIT && button < MOUSE_BUTTON.wheelUp
+
 export const targetAt = (targets: readonly ClickTarget[], line: number, column: number): string | null =>
   targets.find((target) => target.line === line && column >= target.from && column < target.to)?.key ?? null
 

package/src/plans/sent-files-read.ts

@@ -1,22 +1,13 @@
-import { join } from 'node:path'
-import { readRecords, writeRecordAtomically } from '../shared/private-records'
-import { isSentFileRecord, type SentFileRecord } from './sent-files'
+import { closableRecordLog } from './closable-records'
+import { isSentFileRecord } from './sent-files'
 
-const directoryOf = (root: string): string => join(root, '.jackherd', 'sent')
+const log = closableRecordLog('sent', isSentFileRecord, ({ sentAt }) => sentAt)
 
 /** Every record of the sent-file log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
-export const readSentRecords = (root: string): SentFileRecord[] =>
-  readRecords(directoryOf(root), isSentFileRecord, ({ sentAt }) => sentAt)
-
-const closeWhere = (root: string, isChosen: (record: SentFileRecord) => boolean, now: number): number => {
-  const open = readSentRecords(root).filter((record) => record.closedAt === null && isChosen(record))
-  for (const record of open) writeRecordAtomically(directoryOf(root), { ...record, closedAt: now })
-  return open.length
-}
+export const readSentRecords = log.read
 
 /** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
-export const closeSentRecords = (root: string, ids: readonly string[], now: number): number =>
-  closeWhere(root, (record) => ids.includes(record.id), now)
+export const closeSentRecords = log.close
 
 /** Marks every open record `closedAt` and returns how many it closed. */
-export const closeAllSentRecords = (root: string, now: number): number => closeWhere(root, () => true, now)
+export const closeAllSentRecords = log.closeAll

package/src/plans/sent-files.ts

@@ -1,8 +1,10 @@
 import { basename } from 'node:path'
-import { twoDigits } from '../plan-format/clock'
+import { clockText, DAY_MS } from '../plan-format/clock'
 import { terminalSafe } from '../plan-format/terminal-text'
-import type { WaitingItem } from '../plan-format/waiting'
+import { WAITING_KIND, type WaitingItem } from '../plan-format/waiting'
+import { isRecordId } from './record-id'
 import { laneDirectoryOf } from './unlisted-lanes'
+import { isStillWaiting } from './waiting-window'
 
 /** The record of a send of files to the user, as the kit hook `sent-file` writes it to `.jackherd/sent/`. */
 export type SentFileRecord = {
@@ -19,12 +21,8 @@ export type SentFileRecord = {
 /** A badge for a sent file: a `file:` address and the file's name. */
 export type SentChip = { url: string; label: string }
 
-const ID = /^[0-9a-f]{12}$/
 /** The address of a published artifact, as the hook reads it from the tool's answer, as a whole. */
 const ARTIFACT_ADDRESS = /^https:\/\/claude\.ai\/(?:code\/)?artifact\/[A-Za-z0-9_-]+$/
-const DAY_MS = 86_400_000
-/** A send waits on the user this long at most; the coordinator closes it earlier, with the answer. */
-const WAITING_DAYS = 3
 const SHOWN_PER_LANE = 5
 
 /** A published artifact is recorded by its address; a sent file by its path. */
@@ -49,7 +47,7 @@ export const isSentFileRecord = (value: unknown): value is SentFileRecord => {
   const record = value as Record<string, unknown>
   return (
     typeof record.id === 'string' &&
-    ID.test(record.id) &&
+    isRecordId(record.id) &&
     isStringArray(record.files) &&
     record.files.every(isRecordedFile) &&
     (record.caption === null || typeof record.caption === 'string') &&
@@ -96,18 +94,13 @@ export const sentChipsByLane = (
   return lanes
 }
 
-const clockText = (at: number): string => {
-  const date = new Date(at)
-  return `${twoDigits(date.getDate())}.${twoDigits(date.getMonth() + 1)}. ${twoDigits(date.getHours())}:${twoDigits(date.getMinutes())}`
-}
-
 const itemOf = (record: SentFileRecord): WaitingItem => {
   const [first] = record.files
   const more = record.files.length > 1 ? ` +${record.files.length - 1}` : ''
   return {
     since: clockText(record.sentAt),
     item: `${labelOf(first, record.caption)}${more}`,
-    kind: 'file',
+    kind: WAITING_KIND.file,
     id: record.id,
     open: true,
     url: addressOf(first),
@@ -117,5 +110,5 @@ const itemOf = (record: SentFileRecord): WaitingItem => {
 /** What the sends that no one closed wait on: one open item per record younger than three days, oldest first. */
 export const sentWaitingItems = (records: readonly SentFileRecord[], now: number): WaitingItem[] =>
   latestPerFile(records)
-    .filter(({ closedAt, sentAt }) => closedAt === null && now - sentAt <= WAITING_DAYS * DAY_MS)
+    .filter(({ closedAt, sentAt }) => isStillWaiting(closedAt, sentAt, now))
     .map(itemOf)