jackherd 1.12.1 → 1.12.3

package/src/plans/view.ts

@@ -1,14 +1,13 @@
 import { ARTIFACT_LINK_KIND } from '../config/link-kinds'
 import { DEFAULT_TONES } from '../config/tones'
-import { fit, paint, plainText, visibleLength } from '../terminal/text'
-import { type AgentOf, clickHint } from './click-hint'
+import { fit, plainText, visibleLength } from '../terminal/text'
+import type { AgentOf } from './click-hint'
+import { unfocused } from './focus-overlay'
 import { type OverviewView, renderScreen, renderSelected, type Screen } from './layout'
 import type { Options } from './options'
-import { blockRowByKey, boldBracketAt, type FocusHit, focusLine, isFocused, LINKS_KEY_PREFIX } from './row-focus'
 import { laneSelection, overviewSelection, type Selection } from './selection'
-import { longestShimmer, type ShimmerRow, shimmerAt, shimmerRows } from './shimmer'
+import { longestShimmer, type ShimmerRow, shimmerAt } from './shimmer'
 import type { Snapshot } from './snapshot'
-import { TEXTS } from './texts'
 import { setTones } from './tones'
 
 const DEFAULT_WIDTH = 100
@@ -25,9 +24,6 @@ export const FRAME_MS = 16
 export const nextFrameDelay = (lastFrameAt: number | null, now: number): number =>
   lastFrameAt === null ? 0 : Math.max(FRAME_MS - (now - lastFrameAt), 0)
 
-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
 
@@ -62,21 +58,18 @@ const withErrors = (screen: Screen, errors: string[], width: number): Screen =>
   footer: [...errors.map((error) => fit(error, width)), ...screen.footer],
 })
 
+/** What a drawing of a snapshot needs besides the snapshot: the selection, the error lines over the footer, the pane width and whether the shimmer runs. */
+export type RenderContext = { selection: Selection; errors: string[]; width: number; shimmer?: boolean }
+
 export const renderSnapshot = (
   snapshot: Snapshot,
-  selection: Selection,
-  errors: string[],
-  width: number,
-  shimmer = false,
+  { selection, errors, width, shimmer = false }: RenderContext,
 ): Screen => withErrors(renderSelected(overviewOf(snapshot, shimmer), selection, width), errors, width)
 
 /** The snapshot drawn with no row focused (`unfocused`), the base a hover lays its focus on (`focusedScreen`). */
 export const renderUnfocused = (
   snapshot: Snapshot,
-  selection: Selection,
-  errors: string[],
-  width: number,
-  shimmer = false,
+  { selection, errors, width, shimmer = false }: RenderContext,
 ): Screen => withErrors(renderScreen(overviewOf(snapshot, shimmer), unfocused(selection), width), errors, width)
 
 /** The status of a lane's agent by the lane's name, for the footer's click hint. */
@@ -106,13 +99,6 @@ const wholeFrame = (lines: readonly string[], width: number, now: number): strin
   return `${SYNC_BEGIN}${CURSOR_HOME}${drawn}${CLEAR_BELOW}${SYNC_END}`
 }
 
-/**
- * The frame of `frameLinesOf` as written, a shimmering text with its stripe at `now` (epoch milliseconds). It stands
- * between the marks of synchronized output, so a terminal that knows them never shows half of it.
- */
-export const frameOutput = (screen: Screen, top: number, width: number, rows: number, now: number): string =>
-  wholeFrame(frameLinesOf(screen, top, rows), width, now)
-
 /**
  * What to write to turn the frame `previous` on the terminal into `lines`: the frame whole when the terminal content
  * is unknown (null) or its height changed, else each changed line at its cursor address, nothing when none changed.
@@ -132,10 +118,6 @@ export const changedLinesOutput = (
   return changed.length === 0 ? '' : `${SYNC_BEGIN}${changed.join('')}${SYNC_END}`
 }
 
-/** The lines of the frame `frameOutput` writes that shimmer, by their row on the terminal. */
-export const frameShimmerRows = (screen: Screen, top: number, rows: number): ShimmerRow[] =>
-  shimmerRows(frameLinesOf(screen, top, rows))
-
 /** The rows that shimmer, prepared once per frame: the pass they share, and whether a row is wider than the pane. */
 export type PreparedShimmer = {
   rows: readonly (ShimmerRow & { wide: boolean })[]
@@ -162,80 +144,6 @@ export const shimmerOutput = ({ rows, longest, width }: PreparedShimmer, now: nu
   return `${SYNC_BEGIN}${drawn.join('')}${SYNC_END}`
 }
 
-/** A selection that focuses no row: the screen drawn with it is the base `focusedScreen` lays the focus on. */
-export const unfocused = (selection: Selection): Selection => ({
-  ...selection,
-  selected: NO_ROW,
-  hovered: null,
-  hoveredFrom: null,
-})
-
-const NO_ROW = '\0'
-const LEAD = /^ */
-
-/** The blanks a block puts before a row it holds (`indented`): the focus lies right of them, as narrow as the row. */
-const leadOf = (line: string): number => LEAD.exec(line)?.[0].length ?? 0
-
-/** `lines` with the lines of `hit` (counted from `offset`) changed by `change`, the first line told by its index. */
-const changedHit = (
-  lines: readonly string[],
-  offset: number,
-  hit: FocusHit | undefined,
-  change: (line: string, index: number) => string,
-): string[] =>
-  lines.map((line, at) => {
-    const index = hit ? at + offset - hit.line : -1
-    return hit && index >= 0 && index < hit.lines ? change(line, index) : line
-  })
-
-/**
- * `screen` with the focus `state` gives laid on one region of `lines`: the focused row on the focus background and
- * mark, a line of links under the mouse marked alone, and the square-bracket button under the mouse bold.
- */
-const focusedLines = (lines: readonly string[], offset: number, screen: Screen, state: Selection, width: number) => {
-  const hitOf = (key: string | null | undefined) => (key ? screen.focusHits.find((hit) => hit.key === key) : undefined)
-  const hovered = hitOf(state.hovered)
-  const focusedKey = state.selected !== null && isFocused(state, state.selected) ? state.selected : null
-  const focusedHit = hitOf(focusedKey)
-  const gutter = focusedHit ? leadOf(lines[focusedHit.line - offset] ?? '') : 0
-  const focused = changedHit(
-    lines,
-    offset,
-    focusedHit,
-    (line, index) => `${line.slice(0, gutter)}${focusLine(line.slice(gutter), width - gutter, index === 0)}`,
-  )
-  const links = state.hovered?.startsWith(LINKS_KEY_PREFIX)
-    ? changedHit(focused, offset, hovered, (line, index) => (index === 0 ? focusLine(line, width, true) : line))
-    : focused
-  const from = state.hoveredFrom
-  return from == null
-    ? links
-    : changedHit(links, offset, hovered, (line, index) => (index === 0 ? boldBracketAt(line, from) : line))
-}
-
-/**
- * The screen a full drawing with `state` gives, laid on `plain` (drawn with `unfocused`) without a new layout: a hover
- * only moves the focus. Null where it needs the layout: with the help open, or for a row of the blocks on top, whose
- * buttons stand only at the selection. `agentOf` says a lane's agent, for the footer's click hint.
- */
-export const focusedScreen = (plain: Screen, state: Selection, width: number, agentOf: AgentOf): Screen | null => {
-  const blocks = [plain.yourTurnBlock, plain.sourceBlock]
-  const isBlockRow = (key: string | null | undefined) => !!key && blockRowByKey(blocks, key) !== null
-  if (state.showLegend || isBlockRow(state.selected) || isBlockRow(state.hovered)) return null
-  const header = focusedLines(plain.header, 0, plain, state, width)
-  const lines = focusedLines(plain.body.lines, plain.header.length, plain, state, width)
-  const selectedHit = plain.focusHits.find(({ key }) => key === state.selected)
-  const cursorLine =
-    selectedHit && selectedHit.line >= plain.header.length ? selectedHit.line - plain.header.length : -1
-  const hint = clickHint(state, (key) => blockRowByKey(blocks, key), agentOf) ?? TEXTS.hint
-  return {
-    ...plain,
-    header,
-    body: { ...plain.body, lines, cursorLine },
-    footer: [...plain.footer.slice(0, -1), fit(paint.dim(hint), width)],
-  }
-}
-
 const ARTIFACT_ADDRESS = new RegExp(ARTIFACT_LINK_KIND.pattern)
 
 /**

package/src/plans/waiting-click.ts

@@ -8,7 +8,7 @@ import { MOUSE_BUTTON, type MouseEvent } from './selection'
 
 /**
  * One row of a block of the herd as drawn: its plain text lines (more than one while it is expanded; the first starts
- * with `mark` and a blank and, for a row with `[ask]`, is padded to leave the button its cells), whether its text is wider than the pane and the row may expand (`cut`), whether it is expanded, and the address a
+ * with `mark` and a blank and takes the whole pane; the buttons lie over its end only while the row is selected, `hot`), whether its text is wider than the pane and the row may expand (`cut`), whether it is expanded, and the address a
  * click opens.
  */
 export type BlockRow = {
@@ -28,6 +28,11 @@ export type BlockRow = {
   toggle?: string
   /** The row is dim from its text on; absent for most rows. */
   dim?: boolean
+  /**
+   * The first line while the row shows its buttons (`buttonsOver`): the mark and the text cut to end a blank before the
+   * first button, which stands flush right at the edge; absent for a row without buttons.
+   */
+  hot?: string
 }
 
 /**
@@ -98,8 +103,6 @@ export const waitingKey = ({ id, item }: WaitingItem): string => `waiting>${id ?
 /** The cells the two blanks take that start every line of a block row (`blockBar` and the gap after it). */
 export const BAR_WIDTH = 2
 
-const roomOf = (width: number): number => Math.max(width - BAR_WIDTH, 1)
-
 /** `[ask]` for what the coordinator can put, none for what it cannot. */
 const askButtons = (ask: AskTarget | null): BlockButton[] => (ask ? [{ label: ASK_BUTTON, click: { ask } }] : [])
 
@@ -117,14 +120,22 @@ export const placedButtons = (buttons: readonly BlockButton[], room: number): Pl
   })
 }
 
-/** The cells a row's text may take beside `buttonCells` of buttons (0 for none) and the blank before them. */
-export const textRoom = (width: number, buttonCells: number): number =>
-  buttonCells === 0 ? roomOf(width) : Math.max(roomOf(width) - (buttonCells + ASK_GAP), 1)
+/** The cells of text a block row has: the whole pane but the two blanks that start it. */
+export const rowRoom = (width: number): number => Math.max(width - BAR_WIDTH, 1)
 
-/** The cells a row's text may take and the buttons with the screen columns they start in; none for a row without one. */
-const buttonLayout = (items: readonly BlockButton[], width: number): { room: number; placed: PlacedButton[] } => {
-  const room = textRoom(width, items.length === 0 ? 0 : buttonsWidth(items))
-  return { room, placed: placedButtons(items, room) }
+/**
+ * The buttons flush right at the edge of a first line of `room` cells, laid over whatever stands there: the text keeps
+ * the whole line while the row is not chosen, and gives up its end (in "Your turn" the time too) to the buttons while
+ * it is. No buttons, no hot line.
+ */
+export const buttonsOver = (
+  text: string,
+  buttons: readonly BlockButton[],
+  room: number,
+): { hot?: string; placed: PlacedButton[] } => {
+  if (buttons.length === 0) return { placed: [] }
+  const textCells = Math.max(room - buttonsWidth(buttons) - ASK_GAP, 1)
+  return { hot: padVisible(fit(text, textCells), textCells), placed: placedButtons(buttons, textCells) }
 }
 
 /** The labels of a row's buttons as drawn after its text, one blank apart, each painted with `paintLabel`. */
@@ -147,13 +158,12 @@ const MIN_WRAP_WIDTH = 12
  * column of the text; one line cut at `room` when the lead leaves fewer than `MIN_WRAP_WIDTH` cells, so a wide lead never
  * wraps the text one cell per line.
  */
-const hangingLines = (start: string, text: string, room: number): string[] => {
+export const hangingLines = (start: string, text: string, room: number): string[] => {
   const hang = textWidth(start)
   if (room - hang < MIN_WRAP_WIDTH) return [fit(`${start}${text}`, room)]
   const [first, ...rest] = wrap(text, room - hang)
   return [`${start}${first}`, ...rest.map((line) => `${' '.repeat(hang)}${line}`)]
 }
-
 /** What `[done]` closes: the record of a file or a question, else the row of the board; none for a record-less question. */
 const doneOf = (item: WaitingItem): DoneTarget | null => {
   if (item.id) return { kind: DONE_KIND.record, id: item.id }
@@ -174,15 +184,14 @@ export const waitingUrl = (item: WaitingItem): string | null =>
 
 const rowOf = (item: BlockItem, expandedKeys: ReadonlySet<string>, width: number): BlockRow => {
   const { key, mark, lead, text, url, ask, tone, toggle, dim, expands } = item
-  const { room, placed } = buttonLayout(askButtons(ask), width)
+  const room = rowRoom(width)
   const leadText = lead === undefined ? '' : `${lead} `
   const start = `${mark} ${leadText}`
   const cut = expands !== false && textWidth(`${start}${text}`) > room
   const expanded = cut && expandedKeys.has(key)
-  const parts = expanded ? hangingLines(start, text, room) : [fit(`${start}${text}`, room)]
-  const lines =
-    placed.length > 0 ? parts.map((line, index) => (index === 0 ? padVisible(line, room + ASK_GAP) : line)) : parts
-  const dimFrom = parts.map((line, index) => {
+  const lines = expanded ? hangingLines(start, text, room) : [fit(`${start}${text}`, room)]
+  const { hot, placed } = buttonsOver(lines[0], askButtons(ask), room)
+  const dimFrom = lines.map((line, index) => {
     if (!dim) return line.length
     return index === 0 ? mark.length + 1 : 0
   })
@@ -195,6 +204,7 @@ const rowOf = (item: BlockItem, expandedKeys: ReadonlySet<string>, width: number
     url,
     buttons: placed,
     dimFrom,
+    ...(hot && { hot }),
     ...(tone && { tone }),
     ...(toggle && { toggle }),
     ...(dim && { dim }),

package/src/plans/worked-phases.ts

@@ -15,7 +15,7 @@ import { belongsToLane } from './phase-source'
 const workedIds = (lane: SprintLane, plans: PlansByHref, href: string): string[] => {
   const named = lane.steps.filter((step) => step.planHref === href).flatMap((step) => step.phaseIds)
   return (plans[href] ?? [])
-    .filter((phase) => phase.touched && phase.items.some((item) => item.done) && !belongsToLane(phase.id, named))
+    .filter((phase) => phase.work && phase.items.some((item) => item.done) && !belongsToLane(phase.id, named))
     .map((phase) => phase.id)
 }
 

package/src/plans/worktree-stamp.ts

@@ -1,5 +1,6 @@
 import { readFileSync, statSync } from 'node:fs'
 import { isAbsolute, join, resolve } from 'node:path'
+import { stampOf } from '../shared/stat-cache'
 
 const GIT_DIRECTORY_LINE = /^gitdir:\s*(.+)$/m
 
@@ -17,19 +18,21 @@ const gitDirectoryOf = (worktree: string): string => {
 }
 
 const fileMark = (path: string): string => {
-  try {
-    const { mtimeMs, size } = statSync(path)
-    return `${mtimeMs}:${size}`
-  } catch {
-    return '-'
-  }
+  const stamp = stampOf(path)
+  return stamp ? `${stamp.mtimeMs}:${stamp.size}` : '-'
 }
 
 /**
- * What tells whether a worktree's `git status` may have changed without asking git: its index and HEAD as stat-ed,
- * and `activity` (`logMark` of its agent, its subagents' work). Stable for a worktree that does not exist.
+ * What tells whether a worktree's `git status` and its commits may have changed without asking git: its index, HEAD
+ * and the reflog of HEAD (which every commit, reset and rebase grows) as stat-ed, and `activity` (`logMark` of its
+ * agent, its subagents' work, the base's commit). Stable for a worktree that does not exist.
  */
 export const worktreeStamp = (worktree: string, activity: string): string => {
   const gitDirectory = gitDirectoryOf(worktree)
-  return [fileMark(join(gitDirectory, 'index')), fileMark(join(gitDirectory, 'HEAD')), activity].join('|')
+  return [
+    fileMark(join(gitDirectory, 'index')),
+    fileMark(join(gitDirectory, 'HEAD')),
+    fileMark(join(gitDirectory, 'logs', 'HEAD')),
+    activity,
+  ].join('|')
 }

package/src/plans/your-turn-rows.ts

@@ -1,15 +1,14 @@
 import { WAITING_KIND } from '../plan-format/waiting'
-import { fit, padVisible, spread } from '../terminal/text'
+import { fit, spread } from '../terminal/text'
 import { textWidth } from '../terminal/width'
 import { appointmentButtons } from './appointment-rows'
 import { chevronOf, TURN_MARK } from './symbols'
 import {
-  ASK_GAP,
   type BlockButton,
   type BlockRow,
-  buttonsWidth,
-  placedButtons,
-  textRoom,
+  buttonsOver,
+  hangingLines,
+  rowRoom,
   waitingButtons,
   waitingUrl,
 } from './waiting-click'
@@ -33,31 +32,35 @@ const buttonsOf = (row: TurnRow): BlockButton[] => {
   return row.waiting ? waitingButtons(row.waiting) : []
 }
 
-/** The text cut to leave the time its column, the time flush right at `room`. */
-const firstLineOf = (mark: string, row: TurnRow, room: number): string => {
-  const textCells = Math.max(room - textWidth(row.time) - TIME_GAP, 1)
-  return spread(fit(`${mark} ${row.text}`, textCells), row.time, room)
-}
+/** What stands right of the text: the gap and the time, flush right; nothing for a row without a time. */
+const timeColumn = (time: string): string => (time ? `${' '.repeat(TIME_GAP)}${time}` : '')
 
 /**
- * A topic as a block row: the mark, the text and the time flush right at the edge of the text room, which every row
- * of the block shares (`room`), so the times end in one column before the buttons; under a row that frees lanes the
- * dim line `unblocks …`. The buttons keep their columns whether drawn or not; the block draws them at the focused row.
+ * A topic as a block row: the mark and the text over the whole pane but the time, which stands flush right at its
+ * edge (`room`), so the times end in one column; under a row that frees lanes the dim line `unblocks …`. A text cut
+ * off at the time is `cut`, and once its key is in `expandedKeys` it hangs under its first line, the time staying on
+ * that one. The chosen row lays its buttons flush right at the edge, over the end of the text and the time (`buttonsOver`).
  */
-const rowOf = (row: TurnRow, room: number): BlockRow => {
+const rowOf = (row: TurnRow, room: number, expandedKeys: ReadonlySet<string>): BlockRow => {
   const mark = markOf(row)
-  const first = firstLineOf(mark, row, room)
+  const start = `${mark} `
+  const textCells = Math.max(room - textWidth(timeColumn(row.time)), 1)
+  const cut = textWidth(`${start}${row.text}`) > textCells
+  const expanded = cut && expandedKeys.has(row.key)
+  const [head = '', ...hanging] = expanded ? hangingLines(start, row.text, textCells) : [`${start}${row.text}`]
+  const first = spread(fit(head, textCells), row.time, room)
   const unblocks = row.unblocks.length > 0 ? [fit(`${UNBLOCKS_INDENT}unblocks ${row.unblocks.join(', ')}`, room)] : []
-  const buttons = buttonsOf(row)
+  const { hot, placed } = buttonsOver(head, buttonsOf(row), room)
   return {
     key: row.key,
     mark,
-    lines: [buttons.length > 0 ? padVisible(first, room + ASK_GAP) : first, ...unblocks],
-    cut: false,
-    expanded: false,
+    lines: [first, ...hanging, ...unblocks],
+    cut,
+    expanded,
     url: row.waiting ? waitingUrl(row.waiting) : null,
-    buttons: placedButtons(buttons, room),
-    dimFrom: [first.length - row.time.length, ...unblocks.map(() => 0)],
+    buttons: placed,
+    dimFrom: [first.length - row.time.length, ...hanging.map((line) => line.length), ...unblocks.map(() => 0)],
+    ...(hot && { hot }),
   }
 }
 
@@ -80,23 +83,21 @@ const toggleRow = (key: string, text: string, open: boolean, room: number): Bloc
 const moreText = ({ count, older }: { count: number; older: number }): string =>
   older > 0 ? `${count} more · ${older} older than ${OLD_DAYS} days` : `${count} more`
 
-/** The cells of text every row of the block may take: what the widest set of buttons leaves of the pane. */
-const sharedRoom = (rows: readonly TurnRow[], width: number): number =>
-  textRoom(width, Math.max(0, ...rows.map((row) => buttonsWidth(buttonsOf(row)))))
-
 /**
  * The rows of the open "Your turn" block: the now rows, the line for the rest of them, the planned rows and the line
- * for the later ones; an opened line points down at the rest of its rows, which stand below it.
+ * for the later ones; an opened line points down at the rest of its rows, which stand below it. `expandedKeys` names
+ * the rows cut off at the edge that show their whole text.
  */
-export const turnRows = (page: TurnPage, width: number): BlockRow[] => {
+export const turnRows = (page: TurnPage, width: number, expandedKeys: ReadonlySet<string> = new Set()): BlockRow[] => {
   const { opened } = page
-  const room = sharedRoom([...page.now, ...page.nowRest, ...page.planned, ...page.plannedRest], width)
+  const room = rowRoom(width)
+  const rowsOf = (rows: readonly TurnRow[]) => rows.map((row) => rowOf(row, room, expandedKeys))
   return [
-    ...page.now.map((row) => rowOf(row, room)),
+    ...rowsOf(page.now),
     ...(page.nowMore ? [toggleRow(YOUR_TURN_MORE_KEY, moreText(page.nowMore), opened.allNow, room)] : []),
-    ...page.nowRest.map((row) => rowOf(row, room)),
-    ...page.planned.map((row) => rowOf(row, room)),
+    ...rowsOf(page.nowRest),
+    ...rowsOf(page.planned),
     ...(page.later > 0 ? [toggleRow(YOUR_TURN_LATER_KEY, `${page.later} later`, opened.allPlanned, room)] : []),
-    ...page.plannedRest.map((row) => rowOf(row, room)),
+    ...rowsOf(page.plannedRest),
   ]
 }

package/src/plans/your-turn.ts

@@ -4,8 +4,7 @@ import type { PlanLanguage } from '../vocabulary'
 import { parseAppointmentTime } from '../watch/appointments'
 import { type AppointmentRow, appointmentRows, TIME_OPEN } from './appointment-rows'
 import { calendarDaysBetween } from './calendar-days'
-import { plain } from './layout-phase'
-import { nextLines } from './next-rows'
+import { plain } from './markdown-text'
 import { shortTitle } from './task-name'
 import { waitingKey } from './waiting-click'
 
@@ -173,7 +172,10 @@ export const yourTurnOf = ({ waiting, appointments, next, now }: TurnSources): Y
   return { now: [...nowRows].sort(byBlockingThenAge), planned: [...planned, ...nextRows].sort(byTime) }
 }
 
-/** "Your turn" of a board: `waiting` (its open rows, the questions and the files), its open appointments and next lines. */
+/**
+ * "Your turn" of a board: `waiting` (its open rows, the questions and the files) and its open appointments, only what
+ * waits on the user. The board's next lines stay out: they carry no action and repeat what waits.
+ */
 export const yourTurnOfBoard = (
   board: string,
   language: PlanLanguage,
@@ -182,7 +184,7 @@ export const yourTurnOfBoard = (
 ): YourTurnBlock => {
   const clock = new Date(now)
   const appointments = appointmentRows(board, language, clock)
-  return { turn: yourTurnOf({ waiting, appointments, next: nextLines(board, language), now: clock }), now }
+  return { turn: yourTurnOf({ waiting, appointments, next: [], now: clock }), now }
 }
 
 const isOld = (row: TurnRow, now: Date): boolean =>

package/src/shared/bounded-memo.ts

@@ -0,0 +1,19 @@
+/** What was computed per key, kept while a herd runs; a set while it holds `limit` keys, a known one too, starts it over. */
+export type BoundedMemo<K, V> = {
+  /** The value kept for `key`, undefined when none. */
+  get: (key: K) => V | undefined
+  /** Keeps `value` for `key` and answers it. */
+  set: (key: K, value: V) => V
+}
+
+export const boundedMemo = <K, V>(limit: number): BoundedMemo<K, V> => {
+  const kept = new Map<K, V>()
+  return {
+    get: (key) => kept.get(key),
+    set: (key, value) => {
+      if (kept.size >= limit) kept.clear()
+      kept.set(key, value)
+      return value
+    },
+  }
+}

package/src/shared/stat-cache.ts

@@ -22,7 +22,8 @@ export const dropUnused = (cache: Map<string, unknown>, used: ReadonlySet<string
   for (const key of [...cache.keys()]) if (!used.has(key)) cache.delete(key)
 }
 
-const stampOf = (path: string): FileStamp | null => {
+/** The stamp of the file at `path`, null when it cannot be stat-ed. */
+export const stampOf = (path: string): FileStamp | null => {
   try {
     const { mtimeMs, size } = statSync(path)
     return { mtimeMs, size }

package/src/task-signals/command.ts

@@ -19,13 +19,22 @@ export type TaskCommand =
   | { kind: 'help' }
   | { kind: 'usage' }
 
+const TASK_VERB = { start: 'start', done: 'done' } as const
+const HELP_OPTIONS: ReadonlySet<string | undefined> = new Set(['--help', '-h'])
+
+const isTaskVerb = (name: string | undefined): boolean => name === TASK_VERB.start || name === TASK_VERB.done
+
+/** `--help` or `-h` alone, or as the only word after `start` or `done`; among other words it is task text. */
+const asksForHelp = (name: string | undefined, words: readonly string[]): boolean =>
+  HELP_OPTIONS.has(name) || (isTaskVerb(name) && words.length === 1 && HELP_OPTIONS.has(words[0]))
+
 /** The command line as a command: the words after `start` or `done` are the task text, whether quoted or not. */
 export const parseTaskCommand = (args: readonly string[]): TaskCommand => {
   const [name, ...words] = args
-  if (name === '--help' || name === '-h') return { kind: 'help' }
+  if (asksForHelp(name, words)) return { kind: 'help' }
   const text = cleanTaskText(words.join(' '))
-  if (name === 'start' && text !== '') return { kind: 'start', text }
-  if (name === 'done') return { kind: 'done', text }
+  if (name === TASK_VERB.start && text !== '') return { kind: 'start', text }
+  if (name === TASK_VERB.done) return { kind: 'done', text }
   return { kind: 'usage' }
 }
 

package/src/terminal/lifetime.ts

@@ -0,0 +1,52 @@
+import { writeSync } from 'node:fs'
+import { onceRestore } from './restore'
+
+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'
+
+const STDOUT_FD = 1
+const STDERR_FD = 2
+
+/** How the view ends: `quit` and `crash` leave, `restore` gives the terminal back and runs on `exit` as well. */
+export type TerminalEnds = { quit: () => void; crash: (error: unknown) => void; restore: () => void }
+
+/**
+ * The terminal given back on every end, written synchronously because `exit` waits for nothing: mouse reports and
+ * alternate screen off, cursor shown, raw mode released, once (`onceRestore`).
+ */
+export const terminalRestore = (): (() => void) =>
+  onceRestore(TERMINAL_OFF, {
+    write: (text) => writeSync(STDOUT_FD, text),
+    releaseRaw: () => {
+      if (process.stdin.isTTY) process.stdin.setRawMode(false)
+    },
+  })
+
+/**
+ * Alternate screen, hidden cursor, mouse reports and raw keys, each chunk read handed to `onData`. A signal quits, an
+ * error nobody caught crashes (a closed terminal's `EIO` on stdin among them), and `exit` restores the terminal
+ * whatever ended the process.
+ */
+export const enterTerminal = (onData: (chunk: string) => void, ends: TerminalEnds, onResize: () => void) => {
+  process.stdout.write(TERMINAL_ON)
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) process.on(signal, ends.quit)
+  process.on('exit', ends.restore)
+  process.on('uncaughtException', ends.crash)
+  process.on('unhandledRejection', ends.crash)
+  process.stdout.on('resize', onResize)
+  if (!process.stdin.isTTY) return
+  process.stdin.setRawMode(true)
+  process.stdin.on('error', ends.crash)
+  process.stdin.on('data', (chunk) => onData(chunk.toString()))
+}
+
+/** The terminal restored first, so the report lands in the shell and not on the alternate screen; null reports nothing. */
+export const reportCrash = (report: string | null, restore: () => void) => {
+  restore()
+  if (report === null) return
+  try {
+    writeSync(STDERR_FD, `${report}\n`)
+  } catch {
+    // stderr went away with the terminal; the exit code still tells.
+  }
+}

package/src/watch/command.ts

@@ -88,6 +88,7 @@ import { type FeedbackItem } from './feedback-item'
 import { type FeedbackItemsRead, readCommentItems, readFeedbackItems, readOwnLogin } from './feedback-read'
 import { answered, deployTargetOf, type GithubRead, readGithub, targetText } from './github-read'
 import { currentPhaseCountsOf } from './heartbeat-progress'
+import { startHerdPublisher } from './herd-publisher'
 import { agentScreen, listAgents } from './herdr'
 import { endedByKitUpdate } from './kit-update'
 import { type LaneReadings, laneFillEvents, recordLaneLevels } from './lane-fill'
@@ -1311,6 +1312,10 @@ const watchLanes = async (watch: Watch) => {
   })
 
   const kit = await startedKit()
+  const stopPublisher =
+    kit && watch.options.stream
+      ? startHerdPublisher({ root: watch.root, sprintFile: watch.sprintFile, settings: watch.settings }, kit)
+      : null
   const skillSnapshot = kit ? readOrchestrateSnapshot(kit.packageRoot) : null
   const skillLine = () => skillLineFor(kit, skillSnapshot, dirname(watch.files.state))
   const announceUpdate = kit
@@ -1330,6 +1335,7 @@ const watchLanes = async (watch: Watch) => {
     }
   } finally {
     sourceChanges?.close()
+    stopPublisher?.()
   }
 }