jackherd 1.8.1 → 1.10.0

package/src/plans/link-chips.ts

@@ -14,6 +14,7 @@ const MARKS = /\*\*|`/g
 const CONTROL = /\p{Cc}/gu
 
 const linksOf = (line: string): Found[] => {
+  if (!line.includes('http')) return []
   const found: Found[] = []
   const take = (url: string, text: string | null, index: number) =>
     found.push({ url, text, before: line.slice(0, index), line })

package/src/plans/live.ts

@@ -1,14 +1,18 @@
 import { existsSync, type FSWatcher, watch } from 'node:fs'
-import { dirname } from 'node:path'
+import { basename, dirname } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { terminalSafe } from '../plan-format/terminal-text'
+import { runHerdr } from '../terminal/herdr'
 import { openInBrowser } from '../terminal/open'
+import { appointmentKeys } from './appointment-rows'
+import { askCoordinator } from './ask-coordinator'
 import type { LaneMemory } from './current-phase'
 import { errorText } from './error-text'
 import {
   type FetchState,
   fetchBase,
   fetchNotice,
+  fetchPlanHeads,
   goneLanePullRequests,
   initialFetchState,
   shouldFetch,
@@ -19,15 +23,25 @@ import { fetchPullRequests, noPullRequests, type PullRequestState } from './gith
 import { recallLanes, rememberLanes } from './herd-memory'
 import type { Screen } from './layout'
 import { type KnownPage, pageAfterWrite, pageKey, pageNeedsWriting, planAnchorOn, withPlanChips } from './plan-chips'
+import { planPullRequests } from './plan-heads'
 import { herdLabel } from './plan-panes'
 import { pullRequestUrl } from './pull-requests'
+import { newReadCache, type ReadCache } from './read-cache'
+import { TAKEN_OVER_CODE, TAKEOVER_SIGNAL } from './restart-decision'
 import {
   inputOutcome,
   isSprintPageKey,
   overviewSelection,
+  parseMouse,
+  settledBlockFolds,
+  showDoneNotice,
   splitKeys,
   syncLaneFolds,
+  TOP_BLOCK,
+  type TopBlockId,
   targetKeys,
+  toggledBlockFold,
+  toggledExpansion,
   type View,
   windowTop,
 } from './selection'
@@ -36,7 +50,18 @@ import { singleFlight } from './single-flight'
 import { loadSnapshot, type Snapshot, type Source } from './snapshot'
 import { exportSprintPage, writeSprintPageInSteps } from './sprint-export'
 import { boardTexts } from './texts'
-import { bodyRows, clockOf, draw, paneWidth, renderSnapshot, startSelection, TERMINAL_OFF, TERMINAL_ON } from './view'
+import {
+  bodyRows,
+  clockOf,
+  frameOutput,
+  frameToWrite,
+  paneWidth,
+  renderSnapshot,
+  startSelection,
+  TERMINAL_OFF,
+  TERMINAL_ON,
+} from './view'
+import { type BlockClick, type BlockHit, blockClick, blockHeadClick, waitingKeys } from './waiting-click'
 
 /** The state of the running view; only the functions below `runLive` change it. */
 type Live = {
@@ -55,6 +80,8 @@ type Live = {
   reported: Map<string, string | null>
   /** Per lane, the ticks seen at the last read, the phase that moved last and when each moved; kept across herds (`rememberLanes`). */
   memories: Map<string, LaneMemory>
+  /** Session logs and plans parsed at the last read, kept while they did not change. */
+  cache: ReadCache
   pending: Timer | null
   /** The snapshot as read, without the plan chips; `snapshot` is this plus the chips of `page`. */
   read: Snapshot | null
@@ -63,6 +90,8 @@ type Live = {
   pageWriting: boolean
   flight: (() => Promise<void>) | null
   pageError: string | null
+  /** The frame last written to the terminal; null while its content is unknown, such as after a resize. */
+  written: string | null
 }
 
 const REFRESH_MS = 5_000
@@ -140,7 +169,10 @@ const redraw = (live: Live) => {
   const top = windowTop(live.view, screen.body.cursorLine, screen.body.lines.length, bodyRows(screen))
   live.screen = screen
   live.view = { ...live.view, top }
-  draw(screen, top)
+  const output = frameToWrite(live.written, frameOutput(screen, top, paneWidth(), bodyRows(screen)))
+  if (output === null) return
+  live.written = output
+  process.stdout.write(output)
 }
 
 /** The whole sprint, also while the view shows one lane: the snapshot is read again without the lane filter. */
@@ -190,16 +222,27 @@ const refresh = (live: Live, onChange: () => void): Promise<void> => {
 
 const readOnce = async (live: Live, onChange: () => void) => {
   try {
-    const read = await loadSnapshot(live.source, live.pullRequests, live.memories)
+    const read = await loadSnapshot(live.source, live.pullRequests, live.memories, live.cache)
     rememberLanes(live.source.root, live.memories, read.documents.laneOrder)
     const next = withKnownPage(live, read)
     live.read = read
-    if (!live.snapshot) live.view = { ...live.view, selection: startSelection(next, live.source.options) }
+    if (!live.snapshot)
+      live.view = {
+        ...live.view,
+        selection: startSelection(next, live.source.options),
+      }
     const folded = syncLaneFolds(
       live.view.selection,
-      next.views.map(({ progress, status }) => ({ lane: progress.lane.name, status: status.agent })),
+      next.views.map(({ progress, status }) => ({
+        lane: progress.lane.name,
+        status: status.agent,
+      })),
     )
-    live.view = { ...live.view, selection: folded }
+    const settled = settledBlockFolds(folded, {
+      waiting: waitingKeys(next.waiting ?? []),
+      appointments: appointmentKeys(next.appointments?.rows ?? []),
+    })
+    live.view = { ...live.view, selection: settled }
     live.snapshot = next
     const fetchLine = fetchNotice(live.fetch, baseRefOf(live.source.settings), CLOCK_LOCALE)
     live.errors = [
@@ -243,6 +286,53 @@ const openPlan = (live: Live, snapshot: Snapshot, address: string) => {
   live.notice = reason === null ? texts.pageOpened(live.page.path) : texts.pageNotOpenedReason(reason)
 }
 
+/**
+ * What a hit on a row of a block of the herd does: expands or folds it, asks the coordinator to put a question or a board row
+ * (the result shows in the footer) or opens its address (a failure shows there). An appointment row only ever expands.
+ */
+const applyBlockClick = (live: Live, outcome: BlockClick): void => {
+  if ('toggle' in outcome) {
+    live.view = {
+      ...live.view,
+      selection: toggledExpansion(live.view.selection, outcome.toggle),
+    }
+    return
+  }
+  if ('ask' in outcome) {
+    const { root, settings } = live.source
+    live.notice = askCoordinator(outcome.ask, {
+      language: settings.responseLanguage,
+      adapter: settings.adapter,
+      repository: basename(root),
+      run: runHerdr,
+    })
+    return
+  }
+  const reason = openInBrowser(outcome.open)
+  if (reason) live.notice = boardTextsOf(live).notOpened(terminalSafe(reason))
+}
+
+/**
+ * A plain click on a block on top of the herd, matched against `hit` as it was drawn: the head folds or opens it, a
+ * cut-off row expands, a file or Artifact opens, a question or a board row asks the coordinator; the failure or the result
+ * shows in the footer. An appointment row has nothing to open or ask.
+ */
+const clickBlock = (live: Live, block: TopBlockId, hit: BlockHit | null, input: string): boolean => {
+  const mouse = parseMouse(input)
+  if (!mouse || !hit) return false
+  if (blockHeadClick(hit.firstLine - 1, mouse)) {
+    live.view = {
+      ...live.view,
+      selection: toggledBlockFold(live.view.selection, block, hit.keys),
+    }
+    return true
+  }
+  const outcome = blockClick(hit.rows, hit.firstLine, mouse, hit.moreKey)
+  if (!outcome) return false
+  applyBlockClick(live, outcome)
+  return true
+}
+
 const handleInput = (live: Live, input: string) => {
   const { snapshot, screen } = live
   if (!snapshot || !screen) return
@@ -251,12 +341,20 @@ const handleInput = (live: Live, input: string) => {
     void writeSprintPage(live, snapshot)
     return
   }
+  if (
+    clickBlock(live, TOP_BLOCK.waiting, screen.waitingBlock, input) ||
+    clickBlock(live, TOP_BLOCK.appointments, screen.appointmentBlock, input)
+  ) {
+    redraw(live)
+    return
+  }
   const context = {
     keys: targetKeys(screen.body.targets),
     targets: screen.body.targets,
     headerRows: screen.header.length,
     bodyRows: bodyRows(screen),
   }
+  live.notice = showDoneNotice(live.view.selection, input, context.keys)
   const pullRequests = snapshot.views.flatMap((view) => view.pullRequests)
   const outcome = inputOutcome(live.view, input, context, (key) => pullRequestUrl(pullRequests, key))
   live.view = outcome.view
@@ -284,12 +382,14 @@ export const runLive = (source: Source): void => {
     fetchHead: fetchHeadPath(source.root),
     reported: new Map(),
     memories: recallLanes(source.root),
+    cache: newReadCache(),
     pending: null,
     read: null,
     page: null,
     pageWriting: false,
     flight: null,
     pageError: null,
+    written: null,
   }
   const schedule = () => {
     if (live.pending) clearTimeout(live.pending)
@@ -298,6 +398,8 @@ export const runLive = (source: Source): void => {
   const fetchBaseBranch = async () => {
     live.fetch = { ...live.fetch, lastAttempt: Date.now(), running: true }
     const failure = await fetchBase(source.root, BASE_REMOTE, source.settings.baseBranch)
+    const planHeads = planPullRequests([...live.pullRequests.byBranch.values()].flat(), source.settings.planDirectory)
+    if (failure === null) await fetchPlanHeads(source.root, BASE_REMOTE, planHeads)
     live.fetch = {
       ...live.fetch,
       running: false,
@@ -324,17 +426,24 @@ export const runLive = (source: Source): void => {
     fetchWhenDue(readable && gone.length > 0)
     schedule()
   }
-  const quit = () => {
+  const leave = (code: number) => {
     clearTitles(source, live.reported)
     source.terminal.labelOwnPane(null)
     for (const watcher of live.watchers.values()) watcher.close()
     process.stdout.write(TERMINAL_OFF)
-    process.exit(0)
+    process.exit(code)
   }
+  const quit = () => leave(0)
+  const takenOver = () => leave(TAKEN_OVER_CODE)
   const onInput = (input: string) => (QUIT_KEYS.has(input) ? quit() : handleInput(live, input))
 
   source.terminal.labelOwnPane(herdLabel(source.options.lane))
-  enterTerminal(onInput, quit, () => redraw(live))
+  process.removeAllListeners(TAKEOVER_SIGNAL)
+  process.on(TAKEOVER_SIGNAL, takenOver)
+  enterTerminal(onInput, quit, () => {
+    live.written = null
+    redraw(live)
+  })
   setInterval(() => {
     fetchWhenDue(false)
     void refresh(live, schedule)

package/src/plans/phase-ids.ts

@@ -0,0 +1,8 @@
+const SUB_PHASE_LETTERS = /[a-z]+$/i
+
+/** The main phase a sub-phase belongs to: `10c` is part of `10`; a main phase is its own. */
+export const mainPhaseIdOf = (id: string): string => id.replace(SUB_PHASE_LETTERS, '')
+
+/** Whether `named` names the phase: by its own id, or by its main phase when it is a sub-phase (`21b` by `21`). */
+export const isNamedBy = (id: string, named: ReadonlySet<string>): boolean =>
+  named.has(id) || named.has(mainPhaseIdOf(id))

package/src/plans/phase-models.ts

@@ -1,5 +1,5 @@
 import { type LaneProgress, resolvePlanPath } from '../plan-format'
-import { isRecord } from '../watch/json-guards'
+import { isRecord } from '../shared/is-record'
 
 /** The model families a phase ran on and was recommended, as lower-case words; `fits` null without a recommendation. */
 export type PhaseModel = { used: string; recommended: string | null; fits: boolean | null }

package/src/plans/phase-ranges.ts

@@ -0,0 +1,45 @@
+import { phaseLabel } from '../plan-format'
+
+const RANGE_DASH = '–'
+const RANGE_SEPARATOR = ', '
+/** A phase id as a number with an optional sub-phase letter: `10`, `10c`. */
+const NUMBERED_ID = /^(\d+)([a-z]*)$/i
+
+/** One entry of the text: a run of whole phases `first`–`last`, or one id that stands alone. */
+type Entry = { first: number; last: number } | { alone: string }
+
+const byNumber = (first: string, second: string): number => first.localeCompare(second, undefined, { numeric: true })
+
+const entryText = (entry: Entry): string => {
+  if ('alone' in entry) return phaseLabel(entry.alone)
+  const first = phaseLabel(String(entry.first))
+  return entry.first === entry.last ? first : `${first}${RANGE_DASH}${phaseLabel(String(entry.last))}`
+}
+
+/** The entry `id` extends, or the entries with `id` after them; `wholes` are the main phases among the ids. */
+const withId = (entries: Entry[], id: string, wholes: ReadonlySet<string>): Entry[] => {
+  const [, main = '', sub = ''] = NUMBERED_ID.exec(id) ?? []
+  if (main === '' || (sub !== '' && !wholes.has(String(Number(main))))) return [...entries, { alone: id }]
+  if (sub !== '') return entries
+  const number = Number(main)
+  const last = entries.at(-1)
+  if (last && !('alone' in last) && last.last === number - 1)
+    return [...entries.slice(0, -1), { ...last, last: number }]
+  return [...entries, { first: number, last: number }]
+}
+
+/**
+ * Phase ids as ranges, numbered ids by number first: `P1–P7, P10–P15`. A gap ends a range; a sub-phase (`P10c`) is
+ * inside its main phase when that one is among the ids too, else it stands alone between the ranges. An id that is
+ * no number stands alone after the numbered ones. Empty for no id.
+ */
+export const phaseRanges = (ids: readonly string[]): string => {
+  const sorted = [...new Set(ids)].sort(byNumber)
+  const numbered = sorted.filter((id) => NUMBERED_ID.test(id))
+  const wholes = new Set(numbered.filter((id) => /^\d+$/.test(id)).map((id) => String(Number(id))))
+  const others = sorted.filter((id) => !NUMBERED_ID.test(id))
+  return [...numbered, ...others]
+    .reduce<Entry[]>((entries, id) => withId(entries, id, wholes), [])
+    .map(entryText)
+    .join(RANGE_SEPARATOR)
+}

package/src/plans/phase-source.ts

@@ -35,6 +35,21 @@ const tickCount = (phase: PlanPhase): number => phase.items.filter((item) => ite
 const tickedFurther = (worktreePhase: PlanPhase, basePhase: PlanPhase): boolean =>
   tickCount(worktreePhase) > tickCount(basePhase)
 
+/**
+ * The phases of `base` with each phase replaced by the copy's where the copy ticked it further (`tickedFurther`), and
+ * the phases only the copy has after them. Nothing is marked touched: the copy is someone's branch, not the lane's own
+ * work, so it never makes a phase the lane's current one.
+ */
+export const newerPhases = (base: readonly PlanPhase[], copy: readonly PlanPhase[]): PlanPhase[] => {
+  const copyById = new Map(copy.map((phase) => [phase.id, phase]))
+  const baseIds = new Set(base.map((phase) => phase.id))
+  const inBaseOrder = base.map((basePhase) => {
+    const copied = copyById.get(basePhase.id)
+    return copied && tickedFurther(copied, basePhase) ? copied : basePhase
+  })
+  return [...inBaseOrder, ...copy.filter((phase) => !baseIds.has(phase.id))]
+}
+
 /** A phase read from the worktree is touched when its ticks differ from the base's, or the base lacks it. */
 const markTouched = (phase: PlanPhase, basePhase: PlanPhase | undefined): PlanPhase =>
   basePhase && sameTicks(phase, basePhase) ? phase : { ...phase, touched: true }

package/src/plans/plan-cache.ts

@@ -0,0 +1,28 @@
+import { type PlanLanguage, type PlanPhase, parsePlanPhases } from '../plan-format'
+import type { CacheRound } from '../shared/stat-cache'
+
+type ParsedPlan = { text: string; language: PlanLanguage; phases: PlanPhase[] }
+
+/** The phases of each plan by key, kept while the plan's text and language stay the same. */
+export type PlanCache = Map<string, ParsedPlan>
+
+export type PlanRound = CacheRound<ParsedPlan>
+
+/**
+ * `parsePlanPhases` of the text, asked again only when the text or the language under `key` changed since the cache
+ * saw it. The text decides, not a modification time: most plans come from the base ref, which has none.
+ */
+export const parsedPlanPhases = (
+  round: PlanRound | undefined,
+  key: string,
+  text: string,
+  language: PlanLanguage,
+): PlanPhase[] => {
+  if (!round) return parsePlanPhases(text, language)
+  round.used.add(key)
+  const kept = round.entries.get(key)
+  if (kept && kept.language === language && kept.text === text) return kept.phases
+  const phases = parsePlanPhases(text, language)
+  round.entries.set(key, { text, language, phases })
+  return phases
+}

package/src/plans/plan-heads.ts

@@ -0,0 +1,54 @@
+import type { BaseReader } from './git'
+import type { PullRequest } from './pull-requests'
+
+/** What choosing the heads needs of an open pull request: the herd's and the watcher's lists both carry it. */
+export type PlanPullRequest = Pick<PullRequest, 'number' | 'branch' | 'files'>
+
+/** An open pull request that changes a plan, with a reader of the files at its head. */
+export type PlanHead = { number: number; files: readonly string[]; read: BaseReader }
+
+/** Where the herd keeps the fetched heads of open pull requests: its own namespace, apart from branches and remotes. */
+const PULL_HEAD_NAMESPACE = 'refs/jackherd/pr'
+
+export const pullHeadRef = (number: number): string => `${PULL_HEAD_NAMESPACE}/${number}`
+
+/** The refspec that fetches a pull request's head from `refs/pull/<n>/head`, which GitHub keeps for forks too. */
+export const pullHeadRefspec = (number: number): string => `+refs/pull/${number}/head:${pullHeadRef(number)}`
+
+const changesPlan = (pullRequest: PlanPullRequest, planDirectory: string): boolean =>
+  (pullRequest.files ?? []).some((path) => path.startsWith(`${planDirectory}/`))
+
+/** The open pull requests that change a file under `planDirectory`, by number, so several heads merge in a fixed order. */
+export const planPullRequests = <Open extends PlanPullRequest>(
+  pullRequests: readonly Open[],
+  planDirectory: string,
+): Open[] =>
+  pullRequests
+    .filter((pullRequest) => changesPlan(pullRequest, planDirectory))
+    .sort((first, second) => first.number - second.number)
+
+/**
+ * `readerOf` asked once per ref, the reader kept for every later ask: build it once per read of all lanes, so a
+ * head costs one `git rev-parse` however many lanes read it.
+ */
+export const readerOncePerRef = (readerOf: (ref: string) => BaseReader): ((ref: string) => BaseReader) => {
+  const readers = new Map<string, BaseReader>()
+  return (ref) => {
+    const kept = readers.get(ref) ?? readerOf(ref)
+    readers.set(ref, kept)
+    return kept
+  }
+}
+
+/**
+ * The heads a lane's plans are read from besides the base: every plan pull request but the one of the lane's own
+ * branch, whose ticks the lane's worktree holds already.
+ */
+export const laneHeads = (
+  pullRequests: readonly PlanPullRequest[],
+  ownBranch: string | null,
+  readerOf: (ref: string) => BaseReader,
+): PlanHead[] =>
+  pullRequests
+    .filter(({ branch }) => branch !== ownBranch)
+    .map(({ number, files }) => ({ number, files: files ?? [], read: readerOf(pullHeadRef(number)) }))

package/src/plans/pull-requests.ts

@@ -14,6 +14,8 @@ export type PullRequest = {
   checks: ChecksState
   /** The names of the checks that failed, each once, in the rollup's order; empty while none failed. */
   failedChecks: string[]
+  /** The paths the pull request changes, as `gh` lists them (at most 100); absent when the answer has none. */
+  files?: string[]
 }
 
 /**
@@ -40,10 +42,11 @@ export type GhPullRequest = {
   headRefName: string
   isDraft: boolean
   statusCheckRollup: RollupEntry[] | null
+  files?: { path: string }[]
 }
 
 /** The fields `parsePullRequests` reads; pass them to `gh pr list --json`. */
-export const PULL_REQUEST_FIELDS = 'number,title,url,headRefName,isDraft,statusCheckRollup'
+export const PULL_REQUEST_FIELDS = 'number,title,url,headRefName,isDraft,statusCheckRollup,files'
 
 const RUN_IN_PATH = /^\/([\w.-]+)\/([\w.-]+)\/actions\/runs\/(\d+)(?:\/|$)/
 
@@ -131,6 +134,16 @@ const isPullRequestPage = (url: string, number: number, host: string): boolean =
   }
 }
 
+const isFileList = (value: unknown): boolean =>
+  Array.isArray(value) &&
+  value.every(
+    (file) => typeof file === 'object' && file !== null && typeof (file as { path?: unknown }).path === 'string',
+  )
+
+/** The `files` of a `gh` answer as plain paths, to spread into a pull request; nothing when the answer has none. */
+export const filePathsOf = ({ files }: Pick<GhPullRequest, 'files'>): { files?: string[] } =>
+  files ? { files: files.map(({ path }) => path) } : {}
+
 /** One entry of `gh pr list --json <PULL_REQUEST_FIELDS>` whose link is the pull request's own page on `host`. */
 export const isGhPullRequest = (value: unknown, host: string): value is GhPullRequest => {
   if (typeof value !== 'object' || value === null) return false
@@ -142,7 +155,8 @@ export const isGhPullRequest = (value: unknown, host: string): value is GhPullRe
     isPullRequestPage(candidate.url, candidate.number, host) &&
     typeof candidate.headRefName === 'string' &&
     typeof candidate.isDraft === 'boolean' &&
-    (candidate.statusCheckRollup === null || Array.isArray(candidate.statusCheckRollup))
+    (candidate.statusCheckRollup === null || Array.isArray(candidate.statusCheckRollup)) &&
+    (candidate.files === undefined || isFileList(candidate.files))
   )
 }
 
@@ -163,6 +177,7 @@ export const parsePullRequests = (json: string, host = 'github.com'): PullReques
     draft: pullRequest.isDraft,
     checks: checksOf(pullRequest.statusCheckRollup ?? []),
     failedChecks: failedChecksOf(pullRequest.statusCheckRollup ?? [], pullRequest.url).map(({ name }) => name),
+    ...filePathsOf(pullRequest),
   }))
 }
 
@@ -176,6 +191,12 @@ export const pullRequestsByBranch = (pullRequests: readonly PullRequest[]): Map<
 /** The selection key of a pull request row; two parts, so it never equals a three-part phase key. */
 export const pullRequestKey = (number: number): string => `pr:${number}`
 
+/**
+ * The key of a failed test's line under a pull request, by its place in the list: a click unfolds a cut name and folds
+ * it again. No colon and no `#`, so it never reads as a phase or task key.
+ */
+export const failedTestKey = (number: number, index: number): string => `failed>${number}>${index}`
+
 /** The link behind a row key, or null when the key is a phase or a pull request no longer open. */
 export const pullRequestUrl = (pullRequests: readonly PullRequest[], key: string): string | null =>
   pullRequests.find((pullRequest) => pullRequestKey(pullRequest.number) === key)?.url ?? null

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'
 }