jackherd 1.9.0 → 1.10.0

package/src/lane-prompt/input.ts

@@ -0,0 +1,116 @@
+import { type PhaseDependency, parseDependencyTable, writeSetOf } from '../plan-format/dependencies'
+import { parseSprintLanes, phaseLabel, resolvePlanPath, type SprintLane } from '../plan-format/lanes'
+import { parsePlanPhases } from '../plan-format/phases'
+import { isPhaseFinished } from '../plan-format/progress'
+import type { PlanLanguage } from '../vocabulary'
+import type { LanePhase, LanePlan, LanePromptInput } from './build'
+
+/** The lane to prompt, the hand-over file of a restart (null for a fresh start) and the plan language. */
+export type LanePromptRequest = { lane: string; handover: string | null; language: PlanLanguage }
+
+/**
+ * The board's text, its directory from the repository root, which its plan links are relative to, and the path a
+ * refusal names it by.
+ */
+export type BoardSource = { text: string; directory: string; path: string }
+
+/** A plan's text by its path from the repository root; null when it cannot be read. */
+export type ReadPlan = (path: string) => string | null
+
+export type LanePromptResult = { kind: 'prompt'; input: LanePromptInput } | { kind: 'refused'; reason: string }
+
+type PlanSteps = { path: string; ids: string[] }
+
+type Refusal = { reason: string }
+
+type PlanOutcome = { plan: LanePlan } | Refusal
+
+type PlansOutcome = { plans: LanePlan[] } | Refusal
+
+const refused = (reason: string): LanePromptResult => ({ kind: 'refused', reason })
+
+/** The lane's plans by path in board order, each with the phase ids its rows name, rows of one plan merged. */
+const planStepsOf = (lane: SprintLane, directory: string): PlanSteps[] => {
+  const byPath = new Map<string, string[]>()
+  for (const step of lane.steps) {
+    if (step.planHref === null || step.phaseIds.length === 0) continue
+    const path = resolvePlanPath(directory, step.planHref)
+    byPath.set(path, [...new Set([...(byPath.get(path) ?? []), ...step.phaseIds])])
+  }
+  return [...byPath].map(([path, ids]) => ({ path, ids }))
+}
+
+/** The write set of the phase `id`; null without a row, for an unknown target or a cycle. */
+const phaseWriteSet = (rows: readonly PhaseDependency[], id: string): string[] | null => {
+  const row = rows.find((candidate) => candidate.id === id)
+  return row ? writeSetOf(row, new Map(rows.map((candidate) => [candidate.id, candidate]))) : null
+}
+
+/** A plan's text on the lane branch (null without a worktree or a copy there) and in the main checkout. */
+type PlanTexts = { lane: string | null; main: string | null }
+
+const finishedIdsOf = (text: string | null, language: PlanLanguage): Set<string> =>
+  new Set(
+    text === null ? [] : parsePlanPhases(text, language).flatMap((phase) => (isPhaseFinished(phase) ? [phase.id] : [])),
+  )
+
+/**
+ * The plan's open named phases, read from the lane branch when it has a copy, which holds the phases the lane wrote
+ * and the ticks it set; a phase finished in either copy is left out, so a lane branch behind the main checkout does not
+ * bring back what another lane finished.
+ */
+const lanePlanOf = (steps: PlanSteps, texts: PlanTexts, text: string, language: PlanLanguage): PlanOutcome => {
+  const phases = parsePlanPhases(text, language)
+  const named = steps.ids.map((id) => ({ id, phase: phases.find((phase) => phase.id === id) }))
+  const missing = named.find(({ phase }) => phase === undefined)
+  if (missing) return { reason: `${steps.path} has no phase ${phaseLabel(missing.id)}` }
+  const rows = parseDependencyTable(text, language) ?? []
+  const finishedInMain = finishedIdsOf(texts.main, language)
+  const open = named.filter(
+    ({ id, phase }) => phase !== undefined && !isPhaseFinished(phase) && !finishedInMain.has(id),
+  )
+  const lanePhases: LanePhase[] = open.map(({ id }) => ({ id, writes: phaseWriteSet(rows, id) }))
+  return { plan: { path: steps.path, phases: lanePhases } }
+}
+
+const plansOf = (
+  steps: readonly PlanSteps[],
+  readers: { main: ReadPlan; lane: ReadPlan },
+  language: PlanLanguage,
+): PlansOutcome => {
+  const plans: LanePlan[] = []
+  for (const step of steps) {
+    const texts = { lane: readers.lane(step.path), main: readers.main(step.path) }
+    const text = texts.lane ?? texts.main
+    if (text === null) return { reason: `cannot read the plan ${step.path}` }
+    const outcome = lanePlanOf(step, texts, text, language)
+    if ('reason' in outcome) return outcome
+    if (outcome.plan.phases.length > 0) plans.push(outcome.plan)
+  }
+  return { plans }
+}
+
+/**
+ * What the lane's prompt is built from: its open row of the board's lanes table (port, plans, phases), each named
+ * phase that is not finished, and the write set of each from its plan's dependency table. A plan is read from the lane
+ * branch (`readLanePlan`) when it has a copy, else from the main checkout (`readPlan`). Refused, with the reason,
+ * for a lane without a row, a closed lane, rows that name no phase, a plan that cannot be read or lacks a phase the
+ * row names, and a lane whose phases are all finished.
+ */
+export const lanePromptInputOf = (
+  request: LanePromptRequest,
+  board: BoardSource,
+  readPlan: ReadPlan,
+  readLanePlan: ReadPlan = () => null,
+): LanePromptResult => {
+  const sprintLane = parseSprintLanes(board.text, request.language).find((candidate) => candidate.name === request.lane)
+  if (!sprintLane) return refused(`no row for lane ${request.lane} in ${board.path}`)
+  if (sprintLane.closed) return refused(`lane ${request.lane} is closed in ${board.path}`)
+  const steps = planStepsOf(sprintLane, board.directory)
+  if (steps.length === 0) return refused(`the row of lane ${request.lane} in ${board.path} links no plan with a phase`)
+  const found = plansOf(steps, { main: readPlan, lane: readLanePlan }, request.language)
+  if ('reason' in found) return refused(found.reason)
+  if (found.plans.length === 0) return refused(`every phase of lane ${request.lane} is finished`)
+  const { lane, handover, language } = request
+  return { kind: 'prompt', input: { language, lane, plans: found.plans, port: sprintLane.port, handover } }
+}

package/src/lane-prompt/options.ts

@@ -0,0 +1,68 @@
+import { CLI_NAME } from '../version/release'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+
+/** What `jh lane prompt` was asked for; null where an option was left out. */
+export type LanePromptOptions = { lane: string; boardPath: string | null; out: string | null; handover: string | null }
+
+const VALUE_OPTIONS = ['--board', '--out', '--handover'] as const
+
+type ValueOption = (typeof VALUE_OPTIONS)[number]
+
+const SUBCOMMAND = 'prompt'
+
+export const LANE_PROMPT_USAGE = `usage: ${CLI_NAME} lane prompt <lane> [--board <board.md>] [--out <file>] [--handover <file>]
+
+Writes the prompt that starts the lane, from its row in the board and its plan, and prints the file's path.
+  --board <board.md>   the board to read; without it the board is picked as for ${CLI_NAME} herd
+  --out <file>         where to write the prompt; default .claude/handover/<lane>-prompt.md in the main checkout
+  --handover <file>    a restart after a hand-over: the lane reads this file first and continues with its next step`
+
+const usageError = (message: string): Error => new Error(`${message}\n${LANE_PROMPT_USAGE}`)
+
+const isValueOption = (arg: string): arg is ValueOption => (VALUE_OPTIONS as readonly string[]).includes(arg)
+
+const splitArguments = (args: readonly string[]): { values: Map<ValueOption, string>; words: string[] } => {
+  const values = new Map<ValueOption, string>()
+  const words: string[] = []
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (!arg.startsWith('--')) {
+      words.push(arg)
+      continue
+    }
+    if (!isValueOption(arg)) throw usageError(`unknown option ${arg}`)
+    const value = args[i + 1]
+    if (value === undefined || value.startsWith('--')) throw usageError(`${arg} needs a value`)
+    values.set(arg, value)
+    i += 1
+  }
+  return { values, words }
+}
+
+const laneOf = (words: readonly string[]): string => {
+  const [subcommand, ...lanes] = words
+  if (subcommand !== SUBCOMMAND)
+    throw usageError(subcommand ? `unknown subcommand ${subcommand}` : 'the subcommand is required')
+  if (lanes.length === 0) throw usageError('the lane is required')
+  if (lanes.length > 1) throw usageError(`one lane at most, got ${lanes.join(' ')}`)
+  if (!SAFE_LANE_NAME.test(lanes[0])) throw usageError(`${lanes[0]} is no lane name (letters, digits, . _ -)`)
+  return lanes[0]
+}
+
+/** The hand-over path as the prompt quotes it in backticks: one line without a backtick. */
+const handoverOf = (value: string | undefined): string | null => {
+  if (value === undefined) return null
+  if (/[`\r\n]/.test(value)) throw usageError('--handover needs a path without backticks or line breaks')
+  return value
+}
+
+/** Reads `prompt <lane> [--board …] [--out …] [--handover …]` in any order; throws on a wrong command line. */
+export const parseLanePromptOptions = (args: readonly string[]): LanePromptOptions => {
+  const { values, words } = splitArguments(args)
+  return {
+    lane: laneOf(words),
+    boardPath: values.get('--board') ?? null,
+    out: values.get('--out') ?? null,
+    handover: handoverOf(values.get('--handover')),
+  }
+}

package/src/lane-prompt/texts.ts

@@ -0,0 +1,101 @@
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+
+/**
+ * The sentences of a lane prompt in one language, after `/orchestrate` § 1. The opening words and the column name of
+ * a write set come from the vocabulary; the report file keeps its `## Questions` heading in every language, since the
+ * watcher finds the section by that word.
+ */
+export type LanePromptTexts = {
+  answersTo: string
+  phasesIntro: string
+  noWrites: string
+  wholeRepository: string
+  editInside: string
+  writeTools: string
+  port: (port: number) => string
+  noPort: string
+  blocking: string
+  mustNot: string
+  commit: string
+  report: (reportPath: string) => string
+  textBlock: string
+  secret: string
+  askRule: string
+  approvalGate: string
+  helper: (helperName: string) => string
+  helperPurpose: string
+  start: string
+  restart: (handoverPath: string) => string
+}
+
+export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
+  [PLAN_LANGUAGE.en]: {
+    answersTo: 'You answer to the coordinator, not to the user.',
+    phasesIntro: 'Your plan and phases:',
+    noWrites: 'no Writes set in the plan',
+    wholeRepository: 'the whole repository',
+    editInside:
+      'Nothing outside the Writes set of your phases is edited, except the task lines of your phases in the plan: tick a finished one right away, by an Edit of exactly that line.',
+    writeTools:
+      'Write code and tests with Write and Edit, never through a here-document or a script in Bash: such a call shows the reviewer no diff, and an unquoted or unreadable one can stop at a guard.',
+    port: (port) =>
+      `Port ${port}: the coordinator runs your dev server in its own pane; look at your visible changes there (\`/implement\` Step 4b) and never start a server in your own shell.`,
+    noPort:
+      'No port: this lane has no dev server of its own. Never start a server in your own shell; ask the coordinator when you need one.',
+    blocking:
+      'Mark every question of yours `blocking` or `not blocking`. A blocking one stops the step it decides; for a not blocking one leave a `TODO` at its spot and work on, building neither your recommendation nor another option as decided.',
+    mustNot:
+      'Without the user’s approval you push no database migration and write nothing against a shared environment (stage, production); you never run `git reset` or `git stash` on shared refs.',
+    commit: 'Ask before every commit (`/pre-commit`); no push, PR or merge without approval.',
+    report: (reportPath) =>
+      `The report at the end of each step goes to \`${reportPath}\` in the worktree, in the short form: one line of diff stat, one line per check with its numbers, open points, questions as a text block under the heading \`## Questions\` (whatever the report’s language: the watcher finds the section by that word and shows it whole); everything else is in the plan, by reference.`,
+    textBlock:
+      'Every question to the coordinator is a text block at the end of your turn, never a dialog (`AskUserQuestion`), also where a skill or a project rule asks for one, the commit confirmation of `/pre-commit` included: the question with the situation, the problem and what each option leads to, in everyday words (the user may not know your terms), the options, your recommendation, the evidence at `file:line`.',
+    secret:
+      'A value only the user knows (a secret, password, token or one-time code) never passes through you, your arguments, your output or a file you write: ask the coordinator for the step as a question.',
+    askRule:
+      'A tool that asks for approval on every call (an ask rule, such as a database query tool or a project CLI) gets as few calls as possible: bundle the steps into one call (one script, one query) instead of one call per step.',
+    approvalGate:
+      'A call that would open a permission dialog waits for the coordinator: the approval gate holds it and the coordinator asks the user. Denied with “approval pending”, retry the same call once the coordinator says it is approved; denied by the user, do not retry it.',
+    helper: (helperName) =>
+      `A helper agent in a pane of your own (a measurement, a probe session) is announced to the coordinator before it starts, as a question at the end of your turn: what it does, how long, and which temporary settings it uses. Once approved, name it \`${helperName}\` (\`herdr agent rename\`), so the watcher watches it with your lane, and close it yourself when it is done: \`/exit\`, then \`herdr pane close\`, and remove every temporary file it needed.`,
+    helperPurpose: '<purpose>',
+    start: 'Start: run `/implement` for your phases, in the order above.',
+    restart: (handoverPath) => `Start: read \`${handoverPath}\` first and continue with the next step it names.`,
+  },
+  [PLAN_LANGUAGE.de]: {
+    answersTo: 'Du antwortest dem Koordinator, nicht dem User.',
+    phasesIntro: 'Dein Plan und deine Phasen:',
+    noWrites: 'keine Schreibt-Menge im Plan',
+    wholeRepository: 'das ganze Repository',
+    editInside:
+      'Außerhalb der Schreibt-Menge deiner Phasen änderst du nichts, außer den Aufgabenzeilen deiner Phasen im Plan: eine erledigte hakst du sofort ab, per Edit auf genau diese Zeile.',
+    writeTools:
+      'Code und Tests schreibst du mit Write und Edit, nie per Heredoc oder Skript in Bash: ein solcher Aufruf zeigt dem Prüfer keinen Diff, und ein ungequoteter oder unlesbarer kann an einem Wächter hängen bleiben.',
+    port: (port) =>
+      `Port ${port}: Der Koordinator betreibt deinen Dev-Server in seinem eigenen Pane; deine sichtbaren Änderungen siehst du dort an (\`/implement\` Step 4b) und startest nie einen Server in deiner eigenen Shell.`,
+    noPort:
+      'Kein Port: Diese Spur hat keinen eigenen Dev-Server. Starte nie einen Server in deiner eigenen Shell; brauchst du einen, frag den Koordinator.',
+    blocking:
+      'Markiere jede deiner Fragen mit `blocking` oder `not blocking`. Eine blockierende hält den Schritt an, den sie entscheidet; bei einer nicht blockierenden lässt du an ihrer Stelle ein `TODO` und arbeitest weiter, ohne deine Empfehlung oder eine andere Option als entschieden zu bauen.',
+    mustNot:
+      'Ohne Freigabe des Users pushst du keine Datenbank-Migration und schreibst nichts gegen eine geteilte Umgebung (Stage, Produktion); `git reset` und `git stash` auf geteilten Refs führst du nie aus.',
+    commit: 'Vor jedem Commit fragst du (`/pre-commit`); kein Push, kein PR und kein Merge ohne Freigabe.',
+    report: (reportPath) =>
+      `Den Bericht am Ende jedes Schritts schreibst du nach \`${reportPath}\` im Worktree, in der Kurzform: eine Zeile Diff-Stat, eine Zeile je Check mit seinen Zahlen, offene Punkte, Fragen als Textblock unter der Überschrift \`## Questions\` (in jeder Berichtssprache: der Watcher findet den Abschnitt an diesem Wort und zeigt ihn ganz); alles andere steht im Plan, per Verweis.`,
+    textBlock:
+      'Jede Frage an den Koordinator ist ein Textblock am Ende deines Turns, nie ein Dialog (`AskUserQuestion`), auch wo ein Skill oder eine Projektregel einen verlangt, die Commit-Bestätigung von `/pre-commit` eingeschlossen: die Frage mit der Lage, dem Problem und wohin jede Option führt, in Alltagsworten (der User kennt deine Begriffe vielleicht nicht), die Optionen, deine Empfehlung, der Beleg als `datei:zeile`.',
+    secret:
+      'Ein Wert, den nur der User kennt (ein Geheimnis, Passwort, Token oder Einmalcode), läuft nie über dich, deine Argumente, deine Ausgabe oder eine Datei, die du schreibst: bitte den Koordinator mit einer Frage um diesen Schritt.',
+    askRule:
+      'Ein Werkzeug, das bei jedem Aufruf um Freigabe fragt (eine Ask-Regel, etwa ein Datenbank-Abfragewerkzeug oder eine Projekt-CLI), bekommt so wenige Aufrufe wie möglich: bündle die Schritte in einen Aufruf (ein Skript, eine Abfrage) statt eines Aufrufs je Schritt.',
+    approvalGate:
+      'Ein Aufruf, der einen Erlaubnis-Dialog öffnen würde, wartet auf den Koordinator: Das Approval-Gate hält ihn an, und der Koordinator fragt den User. Abgelehnt mit „approval pending“: denselben Aufruf wiederholen, sobald der Koordinator ihn als freigegeben meldet; vom User abgelehnt: nicht wiederholen.',
+    helper: (helperName) =>
+      `Einen Helfer-Agenten in einem eigenen Pane (eine Messung, eine Probesitzung) meldest du dem Koordinator an, bevor er startet, als Frage am Ende deines Turns: was er tut, wie lange, und welche temporären Einstellungen er nutzt. Nach der Freigabe benennst du ihn \`${helperName}\` (\`herdr agent rename\`), damit der Watcher ihn mit deiner Spur beobachtet, und schließt ihn selbst, wenn er fertig ist: \`/exit\`, dann \`herdr pane close\`, und entferne jede temporäre Datei, die er brauchte.`,
+    helperPurpose: '<zweck>',
+    start: 'Start: Führe `/implement` für deine Phasen aus, in der Reihenfolge oben.',
+    restart: (handoverPath) =>
+      `Start: Lies zuerst \`${handoverPath}\` und mach mit dem nächsten Schritt weiter, den sie nennt.`,
+  },
+}

package/src/plan-format/clock.ts

@@ -1,4 +1,12 @@
 export const MS_PER_MINUTE = 60_000
 
+export const DAY_MS = 86_400_000
+
 /** A day, month, hour or minute with a leading zero: `7` → `07`. */
 export const twoDigits = (value: number): string => String(value).padStart(2, '0')
+
+/** A time as the for-you rows show it: `DD.MM. HH:MM`. */
+export const clockText = (at: number): string => {
+  const date = new Date(at)
+  return `${twoDigits(date.getDate())}.${twoDigits(date.getMonth() + 1)}. ${twoDigits(date.getHours())}:${twoDigits(date.getMinutes())}`
+}

package/src/plan-format/dependencies.ts

@@ -200,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}/`)
 
@@ -228,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/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/waiting.ts

@@ -2,6 +2,11 @@ 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
@@ -9,8 +14,8 @@ export type WaitingItem = {
   open: boolean
   /** A `file:` address the item links to, for a sent file; absent for a row of the board. */
   url?: string
-  /** `file` for a file or an Artifact that was sent; absent for a question of the board. */
-  kind?: 'file'
+  /** Absent for a row of the board. */
+  kind?: WaitingKind
   /** The id of the record that closes it (`jh waiting close`); not shown. */
   id?: string
 }

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),
+  }
+}