jackherd 1.10.0 → 1.11.0

package/src/plans/snapshot.ts

@@ -17,8 +17,12 @@ import type { WaitingItem } from '../plan-format/waiting'
 import { dropUnused } from '../shared/stat-cache'
 import type { TaskSignal } from '../task-signals/types'
 import type { LaneAgent, LaneStatusSource } from '../terminal'
+import { isRestingAgent } from '../terminal/types'
+import { laneReportPath, readLaneReport } from '../watch/lane-report-file'
+import { restNote } from '../watch/lane-rest'
 import type { SourceTicket, WatchBadges, WatchHealth } from '../watch/plan-badges'
 import { readWatchReading } from '../watch/plan-badges-read'
+import type { SourceStatus } from '../watch/source-statuses'
 import { assignSignals, laneOfDirectory, type UnplannedTask } from './active-tasks'
 import { type AppointmentBlock, appointmentBlock } from './appointment-rows'
 import { boardRowsOf } from './board-rows'
@@ -33,8 +37,9 @@ import {
 } from './current-phase'
 import { activityTextOf, taskSignalsOf } from './current-task'
 import { errorText } from './error-text'
-import { type BaseReader, baseReaderOf, gitStatusOf, refExists } from './git'
+import { type BaseReader, baseReaderOf, gitStatusOf, lastChangeReaderOf, refExists } from './git'
 import type { PullRequestState } from './github'
+import { groomedDaysAgo } from './groomed'
 import {
   type Fallbacks,
   laneWorkOf,
@@ -48,17 +53,20 @@ import { laneSummary } from './lane-summary'
 import { boardRowTexts, laneTicketsOf, withoutTicketLinks } from './lane-tickets'
 import type { LaneView } from './layout'
 import { extractLinkChips } from './link-chips'
+import { type NextBlock, nextBlock } from './next-rows'
 import type { Options } from './options'
 import { laneModelsOf, type PhaseModelRecord } from './phase-models'
 import { readPhaseModels } from './phase-models-read'
 import { laneHeads, planPullRequests, readerOncePerRef } from './plan-heads'
-import { type PlannedPlan, plannedPlans } from './planned'
+import { markStale, type PlannedPlan, plannedPlans } from './planned'
 import type { PullRequest } from './pull-requests'
 import type { ReadCache } from './read-cache'
 import { type SentChip, sentChipsByLane } from './sent-files'
 import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from './settings'
 import { signalledTitle } from './signalled-phase'
 import { readAllSignals } from './signals-read'
+import { withSourcePrefix } from './source-prefix'
+import type { HerdSource, SourceBlock } from './source-rows'
 import type { SubagentActivity } from './subagents'
 import { readSubagentActivity, subagentSourceOf } from './subagents-read'
 import { boardTexts } from './texts'
@@ -115,8 +123,16 @@ export type Snapshot = {
   watchesTickets?: boolean
   /** What waits on the user's answer: the open rows of the board's section for it, from the checkout's board file. */
   waiting?: WaitingItem[]
-  /** The board's open appointments, read from the same board text as `waiting`, for the block under it. */
+  /** Whole days since the board's grooming (`groomedDaysAgo`); null when its appointment is missing. */
+  groomedDays?: number | null
+  /** The board's next section, read from the same board text as `waiting`, for the block under it. */
+  next?: NextBlock
+  /** The board's open appointments, read from the same board text as `waiting`, for the block under the next one. */
   appointments?: AppointmentBlock
+  /** The sources of `watch.sources` not marked `ticket`, from the watcher's state, for the block under the appointments. */
+  sourceBlock?: SourceBlock
+  /** The tone of each role, from the config, which `renderSnapshot` sets before it draws. */
+  tones?: PlansSettings['tones']
   /** What agents report doing that no lane takes: the coordinator's own, or a lane the board does not list. */
   unplaced?: UnplannedTask[]
 }
@@ -158,6 +174,7 @@ type Decorations = {
   phaseModels: readonly PhaseModelRecord[]
   sprintDirectory: string
   sentChips: ReadonlyMap<string | null, SentChip[]>
+  restNoteOf: (lane: string) => string | null
 }
 
 /** How full the agent's context is, null when the terminal gave no session or the session has no log. */
@@ -381,6 +398,12 @@ const withSentFiles = (view: LaneView, chips: ReadonlyMap<string | null, SentChi
   return found ? { ...view, sentFiles: found } : view
 }
 
+/** The view with what its resting lane waits on, read from the lane's report as the watcher reads it; as it was while the agent works. */
+const withRestNote = (view: LaneView, restNoteOf: Decorations['restNoteOf']): LaneView => {
+  const note = isRestingAgent(view.status.agent) ? restNoteOf(view.progress.lane.name) : null
+  return note === null ? view : { ...view, restNote: note }
+}
+
 /** Up to two names, then how many more: `a, b and 3 more`. */
 const namedWithMore = (names: readonly string[]): string => {
   const more = names.length - SHOWN_NAMES
@@ -496,34 +519,45 @@ const laneResultsOf = async (
 /** Each lane's view with its tickets, the watcher's badges, its phases' models and the files sent from it. */
 const decoratedViews = (
   results: readonly LaneResult[],
-  { reading, phaseModels, sprintDirectory, sentChips }: Decorations,
+  { reading, phaseModels, sprintDirectory, sentChips, restNoteOf }: Decorations,
 ): LaneView[] =>
   results.map((result) =>
-    withSentFiles(
-      withModels(
-        withBadges(withTickets(result, reading?.tickets ?? []), reading?.badges ?? {}),
-        phaseModels,
-        sprintDirectory,
+    withRestNote(
+      withSentFiles(
+        withModels(
+          withBadges(withTickets(result, reading?.tickets ?? []), reading?.badges ?? {}),
+          phaseModels,
+          sprintDirectory,
+        ),
+        sentChips,
       ),
-      sentChips,
+      restNoteOf,
     ),
   )
 
 /** The open phases no lane with an agent leads; none while the view shows one lane. */
+const withSourceTones = (statuses: readonly SourceStatus[], configured: PlansSettings['herdSources']): HerdSource[] =>
+  statuses.map((status) => ({ ...status, tone: configured.find(({ name }) => name === status.name)?.tone ?? null }))
+
 const plannedOf = (
   source: Source,
   plans: Record<string, string>,
   results: readonly LaneResult[],
   sprintDirectory: string,
+  now: number,
 ): PlannedPlan[] =>
   source.options.lane
     ? []
-    : plannedPlans({
-        plans,
-        lanes: results.map(({ view }) => ({ lane: view.progress.lane, agent: view.status.agent })),
-        sprintDirectory,
-        language: source.settings.planLanguage,
-      })
+    : markStale(
+        plannedPlans({
+          plans,
+          lanes: results.map(({ view }) => ({ lane: view.progress.lane, agent: view.status.agent })),
+          sprintDirectory,
+          language: source.settings.planLanguage,
+        }),
+        lastChangeReaderOf(source.root, baseRefOf(source.settings)),
+        now,
+      )
 
 /**
  * Reads the board, its plans and the lanes' state. `memories` holds, per lane, what the herd saw at the last read; it
@@ -553,10 +587,24 @@ export const loadSnapshot = async (
   if (parsed) dropUnused(parsed.entries, parsed.used)
   const listedPlans = await readListedPlans(source, base, sprintDirectory, markdown, fallbacks)
   const documentsPlans = Object.assign({}, listedPlans, ...results.map((result) => result.texts))
-  const { ticketSources } = settings
-  const watched = ticketSources.length > 0 || results.some(({ view }) => view.pullRequests.length > 0)
-  const reading = watched ? readWatchReading(root, now, ticketSources) : null
+  const { ticketSources, herdSources } = settings
+  const watched =
+    ticketSources.length > 0 || herdSources.length > 0 || results.some(({ view }) => view.pullRequests.length > 0)
+  const reading = watched
+    ? readWatchReading(
+        root,
+        now,
+        ticketSources,
+        undefined,
+        undefined,
+        herdSources.map(({ name }) => name),
+      )
+    : null
   const waitingRecords = readWaitingRecords(root)
+  const waiting = withSourcePrefix(
+    waitingItemsOf(liveBoard, settings.planLanguage, waitingRecords, now),
+    settings.sourceLabels,
+  )
   const sentChips = sentChipsByLane(waitingRecords.sent, worktrees, now)
   const notice = fallbacks.length > 0 ? fallbackNotice(fallbacks, baseRef, refExists(root, baseRef)) : null
   const unknownLaneTitle =
@@ -568,6 +616,8 @@ export const loadSnapshot = async (
       phaseModels: readPhaseModels(root),
       sprintDirectory,
       sentChips,
+      restNoteOf: (lane) =>
+        restNote(readLaneReport(laneReportPath(worktreeOf(root, settings, lane), lane))?.text ?? null),
     }),
     documents: {
       sprint: markdown,
@@ -575,7 +625,7 @@ export const loadSnapshot = async (
       laneOrder: [...laneSet.lanes, ...laneSet.unlisted].map((lane) => lane.name),
       lanes: board.lanes,
     },
-    planned: plannedOf(source, documentsPlans, results, sprintDirectory),
+    planned: plannedOf(source, documentsPlans, results, sprintDirectory, now),
     files: [sprintFile, ...results.flatMap((result) => result.files)],
     titles: new Map(
       results.flatMap(({ view, pane }) =>
@@ -584,8 +634,16 @@ export const loadSnapshot = async (
     ),
     errors: [...laneSet.errors, ...pullRequests.errors, ...(notice ? [notice] : [])],
     watch: reading?.health,
-    waiting: waitingItemsOf(liveBoard, settings.planLanguage, waitingRecords, now),
+    waiting,
+    groomedDays: groomedDaysAgo(liveBoard, settings.planLanguage, new Date(now)),
+    next: nextBlock(
+      liveBoard,
+      settings.planLanguage,
+      waiting.map(({ item }) => item),
+    ),
     appointments: appointmentBlock(liveBoard, settings.planLanguage, new Date(now)),
+    ...(reading?.sources ? { sourceBlock: { sources: withSourceTones(reading.sources, herdSources), now } } : {}),
+    tones: settings.tones,
     unplaced: unplacedOf(laneSet.sources, laneSet.lanes, Boolean(options.lane)),
     ...(ticketSources.length > 0 ? { watchesTickets: true } : {}),
   }

package/src/plans/source-asked.ts

@@ -0,0 +1,19 @@
+import type { WaitingItem } from '../plan-format/waiting'
+
+/** Whether the source `source` has an entry titled `title` that an open row of "Waiting for you" asks about. */
+export type AskedCheck = (source: string, title: string) => boolean
+
+const same = (left: string, right: string): boolean => left.trim().toLowerCase() === right.trim().toLowerCase()
+
+/**
+ * The check against the open rows: a row asks about an entry when its origin cell names the entry's source and its text
+ * contains the entry's title, in any case. The rows come from the board, whose text names the entry in words; no id links them.
+ */
+export const askedCheckOf =
+  (waiting: readonly WaitingItem[]): AskedCheck =>
+  (source, title) =>
+    title.trim() !== '' &&
+    waiting.some(
+      ({ origin, item }) =>
+        origin !== undefined && same(origin, source) && item.toLowerCase().includes(title.trim().toLowerCase()),
+    )

package/src/plans/source-prefix.ts

@@ -0,0 +1,17 @@
+import type { WaitingItem } from '../plan-format/waiting'
+
+/** By source name in lower case: what the herd puts before a row that came from the source, its `label` or else its name. */
+export type SourceLabels = Readonly<Record<string, string>>
+
+const lookup = (labels: SourceLabels, origin: string): string | undefined =>
+  Object.entries(labels).find(([name]) => name.toLowerCase() === origin.trim().toLowerCase())?.[1]
+
+/**
+ * The rows with `prefix` set on those whose origin cell names a source: the board row of a source's report then
+ * reads `Error log · Checkout: Resource Not Found` without a look at the plan. Any other row stays as it is.
+ */
+export const withSourcePrefix = (items: readonly WaitingItem[], labels: SourceLabels): WaitingItem[] =>
+  items.map((item) => {
+    const prefix = item.origin === undefined ? undefined : lookup(labels, item.origin)
+    return prefix === undefined ? item : { ...item, prefix }
+  })

package/src/plans/source-rows.ts

@@ -0,0 +1,188 @@
+import { TONE, type ToneName } from '../config/tones'
+import { padVisible } from '../terminal/text'
+import { textWidth } from '../terminal/width'
+import type { EntryStatus, SourceStatus } from '../watch/source-statuses'
+import { ASK_KIND } from './ask-target'
+import type { AskedCheck } from './source-asked'
+import { chevronOf } from './symbols'
+import type { BlockItem } from './waiting-click'
+
+/** A source's status with the tone its config names for the mark while its report is new; null where it names none. */
+export type HerdSource = SourceStatus & { tone?: ToneName | null }
+
+/** The sources block: the listed sources, and the clock (epoch milliseconds) their ages are counted against. */
+export type SourceBlock = { sources: HerdSource[]; now: number }
+
+/** What decides how the rows of the block look: the keys the user opened, and which entries a row of "Waiting for you" asks about. */
+export type SourceView = { expanded: ReadonlySet<string>; asked: AskedCheck }
+
+/** How many entries of an opened source show before `+<n> more`. */
+export const SOURCE_ENTRY_ROWS = 5
+
+const SOURCE_MARK = '●'
+const ENTRY_MARK = '•'
+const MORE_MARK = ' '
+const SEPARATOR = ' · '
+const ASKED_TEXT = '↑ asked'
+const MINUTE_MS = 60_000
+const HOUR_MS = 60 * MINUTE_MS
+const DAY_MS = 24 * HOUR_MS
+
+/** `just now`, `12 min ago`, `5 h ago` or `2 d ago`: the whole units since `since`, the largest that is at least one. */
+const agoOf = (since: number, now: number): string => {
+  const elapsed = Math.max(now - since, 0)
+  if (elapsed >= DAY_MS) return `${Math.floor(elapsed / DAY_MS)} d ago`
+  if (elapsed >= HOUR_MS) return `${Math.floor(elapsed / HOUR_MS)} h ago`
+  return elapsed >= MINUTE_MS ? `${Math.floor(elapsed / MINUTE_MS)} min ago` : 'just now'
+}
+
+const ranText = (ranAt: number | null, now: number): string =>
+  ranAt === null ? 'not run yet' : `ran ${agoOf(ranAt, now)}`
+
+const twoDigits = (value: number): string => String(value).padStart(2, '0')
+
+/** `11:11` for a time on the day of `now`, else the day and month before it, in the local time of the terminal. */
+const clockOf = (at: number, now: number): string => {
+  const date = new Date(at)
+  const time = `${twoDigits(date.getHours())}:${twoDigits(date.getMinutes())}`
+  return date.toDateString() === new Date(now).toDateString()
+    ? time
+    : `${twoDigits(date.getDate())}.${twoDigits(date.getMonth() + 1)}. ${time}`
+}
+
+const sourceKey = ({ name }: SourceStatus): string => `source>${name}`
+
+const entryKey = (name: string, { id }: EntryStatus): string => `source>${name}>${id}`
+
+/** The key in the herd's expanded set that shows every entry of the source, not the first five. */
+export const sourceMoreKey = (name: string): string => `more>source>${name}`
+
+const isUnaskedNew = (name: string, entry: EntryStatus, asked: AskedCheck): boolean =>
+  entry.isNew && !asked(name, entry.title)
+
+/**
+ * Red while the source fails; else the source's own tone or `newTone` while it has a new entry nobody asked about (for a
+ * source without entries: while its newest report is new); none otherwise.
+ */
+const toneOf = (source: HerdSource, newTone: ToneName, asked: AskedCheck): ToneName | undefined => {
+  if (source.failingSince !== null) return TONE.red
+  const hasNew =
+    source.entries.length > 0
+      ? source.entries.some((entry) => isUnaskedNew(source.name, entry, asked))
+      : source.latest?.isNew === true
+  return hasNew ? (source.tone ?? newTone) : undefined
+}
+
+const textOf = (source: HerdSource, now: number, expanded: boolean): string => {
+  const chevron = source.entries.length > 0 ? `${chevronOf(expanded)} ` : ''
+  const parts = [
+    ...(source.failingSince === null ? [] : [`failing since ${agoOf(source.failingSince, now)}`]),
+    ranText(source.ranAt, now),
+    ...(source.latest && source.entries.length === 0 ? [source.latest.title] : []),
+  ]
+  return `${chevron}${parts.join(SEPARATOR)}`
+}
+
+const headerOf = (
+  source: HerdSource,
+  view: SourceView,
+  now: number,
+  newTone: ToneName,
+  nameWidth: number,
+): BlockItem => {
+  const key = sourceKey(source)
+  const hasEntries = source.entries.length > 0
+  return {
+    key,
+    mark: SOURCE_MARK,
+    lead: padVisible(source.name, nameWidth),
+    text: textOf(source, now, view.expanded.has(key)),
+    url: hasEntries ? null : (source.latest?.url ?? null),
+    ask: null,
+    tone: toneOf(source, newTone, view.asked),
+    ...(hasEntries ? { toggle: key } : {}),
+  }
+}
+
+const entryToneOf = (
+  isAsked: boolean,
+  entry: EntryStatus,
+  source: HerdSource,
+  newTone: ToneName,
+): ToneName | undefined => {
+  if (isAsked) return TONE.grey
+  return entry.isNew ? (source.tone ?? newTone) : undefined
+}
+
+const entryTextOf = (entry: EntryStatus, now: number, isAsked: boolean): string =>
+  [entry.count === null ? '' : `${entry.count}×`, clockOf(entry.at, now), isAsked ? ASKED_TEXT : '']
+    .filter((part) => part !== '')
+    .join(' ')
+
+const entryItem = (
+  source: HerdSource,
+  entry: EntryStatus,
+  view: SourceView,
+  now: number,
+  newTone: ToneName,
+  titleWidth: number,
+): BlockItem => {
+  const isAsked = view.asked(source.name, entry.title)
+  const tone = entryToneOf(isAsked, entry, source, newTone)
+  return {
+    key: entryKey(source.name, entry),
+    mark: ENTRY_MARK,
+    lead: padVisible(entry.title, titleWidth),
+    text: entryTextOf(entry, now, isAsked),
+    url: entry.url,
+    ask: { kind: ASK_KIND.sourceEntry, source: source.name, title: entry.title },
+    ...(tone && { tone }),
+    ...(isAsked && { dim: true }),
+  }
+}
+
+const moreItem = (name: string, hidden: number, showsAll: boolean): BlockItem => ({
+  key: sourceMoreKey(name),
+  mark: MORE_MARK,
+  text: showsAll ? '▴ fewer' : `+${hidden} more`,
+  url: null,
+  ask: null,
+  toggle: sourceMoreKey(name),
+})
+
+const entryItems = (source: HerdSource, view: SourceView, now: number, newTone: ToneName): BlockItem[] => {
+  const showsAll = view.expanded.has(sourceMoreKey(source.name))
+  const shown = showsAll ? source.entries : source.entries.slice(0, SOURCE_ENTRY_ROWS)
+  const titleWidth = Math.max(0, ...shown.map(({ title }) => textWidth(title)))
+  const hidden = source.entries.length - SOURCE_ENTRY_ROWS
+  return [
+    ...shown.map((entry) => entryItem(source, entry, view, now, newTone, titleWidth)),
+    ...(hidden > 0 ? [moreItem(source.name, hidden, showsAll)] : []),
+  ]
+}
+
+const DEFAULT_VIEW: SourceView = { expanded: new Set(), asked: () => false }
+
+/**
+ * The rows of the sources block: per source one row with its name, when it ran, since when it fails and, for a source
+ * without entries, its newest report. A source with entries is folded to that row, and a click on it opens its entries
+ * (`view.expanded` holds its key): each with title, count and time, at most five and then `+<n> more`, a click on an
+ * entry opens its address, `[ask]` asks the coordinator to look at exactly that entry. An entry that a row of
+ * "Waiting for you" already asks about is dim and says `↑ asked`, and it does not make the source amber.
+ * `newTone` is the tone of the role `new`, which a source without its own tone wears while it has something new.
+ */
+export const sourceItems = (
+  sources: readonly HerdSource[],
+  now: number,
+  newTone: ToneName,
+  view: SourceView = DEFAULT_VIEW,
+): BlockItem[] => {
+  const nameWidth = Math.max(0, ...sources.map(({ name }) => textWidth(name)))
+  return sources.flatMap((source) => [
+    headerOf(source, view, now, newTone, nameWidth),
+    ...(view.expanded.has(sourceKey(source)) ? entryItems(source, view, now, newTone) : []),
+  ])
+}
+
+/** The keys of all rows: what the fold of the block remembers. */
+export const sourceKeys = (sources: readonly SourceStatus[]): string[] => sources.map(sourceKey)

package/src/plans/texts.ts

@@ -1,4 +1,5 @@
 import { STALE_ACTIVITY_MINUTES } from './lane-summary'
+import { STALE_PLAN_DAYS } from './planned'
 import { CHECK_NAME_LENGTH, CHECKS, type ChecksState, type PullRequest } from './pull-requests'
 import { shownWithMore } from './shown-with-more'
 import { MODEL_MARK, NO_AGENT_WORD, PHASE_COUNT } from './symbols'
@@ -26,6 +27,13 @@ export type PlanTexts = {
   /** The heads of the blocks on top of the herd. */
   waitingHeading: string
   appointmentHeading: string
+  sourceHeading: string
+  nextHeading: string
+  /** On a resting lane's line: the label before its starts-after cell, and the line for a lane without any reason. */
+  restAfter: string
+  restNoReason: string
+  /** After the head of the next block when the board's section holds no line. */
+  nextEmpty: string
   notInPlan: string
   /** Before a task an agent reports that no task of the plan names. */
   now: string
@@ -34,9 +42,13 @@ export type PlanTexts = {
   /** 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
+  /** The line above the listed ticked tasks of a phase; a click or `a` folds them again. */
+  tickedFold: (count: number) => string
   draft: string
   privateLink: string
   planned: (phases: number, plans: number) => string
+  /** The head of the planned section in the herd: `planned · 3 plans, next:`. */
+  plannedHead: (plans: number) => string
   phaseTally: (done: number, total: number) => string
   herd: HerdTexts
   checks: Record<ChecksState, string>
@@ -48,6 +60,9 @@ export type PlanTexts = {
   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 footer line after `[done]` closed `subject`, and the one with the reason when it could not. */
+  closed: (subject: string) => string
+  notClosed: (reason: string) => string
 }
 
 /** The words of the watcher's badges and of the header notice when they are missing. */
@@ -91,11 +106,17 @@ export const TEXTS: PlanTexts = {
   noRow: 'no row in lanes',
   waitingHeading: 'Waiting for you',
   appointmentHeading: 'Appointments',
+  sourceHeading: 'Sources',
+  nextHeading: 'Next',
+  restAfter: 'after:',
+  restNoReason: 'idle · no reason',
+  nextEmpty: 'nothing queued, groom the board',
   notInPlan: 'not in the plan',
   now: 'now:',
   subagent: 'Subagent:',
   allButDocs: ALL_BUT_DOCS,
   tickedSummary: (count) => `${count} ticked · click or a lists them`,
+  tickedFold: (count) => `${count} ticked · click or a folds them`,
   draft: 'draft · ',
   privateLink: 'private',
   phaseTally: (done, total) => (total > 0 ? `${done}/${total} ph` : ''),
@@ -108,25 +129,29 @@ export const TEXTS: PlanTexts = {
   },
   planned: (phases, plans) =>
     `planned (${phases} ${phases === 1 ? 'phase' : 'phases'} in ${plans} ${plans === 1 ? 'plan' : 'plans'})`,
+  plannedHead: (plans) => `planned · ${plans} ${plans === 1 ? 'plan' : 'plans'}, next:`,
   checks: {
     [CHECKS.passed]: '✓ checks',
     [CHECKS.failed]: '✗ checks',
     [CHECKS.pending]: '… checks',
     [CHECKS.none]: 'no checks',
   },
-  hint: '↑↓ select  →← open  a ticked tasks  s html  q quit  ? help',
+  hint: '↑↓ select  →← open  a/click 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 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`,
+    `▸ ▾ 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 or a click on its ▸ n ticked line lists the ticked checkboxes of an open phase one by one, a or a click on its ▾ line folds them · 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)',
+    `▌ 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; [done] closes the row: a board row gets its status, a sent file its record) · 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; [done] closes the row, [run] asks the coordinator to run it now, [move] to ask you for a new time) · 1 2 3 = Next, the board lines to do next · ● Sources = the watcher’s sources that are no tickets: when each ran and its newest report, the mark amber while that report is under a day old and red while the source fails (click on a row: opens the entry) · planned = the open phases no lane works on, the next one per plan; stale? = its plan file was not changed on the base branch for ${STALE_PLAN_DAYS} days`,
     '⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main',
+    '❯ and a light background = the row under the mouse or the arrows, on every clickable row · enter on a block row asks, opens or expands it and never presses [done] · [xx] in square brackets = a click does something, bold under the mouse',
   ],
   notAsked: (reason) => `no coordinator to ask: ${reason}`,
   asked: (name, subject) => `asked ${name} for ${subject}`,
+  closed: (subject) => `closed ${subject}`,
+  notClosed: (reason) => `not closed: ${reason}`,
 }
 
 /** The mark of a running lane the board has no row for; null for a lane it lists. */

package/src/plans/tones.ts

@@ -0,0 +1,30 @@
+import { DEFAULT_TONES, TONE, type ToneName, type ToneRole } from '../config/tones'
+import { paint } from '../terminal/text'
+
+const TONE_PAINT: Record<ToneName, (text: string) => string> = {
+  [TONE.amber]: paint.yellow,
+  [TONE.teal]: paint.teal,
+  [TONE.grey]: paint.dim,
+  [TONE.red]: paint.red,
+  [TONE.green]: paint.green,
+  [TONE.blue]: paint.blue,
+  [TONE.magenta]: paint.magenta,
+}
+
+let palette: Record<ToneRole, ToneName> = DEFAULT_TONES
+
+/**
+ * Sets the tone of each role for the screens drawn from now on. The herd calls it once per frame with the config's
+ * tones, so the layout reads one palette and no function of it takes the colours as a parameter.
+ */
+export const setTones = (tones: Record<ToneRole, ToneName>): void => {
+  palette = tones
+}
+
+export const paintOfTone = (name: ToneName): ((text: string) => string) => TONE_PAINT[name]
+
+/** The paint of a role in the palette set last. */
+export const paintOfRole = (role: ToneRole): ((text: string) => string) => TONE_PAINT[palette[role]]
+
+/** The tone name of a role in the palette set last. */
+export const toneOfRole = (role: ToneRole): ToneName => palette[role]

package/src/plans/view.ts

@@ -1,17 +1,19 @@
 import { ARTIFACT_LINK_KIND } from '../config/link-kinds'
+import { DEFAULT_TONES } from '../config/tones'
 import { fit, plainText } from '../terminal/text'
 import { renderSelected, type Screen } from './layout'
 import type { Options } from './options'
 import { laneSelection, overviewSelection, type Selection } from './selection'
 import type { Snapshot } from './snapshot'
+import { setTones } from './tones'
 
 const DEFAULT_WIDTH = 100
 const CURSOR_HOME = '\x1b[H'
 const CLEAR_LINE_END = '\x1b[K'
 const CLEAR_BELOW = '\x1b[J'
 
-export const TERMINAL_ON = '\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1006h'
-export const TERMINAL_OFF = '\x1b[?1006l\x1b[?1000l\x1b[?25h\x1b[?1049l'
+export const TERMINAL_ON = '\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1003h\x1b[?1006h'
+export const TERMINAL_OFF = '\x1b[?1006l\x1b[?1003l\x1b[?1000l\x1b[?25h\x1b[?1049l'
 
 /** One column short of the pane: a line filling the last column makes some terminals wrap it. */
 export const paneWidth = (): number => (process.stdout.columns ?? (Number(process.env.COLUMNS) || DEFAULT_WIDTH)) - 1
@@ -32,6 +34,7 @@ export const renderSnapshot = (
   width: number,
   locale: string,
 ): Screen => {
+  setTones(snapshot.tones ?? DEFAULT_TONES)
   const screen = renderSelected(
     {
       title: snapshot.title,
@@ -41,7 +44,10 @@ export const renderSnapshot = (
       watch: snapshot.watch,
       watchesTickets: snapshot.watchesTickets,
       awaiting: snapshot.waiting,
+      groomedDays: snapshot.groomedDays,
+      next: snapshot.next,
       appointments: snapshot.appointments,
+      sourceBlock: snapshot.sourceBlock,
       unplaced: snapshot.unplaced,
     },
     selection,