jackherd 1.9.0 → 1.11.0

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/mermaid/command.ts

@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs'
+import { asksForHelp } from '../preview/options'
+import { CLI_NAME } from '../version/release'
+import { type MermaidProblem, mermaidProblems } from './problems'
+
+const USAGE = `usage: ${CLI_NAME} mermaid <file.md>
+
+Checks every \`\`\`mermaid block of the file for edge labels GitHub does not draw (a label between the dashes,
+a pipe label without quotes). Run it on a pull request body before gh pr create or gh pr edit.
+Exit 0 clean, 1 with problems or a wrong command line.`
+
+/** One line per problem, `file:line: reason`, then the offending text indented. */
+const problemLines = (file: string, problems: readonly MermaidProblem[]): string[] =>
+  problems.flatMap(({ line, reason, text }) => [`${file}:${line}: ${reason}`, `    ${text}`])
+
+export const run = (args: string[]): number => {
+  if (asksForHelp(args)) {
+    console.log(USAGE)
+    return 0
+  }
+  const [file, ...rest] = args
+  if (file === undefined || rest.length > 0) {
+    console.error(USAGE)
+    return 1
+  }
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    console.error(`cannot read ${file}`)
+    return 1
+  }
+  const problems = mermaidProblems(text)
+  for (const line of problemLines(file, problems)) console.error(line)
+  return problems.length === 0 ? 0 : 1
+}

package/src/mermaid/problems.ts

@@ -0,0 +1,48 @@
+/** A line of a Mermaid block that GitHub fails to draw: its 1-based line in the text, the line itself and why. */
+export type MermaidProblem = { line: number; text: string; reason: string }
+
+const FENCE = /^\s*(```|~~~)\s*(\S*)/
+const FLOWCHART = /^\s*(?:flowchart|graph)\b/
+/** A label written between the dashes of the link, `a -- text --> b`: a `--` inside the text ends the link early. */
+const LABEL_BETWEEN_DASHES = /\s(?:--|==)\s+\S.*?\s(?:-->|---|==>)(?:\s|$)/
+/** A pipe label that does not open with a quote: a comma, colon or parenthesis in it breaks the parser. */
+const UNQUOTED_PIPE_LABEL = /(?:-->|---|-\.->|==>)\|[^"|]/
+
+const REASON = {
+  betweenDashes: 'edge label between dashes: write -->|"label"|',
+  unquoted: 'edge label without quotes: write -->|"label"|',
+} as const
+
+const reasonOf = (text: string): string | null => {
+  if (LABEL_BETWEEN_DASHES.test(text)) return REASON.betweenDashes
+  return UNQUOTED_PIPE_LABEL.test(text) ? REASON.unquoted : null
+}
+
+/**
+ * The edge labels in the flowcharts of `markdown` that GitHub does not draw: ones written between the dashes and
+ * pipe labels without quotes. Only fenced blocks marked `mermaid` are read (a block never closed runs to the end of the
+ * text); the form that always parses is `-->|"label"|`.
+ */
+export const mermaidProblems = (markdown: string): MermaidProblem[] => {
+  const problems: MermaidProblem[] = []
+  let fence: string | null = null
+  let isFlowchart = false
+  markdown.split('\n').forEach((text, index) => {
+    const opening = FENCE.exec(text)
+    if (fence === null) {
+      if (opening?.[2] === 'mermaid') {
+        fence = opening[1] ?? '```'
+        isFlowchart = false
+      }
+      return
+    }
+    if (opening && opening[1] === fence && opening[2] === '') {
+      fence = null
+      return
+    }
+    if (FLOWCHART.test(text)) isFlowchart = true
+    const reason = isFlowchart ? reasonOf(text) : null
+    if (reason) problems.push({ line: index + 1, text: text.trim(), reason })
+  })
+  return problems
+}

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

@@ -81,10 +81,10 @@ const dependsOf = (cell: string, language: PlanLanguage): Pick<PhaseDependency,
 /**
  * A path as the cell writes it, cut to the directory a glob character starts in (`scripts/*.ts` is `scripts`,
  * `.claude/**` is `.claude`, `*.md` is the root `''`) and without a trailing slash; null for a backticked entry with a
- * space in it, which is a command.
+ * space in it, which is a command, and for one with `[]`, which is a config key (`watch.sources[].label`) and no glob.
  */
 const pathOf = (entry: string): string | null => {
-  if (/\s/.test(entry)) return null
+  if (/\s/.test(entry) || entry.includes('[]')) return null
   const glob = entry.search(GLOB_CHARACTER)
   const literal = glob === -1 ? entry : entry.slice(0, Math.max(entry.lastIndexOf('/', glob), 0))
   const path = literal.replace(/^\.\//, '').replace(/\/+$/, '')
@@ -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,15 +2,24 @@ 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
+  /** The board row's origin cell, one line; absent when the table has no such column or the cell is empty. */
+  origin?: string
+  /** What the herd shows before the item (the label of the source the row came from); set by the herd, never read from the board. */
+  prefix?: string
   /** 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
 }
@@ -25,7 +34,7 @@ const isOpen = (status: string, language: PlanLanguage): boolean => {
 
 /**
  * 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
+ * found by their header names in any order; the origin column is read when the table has it and the cell is not empty. 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[] => {
@@ -35,11 +44,20 @@ export const readWaitingItems = (board: string, language: PlanLanguage): Waiting
   const positions = [columns.since, columns.item, statusName].map((name) => header.indexOf(name))
   if (positions.includes(-1)) return []
   const [since, item, status] = positions
+  const originPosition = header.indexOf(columns.origin)
   return rows.flatMap((cells) => {
     const text = oneLine(cells[item] ?? '')
+    const origin = oneLine(cells[originPosition] ?? '')
     return text === ''
       ? []
-      : [{ since: oneLine(cells[since] ?? ''), item: text, open: isOpen(cells[status] ?? '', language) }]
+      : [
+          {
+            since: oneLine(cells[since] ?? ''),
+            item: text,
+            open: isOpen(cells[status] ?? '', language),
+            ...(origin === '' ? {} : { origin }),
+          },
+        ]
   })
 }
 

package/src/plans/appointment-rows.ts

@@ -0,0 +1,83 @@
+import { DAY_MS, 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 { ASK_KIND } from './ask-target'
+import { DONE_KIND } from './row-targets'
+import { shortTitle } from './task-name'
+import { type BlockButton, type BlockItem, DONE_BUTTON, MOVE_BUTTON, RUN_BUTTON } 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; when: 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 DATE_FROM_DAYS_AHEAD = 7
+
+const startOfDay = (when: Date): number => new Date(when.getFullYear(), when.getMonth(), when.getDate()).getTime()
+
+const daysAhead = (when: Date, now: Date): number => Math.round((startOfDay(when) - startOfDay(now)) / DAY_MS)
+
+/** The weekday names a day within the week; from a week on it is the date, `13.01.`, since the weekday would repeat. */
+const dayOf = (when: Date, now: Date): string =>
+  daysAhead(when, now) >= DATE_FROM_DAYS_AHEAD
+    ? `${twoDigits(when.getDate())}.${twoDigits(when.getMonth() + 1)}.`
+    : weekdayOf(when)
+
+const rowOf =
+  (now: Date) =>
+  ({ when, whenText, action, key }: Appointment): AppointmentRow => ({
+    key,
+    when: whenText,
+    label: `${dayOf(when, now)} ${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(now))
+
+/** 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}`
+
+const buttonsOf = ({ when, action }: AppointmentRow): BlockButton[] => [
+  { label: DONE_BUTTON, click: { done: { kind: DONE_KIND.appointment, when, action } } },
+  { label: RUN_BUTTON, click: { ask: { kind: ASK_KIND.appointmentRun, when, action } } },
+  { label: MOVE_BUTTON, click: { ask: { kind: ASK_KIND.appointmentMove, when, action } } },
+]
+
+/** The rows as the block draws them; a click on the row only expands it, the buttons close it, run it or move it. */
+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,
+    buttons: buttonsOf(row),
+  }))
+}
+
+/** 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,111 @@
+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
+}
+
+/** A sentence takes the subject's key and, for an entry of a source, the source it belongs to (else `''`). */
+type AskSentences = Record<AskTarget['kind'], (subject: string, scope: string) => string>
+
+const ASK_LINES: Record<PlanLanguage, AskSentences> = {
+  [PLAN_LANGUAGE.de]: {
+    [ASK_KIND.question]: (id) => `Stell mir die offene Frage ${id} jetzt (jh waiting).`,
+    [ASK_KIND.boardRow]: (key) => `Stell mir die offene Board-Zeile \`${key}\` jetzt (jh waiting).`,
+    [ASK_KIND.appointmentRun]: (key) => `Führe den Termin \`${key}\` jetzt aus, unter den Freigaben, die er braucht.`,
+    [ASK_KIND.appointmentMove]: (key) =>
+      `Frag den User per Dialog nach der neuen Zeit für den Termin \`${key}\` und trag sie ins Board ein (verschobene Zeile = neuer Termin).`,
+    [ASK_KIND.sourceEntry]: (title, source) =>
+      `Sieh dir die Meldung \`${title}\` der Quelle \`${source}\` an und stell mir, falls nötig, die Frage dazu (jh waiting).`,
+  },
+  [PLAN_LANGUAGE.en]: {
+    [ASK_KIND.question]: (id) => `Ask me the open question ${id} now (jh waiting).`,
+    [ASK_KIND.boardRow]: (key) => `Ask me the open board row \`${key}\` now (jh waiting).`,
+    [ASK_KIND.appointmentRun]: (key) => `Run the appointment \`${key}\` now, under the approvals it needs.`,
+    [ASK_KIND.appointmentMove]: (key) =>
+      `Ask the user in a dialog for the new time of the appointment \`${key}\` and write it into the board (a moved row is a new appointment).`,
+    [ASK_KIND.sourceEntry]: (title, source) =>
+      `Look at the report \`${title}\` of the source \`${source}\` and, if it needs it, put the question about it to me (jh waiting).`,
+  },
+}
+
+/** What the sentence names: the id of a question, else the sanitised key of the row (`boardRowKey`). */
+const subjectKeyOf = (target: AskTarget): string => {
+  if (target.kind === ASK_KIND.question) return target.id
+  if (target.kind === ASK_KIND.sourceEntry) return boardRowKey('', target.title)
+  return target.kind === ASK_KIND.boardRow
+    ? boardRowKey(target.since, target.item)
+    : boardRowKey(target.when, target.action)
+}
+
+/** The source of an entry, sanitised like the key; `''` for every other target. */
+const scopeOf = (target: AskTarget): string =>
+  target.kind === ASK_KIND.sourceEntry ? boardRowKey('', target.source) : ''
+
+/**
+ * The line sent to the coordinator: a fixed sentence that carries the id of a question, or the sanitised key of a
+ * 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 =>
+  ASK_LINES[language][target.kind](subjectKeyOf(target), scopeOf(target))
+
+const isAskable = (target: AskTarget): boolean =>
+  target.kind === ASK_KIND.question
+    ? isQuestionId(target.id)
+    : subjectKeyOf(target) !== '' && (target.kind !== ASK_KIND.sourceEntry || scopeOf(target) !== '')
+
+const SUBJECT_NAMES: Record<AskTarget['kind'], string> = {
+  [ASK_KIND.question]: 'question',
+  [ASK_KIND.boardRow]: 'board row',
+  [ASK_KIND.appointmentRun]: 'appointment',
+  [ASK_KIND.appointmentMove]: 'appointment',
+  [ASK_KIND.sourceEntry]: 'report',
+}
+
+const subjectOf = (target: AskTarget): string => {
+  const scope = scopeOf(target)
+  return `${SUBJECT_NAMES[target.kind]} ${subjectKeyOf(target)}${scope === '' ? '' : ` of ${scope}`}`
+}
+
+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,36 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+
+/**
+ * What the coordinator can be asked: to put an open dialog question or an open board row to the user, to run an
+ * appointment now, or to ask the user for a new time for it.
+ */
+export const ASK_KIND = {
+  question: 'question',
+  boardRow: 'boardRow',
+  appointmentRun: 'appointmentRun',
+  appointmentMove: 'appointmentMove',
+  sourceEntry: 'sourceEntry',
+} as const
+
+export type AskTarget =
+  | { kind: typeof ASK_KIND.question; id: string }
+  | { kind: typeof ASK_KIND.boardRow; since: string; item: string }
+  | { kind: typeof ASK_KIND.appointmentRun | typeof ASK_KIND.appointmentMove; when: string; action: string }
+  | { kind: typeof ASK_KIND.sourceEntry; source: string; title: 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)
+}