jackherd 1.15.2 → 1.16.0

package/src/plans/layout.ts

@@ -98,7 +98,17 @@ import {
 import type { SentChip } from './sent-files'
 import { shownWithMore } from './shown-with-more'
 import { askedCheckOf } from './source-asked'
-import { type SourceBlock, type SourceSummary, sourceItems, sourceSummaries } from './source-rows'
+import {
+  entryBlockItems,
+  entryBlockSources,
+  type HerdSource,
+  type SourceBlock,
+  type SourceSummary,
+  sourceItems,
+  sourceMoreKey,
+  sourceSummaries,
+  statusOnly,
+} from './source-rows'
 import { chevronOf, LESS_MARK, NO_AGENT_SYMBOL, statusSymbol, statusWord, TURN_MARK } from './symbols'
 import { BADGE_TEXTS, type BadgeTexts, checksText, foldedChecksText, laneMarkText, TEXTS } from './texts'
 import { paintOfRole, paintOfTone, toneOfRole } from './tones'
@@ -177,14 +187,16 @@ export type OverviewView = {
 
 /**
  * The drawn screen: a fixed header and footer around a body that scrolls; body lines and targets count from the body's
- * top. `yourTurnBlock` and `sourceBlock` are what a click on these blocks is matched against, null while the block is
- * not drawn.
+ * top. `yourTurnBlock`, `entryBlocks` and `sourceBlock` are what a click on these blocks is matched against, null (or
+ * no entry block) while the block is not drawn.
  */
 export type Screen = {
   header: string[]
   body: Frame
   footer: string[]
   yourTurnBlock: BlockHit | null
+  /** The blocks of the sources that show their entries, in their order under "Your turn". */
+  entryBlocks: BlockHit[]
   sourceBlock: BlockHit | null
   /** Every clickable row by the screen line it starts on (header lines first, then the body unscrolled): what the mouse and the keys land on. */
   focusHits: FocusHit[]
@@ -227,10 +239,12 @@ type TopBlock = {
   hidden: number
   expanded: boolean
   rows: BlockRow[]
+  /** The mark in front of the name in place of the chevron, for a block that does not fold; absent for the chevron. */
+  headMark?: string
 }
 
 /** What the head of a block says: its name, its count, its balance and the paint of the count. */
-type BlockHeadParts = Pick<TopBlock, 'name' | 'count' | 'balance' | 'countPaint'>
+type BlockHeadParts = Pick<TopBlock, 'name' | 'count' | 'balance' | 'countPaint' | 'headMark'>
 
 /** The blocks on top of the herd one under the other: their lines below the title, and the hit of each drawn block. */
 type BlockStack = { lines: string[]; hits: (BlockHit | null)[] }
@@ -903,24 +917,57 @@ const SUBAGENT_ACTIVITY_INDENT = '  '
 /** How long a subagent's name may grow before its action, so a narrow pane cuts the name and keeps the action. */
 const SUBAGENT_NAME_CELLS = 28
 
-/** One dim line of activity behind `indent`, cut to `width`; the cut is made before the paint, on plain text. */
-const activityLine = (indent: string, text: string, width: number): string =>
-  paint.dim(fit(`${indent}${ACTIVITY_MARK} ${text}`, width))
+/** The key of a lane's activity line, flipped in `expanded`. */
+const laneActivityKey = (lane: string): string => `activity>${lane}`
+
+/**
+ * The key of a subagent's activity line, by its label: a subagent that moves up when another ends keeps its own state,
+ * and the key is no child of the lane's, so folding one leaves the other.
+ */
+const subagentActivityKey = (lane: string, label: string): string => `subagent-activity>${lane}>${label}`
+
+/**
+ * One dim line of activity behind `indent`, cut to the pane on plain text before the paint. A cut line is a row: a
+ * click unfolds it over several lines, the text hanging under its first word, and a second click folds it; a line
+ * that fits is no click target.
+ */
+const activityFrame = (
+  key: string,
+  indent: string,
+  text: string,
+  { state, width }: { state: Selection; width: number },
+): Frame => {
+  const head = `${indent}${ACTIVITY_MARK} `
+  const cut = textWidth(`${head}${text}`) > width
+  const lines =
+    cut && state.expanded.has(key)
+      ? wrap(text, Math.max(width - textWidth(head), 1)).map((line, index) =>
+          index === 0 ? `${head}${line}` : `${' '.repeat(textWidth(head))}${line}`,
+        )
+      : [fit(`${head}${text}`, width)]
+  const dimmed = lines.map((line) => paint.dim(line))
+  return cut ? rowFrame(key, dimmed, [], { state, width }) : textFrame(dimmed)
+}
 
 /**
  * The last action of a working lane's agent and of each of its running subagents, one dim line each, under the lane
  * line in the column of its children. None while the lane does not work, or without a source for it.
  */
-const activityLines = ({ activity, status }: LaneView, width: number): string[] => {
+const activityFrames = (
+  { activity, status, progress }: LaneView,
+  context: { state: Selection; width: number },
+): Frame[] => {
   if (!activity || status.agent !== AGENT_STATUS.working) return []
+  const lane = progress.lane.name
   const indent = ' '.repeat(LANE_HEAD_CELLS)
   return [
-    ...(activity.lane === null ? [] : [activityLine(indent, activity.lane, width)]),
+    ...(activity.lane === null ? [] : [activityFrame(laneActivityKey(lane), indent, activity.lane, context)]),
     ...activity.subagents.map(({ label, description, line }) =>
-      activityLine(
+      activityFrame(
+        subagentActivityKey(lane, label),
         `${indent}${SUBAGENT_ACTIVITY_INDENT}`,
         `${ellipsize(description ?? label, SUBAGENT_NAME_CELLS)}: ${line}`,
-        width,
+        context,
       ),
     ),
   ]
@@ -950,8 +997,7 @@ const laneBlock = (
   const open = isLaneOpen(state, view.progress.lane.name, view.status.agent)
   const lines = laneLines(view, open, { width, taskStyle }, columns, reason)
   const lane = rowFrame(laneKey(view.progress.lane.name), lines, [], context)
-  const activity = activityLines(view, width)
-  const row = activity.length > 0 ? joinFrames([lane, textFrame(activity)]) : lane
+  const row = joinFrames([lane, ...activityFrames(view, { state, width })])
   if (!open) return row
   const inner = narrower(context, LANE_HEAD_CELLS)
   const head = {
@@ -1085,9 +1131,13 @@ const blockBar = (): string => ' '
  * above the block; `▸ <name> · <n>  <balance>` while folded. The count (in `countPaint` while it is more than 0) is
  * left out for a block without one; the balance comes painted.
  */
-const blockHead = ({ name, count, balance, countPaint }: BlockHeadParts, open: boolean, width: number): string => {
+const blockHead = (
+  { name, count, balance, countPaint, headMark }: BlockHeadParts,
+  open: boolean,
+  width: number,
+): string => {
   const counted = count === null ? '' : ` ${ITEM_SEPARATOR} ${count > 0 ? countPaint(String(count)) : count}`
-  const lead = `${paint.dim(chevronOf(open))} ${name}${counted}${balance ? `  ${balance}` : ''}`
+  const lead = `${paint.dim(headMark ?? chevronOf(open))} ${name}${counted}${balance ? `  ${balance}` : ''}`
   if (!open) return fit(lead, width)
   const cut = fit(lead, Math.max(width - 2, 1))
   return `${cut} ${paint.dim(RULE.repeat(Math.max(width - visibleLength(cut) - 1, 0)))}`
@@ -1226,11 +1276,12 @@ const sourceSummaryText = (summaries: readonly SourceSummary[]): string =>
  * fails, and a source's entries under it once opened.
  */
 const sourceLines = (
-  { sources, now }: SourceBlock,
+  { sources: listed, now }: SourceBlock,
   awaiting: readonly WaitingItem[],
   state: Selection,
   width: number,
 ): BlockLines => {
+  const sources = listed.map(statusOnly)
   const shown = state.expanded.has(SOURCE_MORE_KEY) ? sources : sources.slice(0, SHOWN_BLOCK_ROWS)
   const asked = askedCheckOf(awaiting)
   const newTone = toneOfRole(TONE_ROLE.new)
@@ -1258,6 +1309,69 @@ const sourceLinesOf = (
 ): BlockLines | null =>
   sourceBlock && sourceBlock.sources.length > 0 ? sourceLines(sourceBlock, awaiting, state, width) : null
 
+/**
+ * How many entry rows all blocks of entries show together while folded: one calendar keeps the five of the other
+ * blocks, a second one takes from the same five, so the head of the herd, which does not scroll, leaves the lanes room.
+ */
+const ENTRY_BLOCK_ROW_BUDGET = SHOWN_BLOCK_ROWS
+
+/**
+ * The rows each block of entries shows while folded, in the order of the sources: the shared budget, with one row kept
+ * for each block after it, and at least one row per block, so a block past the budget still shows its first entry; a
+ * block with fewer entries than its share leaves the rest to the blocks after it. More blocks than the budget take one
+ * row each, past the budget.
+ */
+const entryRowShares = (counts: readonly number[], budget: number): number[] => {
+  let left = budget
+  return counts.map((count, index) => {
+    const share = Math.min(count, Math.max(left - (counts.length - index - 1), 1))
+    left -= share
+    return share
+  })
+}
+
+/** A source with a block of its own, the clock its times are counted against and the rows it shows while folded. */
+type EntryBlock = { source: HerdSource; now: number; share: number }
+
+/**
+ * The block of a source that shows its entries: always open, headed by its label (else its name) without a chevron,
+ * its `share` of entries and `+<n>` for the rest, which opens all of them and folds them again as in the other blocks.
+ * The head is no click target; an entry with an address opens it.
+ */
+const entryBlockLines = ({ source, now, share }: EntryBlock, state: Selection, width: number): BlockLines => {
+  const moreKey = sourceMoreKey(source.name)
+  const expanded = state.expanded.has(moreKey)
+  const hidden = source.entries.length - share
+  const block: TopBlock = {
+    name: source.label ?? source.name,
+    count: null,
+    balance: '',
+    markPaint: paint.dim,
+    focused: (key) => isFocused(state, key),
+    allBold: (key) => buttonsAllBold(state, key),
+    countPaint: (text) => text,
+    moreKey: hidden > 0 ? moreKey : null,
+    hidden,
+    expanded,
+    rows: allBlockRows(entryBlockItems(source, now, expanded ? source.entries.length : share), new Set(), width),
+    headMark: ' ',
+  }
+  const { lines, hit } = openBlockLines(block, '', width)
+  return { open: true, lines, hit: { rows: hit.rows, moreKey: hit.moreKey } }
+}
+
+const entryBlocksOf = (sourceBlock: SourceBlock | undefined, state: Selection, width: number): BlockLines[] => {
+  if (!sourceBlock) return []
+  const sources = entryBlockSources(sourceBlock.sources)
+  const shares = entryRowShares(
+    sources.map(({ entries }) => entries.length),
+    ENTRY_BLOCK_ROW_BUDGET,
+  )
+  return sources.map((source, index) =>
+    entryBlockLines({ source, now: sourceBlock.now, share: shares[index] ?? 0 }, state, width),
+  )
+}
+
 /**
  * The blocks one under the other, `offset` lines below the top of the screen, a blank line after each, so one stands
  * between neighbours and one between the last and the lanes. An absent block (null) takes no line and has no hit.
@@ -1429,7 +1543,9 @@ export const renderScreen = (
   const nowLines = unplaced.map((task) => nowLine(task, width, taskStyle))
   const above = nowLines.length > 0 ? [titleLine, rule(width), ...nowLines] : [titleLine]
   const listed = sourceLinesOf(sourceBlock, awaiting, state, width)
-  const stack = stackBlocks([turn, listed], above.length)
+  const entryBlocks = entryBlocksOf(sourceBlock, state, width)
+  const stack = stackBlocks([turn, ...entryBlocks, listed], above.length)
+  const sourcesSlot = 1 + entryBlocks.length
   const sections = [
     ...(active.length > 0 ? [lanesFrame(active, turnRowsOf, { state, width, badgeTexts, taskStyle })] : []),
     ...(waiting.length > 0 ? [waitingFrame(waiting, state, width)] : []),
@@ -1448,7 +1564,8 @@ export const renderScreen = (
   const body = { ...plainBody, lines: emphasisedAt(plainBody.lines, plainHeader.length, focusHits, state, width) }
   return {
     yourTurnBlock: stack.hits[0],
-    sourceBlock: stack.hits[1],
+    entryBlocks: stack.hits.slice(1, sourcesSlot).filter((hit) => hit !== null),
+    sourceBlock: stack.hits[sourcesSlot],
     focusHits: state.showLegend ? focusHits.filter(({ line }) => line < plainHeader.length) : focusHits,
     rowKeys: [...blockHits.map(({ key }) => key), ...targetKeys(body.targets)],
     header,

package/src/plans/live.ts

@@ -35,6 +35,7 @@ import { REFRESH_PACE } from './refresh-pace'
 import { TAKEN_OVER_CODE, TAKEOVER_SIGNAL } from './restart-decision'
 import { closeRow } from './row-actions'
 import { blockRowByKey, type HoverScreen, hoveredSelection, rehovered, withoutHover } from './row-focus'
+import { DONE_KIND, type DoneTarget } from './row-targets'
 import {
   applyClick,
   inputOutcome,
@@ -76,6 +77,7 @@ import {
   startSelection,
 } from './view'
 import { type BlockClick, type BlockHit, blockClick, blockHeadClick, mainClickOf } from './waiting-click'
+import type { TurnRow, YourTurn } from './your-turn'
 
 /**
  * Where the herd's reads come from: its own reader, or the read the watcher publishes for every herd of the board
@@ -97,6 +99,8 @@ type Live = {
   errors: string[]
   /** One footer line about the last action of the person, such as where the sprint page was written; cleared by the next key. */
   notice: string | null
+  /** What a `[done]` closed, left out of "Your turn" from the click until a read no longer holds its row. */
+  closing: DoneTarget[]
   reported: Map<string, string | null>
   /** The snapshot as read, without the plan chips; `snapshot` is this plus the chips of the page. */
   read: Snapshot | null
@@ -123,6 +127,39 @@ type Live = {
 
 const QUIT_KEYS = new Set(['\x03', 'q'])
 
+/** Whether `row` of "Your turn" is what `target` closes: a record by its id, a board row or an appointment by its cells. */
+const isClosedBy = (target: DoneTarget, { waiting, appointment }: TurnRow): boolean => {
+  switch (target.kind) {
+    case DONE_KIND.record:
+      return waiting?.id === target.id
+    case DONE_KIND.boardRow:
+      return waiting?.id === undefined && waiting?.since === target.since && waiting.item === target.item
+    case DONE_KIND.appointment:
+      return appointment?.when === target.when && appointment.action === target.action
+  }
+}
+
+const isClosing = (closing: readonly DoneTarget[], row: TurnRow): boolean =>
+  closing.some((target) => isClosedBy(target, row))
+
+/** "Your turn" without the rows `closing` names, so a closed row leaves at the click, not at the next read. */
+export const withoutClosing = (turn: YourTurn, closing: readonly DoneTarget[]): YourTurn => {
+  if (closing.length === 0) return turn
+  const open = (rows: readonly TurnRow[]) => rows.filter((row) => !isClosing(closing, row))
+  return { now: open(turn.now), planned: open(turn.planned) }
+}
+
+/** The closings a read still holds a row of; one whose row the read no longer holds is closed on the board as well. */
+export const pendingClosings = (turn: YourTurn | undefined, closing: readonly DoneTarget[]): DoneTarget[] => {
+  const rows = turn ? [...turn.now, ...turn.planned] : []
+  return closing.filter((target) => rows.some((row) => isClosedBy(target, row)))
+}
+
+const withClosingLeftOut = (snapshot: Snapshot, closing: readonly DoneTarget[]): Snapshot =>
+  snapshot.yourTurn && closing.length > 0
+    ? { ...snapshot, yourTurn: { ...snapshot.yourTurn, turn: withoutClosing(snapshot.yourTurn.turn, closing) } }
+    : snapshot
+
 /** The sidebar titles that differ from the ones last reported, in the order of `titles`; null clears one. */
 export const changedTitles = (
   titles: ReadonlyMap<string, string | null>,
@@ -171,7 +208,7 @@ const renderContextOf = (live: Live): RenderContext => ({
 
 /** The screen for the current state, with the window scrolled to keep the cursor in view. */
 const renderLive = (live: Live, snapshot: Snapshot): { screen: Screen; top: number } => {
-  const screen = renderSnapshot(snapshot, renderContextOf(live))
+  const screen = renderSnapshot(withClosingLeftOut(snapshot, live.closing), renderContextOf(live))
   return { screen, top: windowTop(live.view, screen.body.cursorLine, screen.body.lines.length, bodyRows(screen)) }
 }
 
@@ -236,7 +273,7 @@ const followShimmer = (live: Live, prepared: PreparedShimmer) => {
 const drawHover = (live: Live) => {
   live.frame = null
   if (!live.snapshot) return
-  live.plain ??= renderUnfocused(live.snapshot, renderContextOf(live))
+  live.plain ??= renderUnfocused(withClosingLeftOut(live.snapshot, live.closing), renderContextOf(live))
   const laid = focusedScreen(live.plain, live.view.selection, paneWidth(), agentOfSnapshot(live.snapshot))
   if (laid === null) redraw(live)
   else write(live, laid, live.view.top)
@@ -311,6 +348,7 @@ const takeRead = (live: Live, outcome: ReadOutcome, notes: readonly string[]): b
   )
   live.view = { ...live.view, selection: folded }
   live.snapshot = next
+  live.closing = pendingClosings(next.yourTurn?.turn, live.closing)
   live.errors = [...next.errors, ...notes, ...reportTitles(live.source, next.titles, live.reported)]
   return redraw(live)
 }
@@ -474,12 +512,14 @@ const applyBlockClick = (live: Live, outcome: BlockClick): void => {
     return
   }
   if ('done' in outcome) {
-    live.notice = closeRow(outcome.done, {
+    const { closed, notice } = closeRow(outcome.done, {
       sprintFile: live.source.sprintFile,
       language: live.source.settings.planLanguage,
       now: new Date(),
       closeRecords: (ids) => closeWaiting(live.source.root, ids, Date.now()),
     })
+    if (closed) live.closing = [...live.closing, outcome.done]
+    live.notice = notice
     return
   }
   const reason = openInBrowser(outcome.open)
@@ -487,14 +527,15 @@ const applyBlockClick = (live: Live, outcome: BlockClick): void => {
 }
 
 /**
- * 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
+ * A plain click on a block on top of the herd, matched against `hit` as it was drawn: the head of `block` folds or
+ * opens it (a block of entries, `block` null, has no such head), a
  * cut-off row expands, a file or Artifact opens, a button asks the coordinator or closes the row; the failure or the
  * result shows in the footer.
  */
-const clickBlock = (live: Live, block: TopBlockId, hit: BlockHit | null, input: string): boolean => {
+const clickBlock = (live: Live, block: TopBlockId | null, hit: BlockHit | null, input: string): boolean => {
   const mouse = parseMouse(input)
   if (!mouse || !hit) return false
-  if (blockHeadClick(hit.firstLine - 1, mouse)) {
+  if (block !== null && blockHeadClick(hit.firstLine - 1, mouse)) {
     live.view = {
       ...live.view,
       selection: applyClick(live.view.selection, topBlockHeadKey(block)),
@@ -533,7 +574,11 @@ const activateBlockRow = (live: Live, screen: Screen, input: string): boolean =>
   return true
 }
 
-const blocksOf = ({ yourTurnBlock, sourceBlock }: Screen): (BlockHit | null)[] => [yourTurnBlock, sourceBlock]
+const blocksOf = ({ yourTurnBlock, entryBlocks, sourceBlock }: Screen): (BlockHit | null)[] => [
+  yourTurnBlock,
+  ...entryBlocks,
+  sourceBlock,
+]
 
 const handleInput = (live: Live, input: string) => {
   const { snapshot, screen } = live
@@ -556,6 +601,7 @@ const handleInput = (live: Live, input: string) => {
   }
   if (
     clickBlock(live, TOP_BLOCK.yourTurn, screen.yourTurnBlock, input) ||
+    screen.entryBlocks.some((hit) => clickBlock(live, null, hit, input)) ||
     clickBlock(live, TOP_BLOCK.sources, screen.sourceBlock, input)
   ) {
     redraw(live)
@@ -594,6 +640,7 @@ export const runLive = (source: Source, key: string | null = null): void => {
     view: { selection: overviewSelection(), top: 0, follow: true },
     errors: [],
     notice: null,
+    closing: [],
     reported: new Map(),
     read: null,
     whole: null,

package/src/plans/row-actions.ts

@@ -16,9 +16,16 @@ export type CloseDependencies = {
   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')
+/** Whether the row was closed, and the footer line that says so or why not. */
+export type CloseResult = { closed: boolean; notice: string }
+
+const closedAs = (subject: string): CloseResult => ({ closed: true, notice: TEXTS.closed(subject) })
+
+const notClosed = (reason: string): CloseResult => ({ closed: false, notice: TEXTS.notClosed(reason) })
+
+const closeRecord = (id: string, { closeRecords }: CloseDependencies): CloseResult => {
+  if (!isQuestionId(id)) return notClosed('not a record id')
+  return closeRecords([id]) > 0 ? closedAs(`record ${id}`) : notClosed('record not found or closed already')
 }
 
 const closedBoard = (target: DoneTarget, board: string, { language, now }: CloseDependencies): string | null => {
@@ -31,22 +38,22 @@ const subjectOfRow = (target: DoneTarget): string => {
   return target.kind === DONE_KIND.appointment ? `appointment ${boardRowKey(target.when, target.action)}` : ''
 }
 
-const closeBoardRow = (target: DoneTarget, dependencies: CloseDependencies): string => {
+const closeBoardRow = (target: DoneTarget, dependencies: CloseDependencies): CloseResult => {
   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')
+    if (closed === null) return notClosed('row not found in the board')
     writeFileSync(dependencies.sprintFile, closed)
-    return TEXTS.closed(subjectOfRow(target))
+    return closedAs(subjectOfRow(target))
   } catch (error) {
-    return TEXTS.notClosed(errorText(error))
+    return 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.
+ * status cell. Returns whether it closed and 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 =>
+export const closeRow = (target: DoneTarget, dependencies: CloseDependencies): CloseResult =>
   target.kind === DONE_KIND.record ? closeRecord(target.id, dependencies) : closeBoardRow(target, dependencies)

package/src/plans/snapshot.ts

@@ -635,15 +635,20 @@ const decoratedViews = (
     ),
   )
 
-/** Each source with the tone and the label its config gives it. */
+/** Each source with the tone, the label and the `show` its config gives it. */
 const withSourceStyle = (
   statuses: readonly SourceStatus[],
   { herdSources, sourceLabels }: HerdSourceSettings,
 ): HerdSource[] =>
   statuses.map((status) => {
     const label = sourceLabels[status.name]
-    const tone = herdSources.find(({ name }) => name === status.name)?.tone ?? null
-    return { ...status, tone, ...(label === undefined ? {} : { label }) }
+    const config = herdSources.find(({ name }) => name === status.name)
+    return {
+      ...status,
+      tone: config?.tone ?? null,
+      ...(label === undefined ? {} : { label }),
+      ...(config?.show === undefined ? {} : { show: config.show }),
+    }
   })
 
 /**

package/src/plans/source-rows.ts

@@ -2,6 +2,7 @@ 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 { SOURCE_SHOW, type SourceShow } from '../watch/sources'
 import { ASK_KIND } from './ask-target'
 import type { AskedCheck } from './source-asked'
 import { chevronOf } from './symbols'
@@ -9,9 +10,10 @@ 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) and
- * the label its config gives it, absent where it gives none.
+ * the label its config gives it, absent where it gives none, and `show` where it asks for its entries in a block of
+ * their own.
  */
-export type HerdSource = SourceStatus & { tone?: ToneName | null; label?: string }
+export type HerdSource = SourceStatus & { tone?: ToneName | null; label?: string; show?: SourceShow }
 
 /** One source in the line of the folded sources block: what it says and the tone it wears, none for dim. */
 export type SourceSummary = { text: string; tone?: ToneName }
@@ -179,6 +181,37 @@ const entryItems = (source: HerdSource, view: SourceView, now: number, newTone:
   ]
 }
 
+/** Whether the source asks for its entries in a block of their own. */
+export const showsEntries = (source: HerdSource): boolean => source.show === SOURCE_SHOW.entries
+
+/** The sources that have a block of their own: those that ask for it and have entries; an empty run draws none. */
+export const entryBlockSources = (sources: readonly HerdSource[]): HerdSource[] =>
+  sources.filter((source) => showsEntries(source) && source.entries.length > 0)
+
+/** The source as the `Sources` block draws it: a source with a block of its own keeps its status, not its entries. */
+export const statusOnly = (source: HerdSource): HerdSource =>
+  showsEntries(source) ? { ...source, entries: [], latest: null } : source
+
+/**
+ * The rows of the block of a source that shows its entries: count, time and title as in the opened source, in the
+ * order the state holds them, in the tone of the source, none of them asking or expanding; a row with an address
+ * is linked. Only the first `limit` entries become rows, the columns measured over those.
+ */
+export const entryBlockItems = (source: HerdSource, now: number, limit: number): BlockItem[] => {
+  const shown = source.entries.slice(0, limit)
+  const columns = columnsOf(shown, now)
+  return shown.map((entry) => ({
+    key: entryKey(source.name, entry),
+    mark: ENTRY_MARK,
+    lead: entryLeadOf(entry, now, columns),
+    text: entry.title,
+    url: entry.url,
+    ask: null,
+    expands: false,
+    ...(source.tone && { tone: source.tone }),
+  }))
+}
+
 const DEFAULT_VIEW: SourceView = { expanded: new Set(), asked: () => false }
 
 /**

package/src/watch/lane-report.ts

@@ -409,7 +409,8 @@ const readyPhaseText = ({ id, after }: ReadyPhase): string =>
 
 /**
  * What a resting lane (`done` or `idle`) with ready phases asks of the coordinator (`orchestrate` § 2): one line per such
- * lane, naming every ready phase, to start it now; a pull request waiting for approval holds only the commit.
+ * lane, naming every ready phase, to start it now; a pull request of the lane waiting for approval or merge
+ * holds only the commit.
  */
 export const readyPhaseDutyLines = (
   stopped: readonly string[],

package/src/watch/source-dry-run.ts

@@ -35,7 +35,7 @@ const RAW_LINE_LENGTH = 200
 const INDENT = '  '
 const BASELINE = 'first run of this source: baseline, nothing reported'
 const NOT_CHECKED = '0 entries: map not checked'
-const FOOTER = 'watcher state not read or changed; the watcher takes a new source over at its next start'
+const FOOTER = 'watcher state not read or changed; a running watcher takes a new source over at its next cycle'
 
 export const dryRunTarget = (value: string): DryRunTarget => {
   if (value === STDIN) return { kind: 'stdin' }

package/src/watch/texts.ts

@@ -79,7 +79,7 @@ export const watchTexts = (dialogLanguage: PlanLanguage): WatchTexts => ({
   laneModelDuty:
     'switch it while idle: /exit, then claude --resume <session> --model <id> in the same pane (§ 2 step 6)',
   readyPhaseDuty: (count) =>
-    `start ${count === 1 ? 'it' : 'them'} now (§ 2); a waiting PR approval holds only the commit`,
+    `start ${count === 1 ? 'it' : 'them'} now (§ 2), on a branch over the open PR of the lane if it waits for approval or merge: that holds only the commit`,
   mainCheckoutBehind: (remoteBase, count) =>
     `main checkout behind ${remoteBase} by ${count} (git merge --ff-only ${remoteBase})`,
   mainCheckoutOffBase: (branch, baseBranch) => `main checkout on ${branch ?? 'a detached head'}, not ${baseBranch}`,