jackherd 1.8.1 → 1.10.0

package/src/plan-format/dependencies.ts

@@ -1,5 +1,5 @@
 import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { PHASE_ID_PREFIX, phaseLabels } from './lanes'
+import { PHASE_ID_PREFIX, phaseLabels, spannedPhaseIds } from './lanes'
 import { escapeRegExp, firstTableWithHeader, subsectionLines } from './markdown'
 import { type PhaseHeading, parsePlanPhases, phaseHeadings } from './phases'
 import { isPhaseFinished } from './progress'
@@ -40,7 +40,6 @@ const VERSION = /^v?\d+(?:[.\-+][\w.-]*)?$/i
 const PACKAGE_SCOPE = /^@[^/]+\//
 /** The files a release of the package in their directory changes: the changelog and the version in the manifest. */
 const RELEASE_FILE = /(?:^|\/)(?:CHANGELOG\.md|package\.json)$/
-const MAX_RANGE = 50
 
 const phaseIdOf = (cell: string): string | null => PHASE_ID.exec(cell)?.[1]?.toLowerCase() ?? null
 
@@ -63,9 +62,7 @@ const splitOutsideParentheses = (cell: string, separator: string): string[] => {
 const rangeOf = (entry: string): string[] | null => {
   const match = PHASE_RANGE.exec(entry)
   if (!match) return null
-  const [first, last] = [Number(match[1]), Number(match[2])]
-  if (first > last || last - first >= MAX_RANGE) return []
-  return Array.from({ length: last - first + 1 }, (_, offset) => String(first + offset))
+  return spannedPhaseIds(Number(match[1]), Number(match[2]))
 }
 
 const dependsOf = (cell: string, language: PlanLanguage): Pick<PhaseDependency, 'after' | 'external'> => {
@@ -203,18 +200,21 @@ const longestChain = (chains: readonly string[][]): string[] =>
 const mergeSets = (sets: readonly (string[] | null)[]): string[] | null =>
   sets.some((set) => set === null) ? null : sets.flatMap((set) => set ?? [])
 
-/** The paths a phase writes, those of every phase its `like` cell names included; null for an unknown target or a cycle. */
-const writeSetOf = (
+const writeSetWithin = (
   row: PhaseDependency,
   byId: ReadonlyMap<string, PhaseDependency>,
   chain: readonly string[],
 ): string[] | null => {
   if (chain.includes(row.id)) return null
   const targets = row.writesLike.map((id) => byId.get(id))
-  const like = mergeSets(targets.map((target) => (target ? writeSetOf(target, byId, [...chain, row.id]) : null)))
+  const like = mergeSets(targets.map((target) => (target ? writeSetWithin(target, byId, [...chain, row.id]) : null)))
   return like === null ? null : [...row.writes, ...like]
 }
 
+/** The paths a phase writes, those of every phase its `like` cell names included; null for an unknown target or a cycle. */
+export const writeSetOf = (row: PhaseDependency, byId: ReadonlyMap<string, PhaseDependency>): string[] | null =>
+  writeSetWithin(row, byId, [])
+
 const overlaps = (left: string, right: string): boolean =>
   left === '' || right === '' || left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)
 
@@ -231,7 +231,7 @@ const collides = (first: Candidate, second: Candidate): boolean =>
   sharesMarker(first, second) || first.writes.some((path) => second.writes.some((other) => overlaps(path, other)))
 
 const candidateOf = (row: PhaseDependency, byId: ReadonlyMap<string, PhaseDependency>): Candidate[] => {
-  const writes = writeSetOf(row, byId, [])
+  const writes = writeSetOf(row, byId)
   if (writes === null || writes.length === 0) return []
   const releases = [...new Set([...row.releases, ...releasedByFiles(writes)])]
   return [{ id: row.id, writes, serialMarkers: row.serialMarkers, releases }]

package/src/plan-format/index.ts

@@ -34,4 +34,5 @@ export * from './phase-tally'
 export * from './phases'
 export * from './plan-structure'
 export * from './progress'
+export * from './short-names'
 export * from './sprint-document'

package/src/plan-format/lanes.ts

@@ -32,6 +32,15 @@ export const PHASE_ID_PREFIX = 'P'
 /** A phase as plans and reports name it: `P4`. */
 export const phaseLabel = (id: string): string => `${PHASE_ID_PREFIX}${id}`
 
+/** The widest range a cell may span; a wider one is a typo, not a plan. */
+const MAX_RANGE = 50
+
+/** The ids from `first` to `last`, both included; empty when the range runs backwards or spans `MAX_RANGE` or more. */
+export const spannedPhaseIds = (first: number, last: number): string[] =>
+  first > last || last - first >= MAX_RANGE
+    ? []
+    : Array.from({ length: last - first + 1 }, (_, offset) => String(first + offset))
+
 /** Phases as plans and reports name them, joined by `separator`: `P3 P4`, `P19 ∥ P20`. */
 export const phaseLabels = (ids: readonly string[], separator: string): string => ids.map(phaseLabel).join(separator)
 
@@ -39,22 +48,32 @@ const PHASES_COLUMN = 3
 const CLAUSE_SEPARATOR = /([;,]|\.(?=\s))\s*/
 const ENTRY_END = new Set([';', '.'])
 
-type PhaseIdPatterns = { leading: RegExp; afterConnector: RegExp; connector: RegExp }
+type PhaseIdPatterns = { leading: RegExp; rangeEnd: RegExp; afterConnector: RegExp; connector: RegExp }
 
 const phaseIdPatterns = (language: PlanLanguage): PhaseIdPatterns => {
   const connectors = PLAN_VOCABULARY[language].phaseConnectors.join('|')
   const id = `(?:\\*\\*)?${PHASE_ID_PREFIX}(\\d+[a-z]?)\\b`
   return {
     leading: new RegExp(`^\\s*(?:(?:${connectors})\\s+)*${id}`),
+    rangeEnd: new RegExp(`^\\s*[–-]\\s*(?:\\*\\*)?${PHASE_ID_PREFIX}(\\d+)\\b`),
     afterConnector: new RegExp(`^\\s*(?:${connectors})\\s`),
     connector: new RegExp(`\\b(?:${connectors})\\s+${id}`, 'g'),
   }
 }
 
+/** The ids an entry starting with `leading` names: the one id, or every id of a range `P17–P25` it opens. */
+const leadingIds = (clause: string, leading: RegExpMatchArray, patterns: PhaseIdPatterns): string[] => {
+  const first = leading[1]
+  const end = clause.slice(leading[0].length).match(patterns.rangeEnd)
+  if (!end || !/^\d+$/.test(first)) return [first]
+  const spanned = spannedPhaseIds(Number(first), Number(end[1]))
+  return spanned.length > 0 ? spanned : [first]
+}
+
 /**
  * The phase ids of a phases cell. An id counts where an entry starts: at the start of the cell or of a
  * sentence, after `;`, after a connector word (`P1 Index und P2 Suche`), or after `,` while a list that began
- * with an id is running (`P1 (#<number>), P2 (#<number>)`). A `P6` inside a sentence (`geht in P6 auf`, `abgeräumt,
+ * with an id is running (`P1 (#<number>), P2 (#<number>)`); an entry `P17–P25` names every phase it spans. A `P6` inside a sentence (`geht in P6 auf`, `abgeräumt,
  * P6 startet neu`) is prose.
  */
 const phaseIdsOf = (cell: string, patterns: PhaseIdPatterns): string[] => {
@@ -69,7 +88,7 @@ const phaseIdsOf = (cell: string, patterns: PhaseIdPatterns): string[] => {
     const leading = clause.match(patterns.leading)
     const startsEntry: boolean = entryStart || listRunning || patterns.afterConnector.test(clause)
     const counts: boolean = leading !== null && startsEntry
-    if (leading && counts) ids.push(leading[1])
+    if (leading && counts) ids.push(...leadingIds(clause, leading, patterns))
     ids.push(...[...clause.matchAll(patterns.connector)].map((match) => match[1]))
     listRunning ||= counts
   }
@@ -111,7 +130,8 @@ export const withoutRepeats = (lane: SprintLane, step: PlanStep): PlanStep => {
 /**
  * The lanes of the sprint document's lanes table (`## Spuren` in `de`) in table order. A row whose
  * first cell names a lane in backticks belongs to that lane; a `↳` row without a name continues
- * the lane above it.
+ * the lane above it. A cleaned-up lane stays closed through its `↳` rows, but a later row that names it again
+ * without the mark starts the lane anew: the closed rows are history and drop out.
  */
 export const parseSprintLanes = (markdown: string, language: PlanLanguage): SprintLane[] => {
   const lanes = new Map<string, SprintLane>()
@@ -123,7 +143,12 @@ export const parseSprintLanes = (markdown: string, language: PlanLanguage): Spri
     if (!name) continue
     const port = Number.parseInt(cells[1] ?? '', 10)
     const lane = lanes.get(name) ?? { name, port: Number.isNaN(port) ? null : port, steps: [], closed: false }
-    lane.closed ||= (cells[0] ?? '').includes(laneClosed)
+    const marked = (cells[0] ?? '').includes(laneClosed)
+    if (lane.closed && !marked && !(cells[0] ?? '').startsWith(CONTINUATION)) {
+      lane.closed = false
+      lane.steps = []
+    }
+    lane.closed ||= marked
     lane.steps.push(withoutRepeats(lane, toStep(cells, phaseId)))
     lanes.set(name, lane)
     previous = name

package/src/plan-format/short-names.ts

@@ -0,0 +1,71 @@
+import type { PlanLanguage } from '../vocabulary'
+import { endsPhase, isOpenCheckboxLine, isReviewGateLine, type PhaseHeading, phaseHeadings } from './phases'
+
+/** Characters a task's short name may have, so the herd shows it whole. */
+export const SHORT_NAME_LIMIT = 40
+
+/** Characters a phase title may have; the title is the phase's name. */
+export const PHASE_TITLE_LIMIT = 50
+
+export const SHORT_NAME_PROBLEM = { missing: 'missing', long: 'long' } as const
+
+/** What is wrong with an open task's short name: none at all, or one of `length` characters over the limit. */
+export type ShortNameProblem =
+  | { problem: typeof SHORT_NAME_PROBLEM.missing }
+  | { problem: typeof SHORT_NAME_PROBLEM.long; length: number }
+
+/** An open task (1-based line) of phase `phase` whose short name is missing or too long. */
+export type ShortNameFinding = { line: number; phase: string } & ShortNameProblem
+
+/** A phase heading whose title has `length` characters, over the limit. */
+export type LongPhaseTitle = PhaseHeading & { length: number }
+
+/** `- [ ] **Name**: …`, the name in group 1. */
+const SHORT_NAME = /^\s*[-*]\s+\[ \]\s+\*\*(.+?)\*\*:/
+
+const characterCount = (text: string): number => [...text].length
+
+const shortNameProblem = (line: string): ShortNameProblem | null => {
+  const name = line.match(SHORT_NAME)?.[1]
+  if (name === undefined) return { problem: SHORT_NAME_PROBLEM.missing }
+  const length = characterCount(name)
+  return length > SHORT_NAME_LIMIT ? { problem: SHORT_NAME_PROBLEM.long, length } : null
+}
+
+/**
+ * The open tasks a change wrote (a line not in `previousLines`) that do not start with `**Name**:` or whose name is
+ * longer than `SHORT_NAME_LIMIT`. Only tasks of a phase section before its review gate count: a gate item keeps its
+ * own form.
+ */
+export const shortNameFindings = (
+  markdown: string,
+  language: PlanLanguage,
+  previousLines: ReadonlySet<string>,
+): ShortNameFinding[] => {
+  const headings = new Map(phaseHeadings(markdown, language).map((heading) => [heading.line, heading.id]))
+  const found: ShortNameFinding[] = []
+  let phase: string | null = null
+  for (const [index, line] of markdown.split('\n').entries()) {
+    const heading = headings.get(index + 1)
+    if (heading !== undefined) phase = heading
+    else if (endsPhase(line) || isReviewGateLine(line)) phase = null
+    else if (phase !== null && isOpenCheckboxLine(line) && !previousLines.has(line)) {
+      const problem = shortNameProblem(line)
+      if (problem) found.push({ line: index + 1, phase, ...problem })
+    }
+  }
+  return found
+}
+
+/** The phase headings a change wrote whose title is longer than `PHASE_TITLE_LIMIT`. */
+export const longPhaseTitles = (
+  markdown: string,
+  language: PlanLanguage,
+  previousLines: ReadonlySet<string>,
+): LongPhaseTitle[] => {
+  const lines = markdown.split('\n')
+  return phaseHeadings(markdown, language)
+    .filter(({ line }) => !previousLines.has(lines[line - 1] ?? ''))
+    .map((heading) => ({ ...heading, length: characterCount(heading.title) }))
+    .filter(({ length }) => length > PHASE_TITLE_LIMIT)
+}

package/src/plan-format/terminal-text.ts

@@ -26,3 +26,7 @@ const UNSAFE_TERMINAL_TEXT = new RegExp(
  * on the terminal. Apply it where such text enters, before any styling is added.
  */
 export const terminalSafe = (text: string): string => text.replace(UNSAFE_TERMINAL_TEXT, '')
+
+/** The text cut to `max` characters with an ellipsis as the last one; text that fits stays as it is. */
+export const ellipsize = (text: string, max: number): string =>
+  text.length > max ? `${text.slice(0, max - 1)}…` : text

package/src/plan-format/waiting.ts

@@ -0,0 +1,53 @@
+import { type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
+import { firstTableWithHeader, sectionLines } from './markdown'
+import { terminalSafe } from './terminal-text'
+
+/** `file` for a file or an Artifact that was sent, `question` for a dialog that ended unanswered. */
+export const WAITING_KIND = { file: 'file', question: 'question' } as const
+
+export type WaitingKind = (typeof WAITING_KIND)[keyof typeof WAITING_KIND]
+
+/** One row of the board's section of what waits on the user: when it began (as written), what it is, whether it is open. */
+export type WaitingItem = {
+  since: string
+  item: string
+  open: boolean
+  /** A `file:` address the item links to, for a sent file; absent for a row of the board. */
+  url?: string
+  /** Absent for a row of the board. */
+  kind?: WaitingKind
+  /** The id of the record that closes it (`jh waiting close`); not shown. */
+  id?: string
+}
+
+const oneLine = (text: string): string => terminalSafe(text).replace(/\s+/g, ' ').trim()
+
+/** An empty status counts as open: a row nobody closed is not dropped in silence. */
+const isOpen = (status: string, language: PlanLanguage): boolean => {
+  const lower = status.toLowerCase()
+  return lower === '' || WAITING_VOCABULARY[language].open.some((word) => lower.startsWith(word))
+}
+
+/**
+ * The rows of the board's waiting section in `language` (`## Wartet auf dich`, `## Waiting for you`), its columns
+ * found by their header names in any order; the origin column is not read. A table without the since, item or status
+ * column, a section without a table and a row without an item give nothing.
+ */
+export const readWaitingItems = (board: string, language: PlanLanguage): WaitingItem[] => {
+  const { heading, columns, statusAlso } = WAITING_VOCABULARY[language]
+  const { header, rows } = firstTableWithHeader(sectionLines(board, heading))
+  const statusName = [columns.status, ...statusAlso].find((name) => header.includes(name)) ?? columns.status
+  const positions = [columns.since, columns.item, statusName].map((name) => header.indexOf(name))
+  if (positions.includes(-1)) return []
+  const [since, item, status] = positions
+  return rows.flatMap((cells) => {
+    const text = oneLine(cells[item] ?? '')
+    return text === ''
+      ? []
+      : [{ since: oneLine(cells[since] ?? ''), item: text, open: isOpen(cells[status] ?? '', language) }]
+  })
+}
+
+/** The open items, in the order of the board. */
+export const openWaitingItems = (board: string, language: PlanLanguage): WaitingItem[] =>
+  readWaitingItems(board, language).filter(({ open }) => open)

package/src/plans/active-tasks.ts

@@ -0,0 +1,60 @@
+import { sep } from 'node:path'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { matchSignals, type OpenPlanTask } from '../task-signals/matcher'
+import type { TaskSignal } from '../task-signals/types'
+import type { TaskPhase } from './current-task'
+
+/**
+ * A task an agent is working on: its index among the phase's checkboxes, who works on it (null while only one agent
+ * is active in the lane), whether the herd only guesses it from words, and when the agent began it (null for a guess).
+ */
+export type ActiveTask = { index: number; agent: string | null; guessed: boolean; startedAt: number | null }
+
+/** A task an agent reports that no open task of the plan names. */
+export type UnplannedTask = { text: string; agent: string | null }
+
+export type Assignment = { byPhase: ReadonlyMap<string, ActiveTask[]>; unplanned: UnplannedTask[] }
+
+const openTasksOf = (phases: readonly TaskPhase[]): OpenPlanTask[] =>
+  phases.flatMap(({ id, items }) =>
+    items.flatMap((item, taskIndex) => (item.done ? [] : [{ phaseId: id, taskIndex, text: item.text }])),
+  )
+
+/**
+ * Lays the reported `signals` over the plan's open tasks: each task an agent named is active, grouped by phase in the
+ * order of the signals, two agents on one task share it; a signal that names no open task is unplanned. Agent text is
+ * made terminal safe here, and the agent is named only when more than one agent reports.
+ */
+export const assignSignals = (phases: readonly TaskPhase[], signals: readonly TaskSignal[]): Assignment => {
+  const named = new Set(signals.map(({ agent }) => terminalSafe(agent))).size > 1
+  const nameOf = (agent: string): string | null => (named ? terminalSafe(agent) : null)
+  const byPhase = new Map<string, ActiveTask[]>()
+  const unplanned: UnplannedTask[] = []
+  for (const { signal, task } of matchSignals(openTasksOf(phases), signals)) {
+    if (task === null) {
+      unplanned.push({ text: terminalSafe(signal.text), agent: nameOf(signal.agent) })
+      continue
+    }
+    const tasks = byPhase.get(task.phaseId) ?? []
+    const shared = tasks.find(({ index }) => index === task.taskIndex)
+    const agent = nameOf(signal.agent)
+    if (shared) shared.agent = shared.agent && agent ? `${shared.agent}, ${agent}` : shared.agent
+    else tasks.push({ index: task.taskIndex, agent, guessed: false, startedAt: signal.startedAt })
+    byPhase.set(task.phaseId, tasks)
+  }
+  return { byPhase, unplanned }
+}
+
+/**
+ * The signals still believed: a `jh task` record counts only while it is younger than the lane's last tick, since a
+ * ticked box is the better witness that the agent moved on; Claude's own task list closes itself. Without a tick, all stay.
+ */
+export const freshSignals = (signals: readonly TaskSignal[], lastTickAt: number | null): TaskSignal[] =>
+  signals.filter(({ source, startedAt }) => source !== 'jh' || lastTickAt === null || startedAt >= lastTickAt)
+
+/** The lane a directory belongs to: the first directory below `worktrees` it lies in; null anywhere else. */
+export const laneOfDirectory = (directory: string, worktrees: string): string | null => {
+  const prefix = worktrees.endsWith(sep) ? worktrees : `${worktrees}${sep}`
+  if (!directory.startsWith(prefix)) return null
+  return directory.slice(prefix.length).split(sep)[0] || null
+}

package/src/plans/appointment-rows.ts

@@ -0,0 +1,59 @@
+import { twoDigits } from '../plan-format/clock'
+import { padVisible } from '../terminal/text'
+import { textWidth } from '../terminal/width'
+import type { PlanLanguage } from '../vocabulary'
+import { type Appointment, readAppointmentTable } from '../watch/appointments'
+import { shortTitle } from './task-name'
+import type { BlockItem } from './waiting-click'
+
+/** An open appointment as the herd shows it: `label` is the weekday and the time, `Mon 09:03` (the weekday is English whatever the board's language); `key` is the watcher's. */
+export type AppointmentRow = { key: string; label: string; action: string }
+
+/** The appointment block: the open rows, the earliest first. */
+export type AppointmentBlock = { rows: AppointmentRow[] }
+
+const APPOINTMENT_MARK = '◷'
+
+const WEEKDAY_LOCALE = 'en-US'
+
+const weekdayOf = (when: Date): string => new Intl.DateTimeFormat(WEEKDAY_LOCALE, { weekday: 'short' }).format(when)
+
+const rowOf = ({ when, action, key }: Appointment): AppointmentRow => ({
+  key,
+  label: `${weekdayOf(when)} ${twoDigits(when.getHours())}:${twoDigits(when.getMinutes())}`,
+  action,
+})
+
+/**
+ * The open appointments of the board's section, read as the watcher reads them, the earliest first. A done row, a
+ * row whose time cannot be read and a board without the section give no row.
+ */
+export const appointmentRows = (board: string, language: PlanLanguage, now: Date): AppointmentRow[] =>
+  readAppointmentTable(board, language, now)
+    .appointments.filter(({ open }) => open)
+    .sort((left, right) => left.when.getTime() - right.when.getTime())
+    .map(rowOf)
+
+/** The block of the board's open appointments, as the herd shows them. */
+export const appointmentBlock = (board: string, language: PlanLanguage, now: Date): AppointmentBlock => ({
+  rows: appointmentRows(board, language, now),
+})
+
+const appointmentKey = ({ key }: AppointmentRow): string => `appointment>${key}`
+
+/** The rows as the block draws them; a click on one only expands it, so they carry no address and no question. */
+export const appointmentItems = (rows: readonly AppointmentRow[]): BlockItem[] => {
+  const timeWidth = Math.max(0, ...rows.map(({ label }) => textWidth(label)))
+  return rows.map((row) => ({
+    key: appointmentKey(row),
+    mark: APPOINTMENT_MARK,
+    lead: padVisible(row.label, timeWidth),
+    text: row.action,
+    title: shortTitle(row.action),
+    url: null,
+    ask: null,
+  }))
+}
+
+/** The keys of all rows, the shown ones and the `+<n>` rest alike: what the fold of the block remembers. */
+export const appointmentKeys = (rows: readonly AppointmentRow[]): string[] => rows.map(appointmentKey)

package/src/plans/ask-coordinator.ts

@@ -0,0 +1,77 @@
+import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
+import { resolveCoordinatorName } from '../context/coordinator-name'
+import { laneSenderFor } from '../settled/send'
+import { type HerdrRunner, parseAgentList } from '../terminal/herdr'
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import { ASK_KIND, type AskTarget, boardRowKey } from './ask-target'
+import { errorText } from './error-text'
+import { isQuestionId } from './question-records'
+import { TEXTS } from './texts'
+
+/** What `askCoordinator` needs from the outside: the dialog language, the terminal, the repository and herdr. */
+export type AskDependencies = {
+  language: PlanLanguage
+  adapter: TerminalAdapter
+  /** The repository's directory name, from which the coordinator's herdr name follows. */
+  repository: string
+  run: HerdrRunner
+}
+
+type AskSentences = { question: (id: string) => string; boardRow: (key: string) => string }
+
+const ASK_LINES: Record<PlanLanguage, AskSentences> = {
+  [PLAN_LANGUAGE.de]: {
+    question: (id) => `Stell mir die offene Frage ${id} jetzt (jh waiting).`,
+    boardRow: (key) => `Stell mir die offene Board-Zeile \`${key}\` jetzt (jh waiting).`,
+  },
+  [PLAN_LANGUAGE.en]: {
+    question: (id) => `Ask me the open question ${id} now (jh waiting).`,
+    boardRow: (key) => `Ask me the open board row \`${key}\` now (jh waiting).`,
+  },
+}
+
+/**
+ * The line sent to the coordinator: a fixed sentence that carries the id of a question, or the sanitised key of a
+ * board row (`boardRowKey`), and nothing else from the board or the question, so a prompt line cannot be steered by
+ * the file it reads. The caller checks the id with `isQuestionId`.
+ */
+export const askLine = (target: AskTarget, language: PlanLanguage): string =>
+  target.kind === ASK_KIND.question
+    ? ASK_LINES[language].question(target.id)
+    : ASK_LINES[language].boardRow(boardRowKey(target.since, target.item))
+
+const isAskable = (target: AskTarget): boolean =>
+  target.kind === ASK_KIND.question ? isQuestionId(target.id) : boardRowKey(target.since, target.item) !== ''
+
+const subjectOf = (target: AskTarget): string =>
+  target.kind === ASK_KIND.question ? `question ${target.id}` : `board row ${boardRowKey(target.since, target.item)}`
+
+const agentNamesOf = (run: HerdrRunner): string[] => parseAgentList(run(['agent', 'list'])).map(({ name }) => name)
+
+/** The coordinator's herdr name, or why there is none to reach; without a terminal the sender gives the reason. */
+const coordinatorOf = ({ adapter, repository, run }: AskDependencies): { name: string } | { reason: string } => {
+  if (adapter === TERMINAL_ADAPTER.none) return { name: resolveCoordinatorName(repository, []) }
+  try {
+    const names = agentNamesOf(run)
+    const name = resolveCoordinatorName(repository, names)
+    return names.includes(name) ? { name } : { reason: `no agent named ${name}` }
+  } catch (error) {
+    return { reason: errorText(error) }
+  }
+}
+
+/**
+ * Asks the coordinator, by `herdr agent prompt`, to put the open question or board row `target` to the user. A
+ * coordinator that is working gets the line too: herdr queues it like a message in the middle of a turn. Returns the
+ * footer line: who was asked, or why nobody was.
+ */
+export const askCoordinator = (target: AskTarget, dependencies: AskDependencies): string => {
+  if (!isAskable(target)) return TEXTS.notAsked('nothing to ask')
+  const coordinator = coordinatorOf(dependencies)
+  if ('reason' in coordinator) return TEXTS.notAsked(coordinator.reason)
+  const failure = laneSenderFor(dependencies.adapter, dependencies.run)(
+    coordinator.name,
+    askLine(target, dependencies.language),
+  )
+  return failure === null ? TEXTS.asked(coordinator.name, subjectOf(target)) : TEXTS.notAsked(failure)
+}

package/src/plans/ask-target.ts

@@ -0,0 +1,25 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+
+/** What the coordinator can be asked to put to the user: an open dialog question, or an open row of the board. */
+export const ASK_KIND = { question: 'question', boardRow: 'boardRow' } as const
+
+export type AskTarget =
+  | { kind: typeof ASK_KIND.question; id: string }
+  | { kind: typeof ASK_KIND.boardRow; since: string; item: string }
+
+/** The longest key a prompt line carries for a board row, the ellipsis included. */
+export const MAX_ROW_KEY_LENGTH = 120
+
+const ROW_KEY_SEPARATOR = ' · '
+
+const safeCell = (text: string): string => terminalSafe(text.replace(/\s+/g, ' ')).replaceAll('`', "'").trim()
+
+/**
+ * The key of a board row as it goes into a prompt line: since and item on one line, free of control characters and
+ * backticks (the line quotes the key in backticks), cut to `MAX_ROW_KEY_LENGTH`. The text comes from the board, so
+ * it is never trusted as it is.
+ */
+export const boardRowKey = (since: string, item: string): string => {
+  const cells = [safeCell(since), safeCell(item)].filter((cell) => cell !== '')
+  return ellipsize(cells.join(ROW_KEY_SEPARATOR), MAX_ROW_KEY_LENGTH)
+}

package/src/plans/child-stop.ts

@@ -0,0 +1,51 @@
+/** Milliseconds a child gets to end after a signal before it is killed. */
+export const GRACE_MS = 2000
+
+export type StopperDeps = {
+  kill: (signal: NodeJS.Signals) => void
+  setTimer: (run: () => void, ms: number) => unknown
+  clearTimer: (handle: unknown) => void
+}
+
+export const STOP_REQUEST = { forwarded: 'forwarded', killed: 'killed' } as const
+
+export type StopRequest = (typeof STOP_REQUEST)[keyof typeof STOP_REQUEST]
+
+export type Stopper = {
+  /** The first call forwards `signal` and arms the kill; any further call kills at once. */
+  request: (signal: NodeJS.Signals) => StopRequest
+  /** The child has ended: nothing is left to kill. */
+  ended: () => void
+}
+
+/**
+ * Stops one child: the signal goes to it, and a child that ignores it is killed once `GRACE_MS` have passed, so a
+ * supervisor never waits on a view that does not end.
+ */
+export const stopperOf = ({ kill, setTimer, clearTimer }: StopperDeps): Stopper => {
+  let timer: unknown
+  let requested = false
+
+  const send = (signal: NodeJS.Signals): void => {
+    try {
+      kill(signal)
+    } catch {
+      // the child is already gone
+    }
+  }
+
+  return {
+    request: (signal) => {
+      if (requested) {
+        clearTimer(timer)
+        send('SIGKILL')
+        return STOP_REQUEST.killed
+      }
+      requested = true
+      send(signal)
+      timer = setTimer(() => send('SIGKILL'), GRACE_MS)
+      return STOP_REQUEST.forwarded
+    },
+    ended: () => clearTimer(timer),
+  }
+}

package/src/plans/closable-records.ts

@@ -0,0 +1,34 @@
+import { join } from 'node:path'
+import { readRecords, writeRecordAtomically } from '../shared/private-records'
+
+/** A record that waits on the user until something sets `closedAt`. */
+export type ClosableRecord = { id: string; closedAt: number | null }
+
+export type ClosableRecordLog<T extends ClosableRecord> = {
+  /** Every record of the log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
+  read: (root: string) => T[]
+  /** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+  close: (root: string, ids: readonly string[], now: number) => number
+  /** Marks every open record `closedAt` and returns how many it closed. */
+  closeAll: (root: string, now: number) => number
+}
+
+/** The log of `.jackherd/<directoryName>/`: records the `guard` accepts, ordered by `timeOf`. */
+export const closableRecordLog = <T extends ClosableRecord>(
+  directoryName: string,
+  guard: (value: unknown) => value is T,
+  timeOf: (record: T) => number,
+): ClosableRecordLog<T> => {
+  const directoryOf = (root: string): string => join(root, '.jackherd', directoryName)
+  const read = (root: string): T[] => readRecords(directoryOf(root), guard, timeOf)
+  const closeWhere = (root: string, isChosen: (record: T) => boolean, now: number): number => {
+    const open = read(root).filter((record) => record.closedAt === null && isChosen(record))
+    for (const record of open) writeRecordAtomically(directoryOf(root), { ...record, closedAt: now })
+    return open.length
+  }
+  return {
+    read,
+    close: (root, ids, now) => closeWhere(root, (record) => ids.includes(record.id), now),
+    closeAll: (root, now) => closeWhere(root, () => true, now),
+  }
+}

package/src/plans/command.ts

@@ -6,6 +6,7 @@ import { boardFor, foundLanesOf } from './board-pick'
 import { ensurePlanPanes } from './ensure-panes'
 import { mainCheckout, worktreeRoot } from './git'
 import { fetchPullRequests } from './github'
+import { claimOwnTerminal, startExclusive } from './herd-claim'
 import { recallLanes, rememberLanes } from './herd-memory'
 import { runLive } from './live'
 import { parseOptions } from './options'
@@ -59,8 +60,8 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
     }
     const source = { root, sprintFile: picked.file, options, settings, terminal }
     if (options.once || !process.stdout.isTTY) await printOnceWithNotice(source, picked.notice)
-    else if (isSupervisedChild(process.env)) runLive(source)
-    else return await superviseView(args, await startedKit())
+    else if (isSupervisedChild(process.env)) await startExclusive(claimOwnTerminal, () => runLive(source))
+    else process.exit(await superviseView(args, await startedKit()))
     return 0
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))