jackherd 1.10.0 → 1.11.0

package/src/config/schema.ts

@@ -10,6 +10,7 @@ import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
 import { hasNestedQuantifier } from './nested-quantifier'
 import { isRepositoryDirectory } from './repository-directory'
+import { DEFAULT_TONES, TONE_NAMES } from './tones'
 
 export const TERMINAL_ADAPTER = { none: 'none', herdr: 'herdr' } as const
 
@@ -176,7 +177,7 @@ const sourcePath = z.string().refine(isSourcePath, 'not a source path: `.`, or `
 
 const SOURCE_FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]*$/
 
-/** The seven known fields, and any further field (`priority`, `assignee`, …) whose name is a plain name, for `reportOn`. */
+/** The eight known fields, and any further field (`priority`, `assignee`, …) whose name is a plain name, for `reportOn`. */
 const sourceMapSchema = z
   .object({
     [SOURCE_FIELD.id]: sourcePath,
@@ -193,6 +194,8 @@ const sourceMapSchema = z
     [SOURCE_FIELD.author]: sourcePath.optional(),
     /** A ticket source's status, shown on its badge in the herd; also a field `reportOn` can name. */
     [SOURCE_FIELD.status]: sourcePath.optional(),
+    /** How often the entry happened (an error count), shown as `113×` beside the entry in the herd's `Sources` block. */
+    [SOURCE_FIELD.count]: sourcePath.optional(),
   })
   .catchall(sourcePath)
   .refine((map) => Object.keys(map).every((field) => SOURCE_FIELD_NAME.test(field)), {
@@ -203,6 +206,8 @@ const sourceMapSchema = z
 const canChange = ({ map, reportOn }: { map: Record<string, string | undefined>; reportOn?: string[] }): boolean =>
   map.updatedAt !== undefined || CONTENT_FIELDS.some((field) => map[field] !== undefined) || reportOn !== undefined
 
+const toneName = z.enum(TONE_NAMES)
+
 const sourceSchema = z
   .strictObject({
     /** Printed in every report of the source and the key of its saved state. */
@@ -218,6 +223,13 @@ const sourceSchema = z
     ignoreAuthors: z.array(z.string().min(1)).default([]),
     /** The most new or changed entries one report shows of this source; the rest is one line `+<n> more`. */
     reportLimit: z.number().int().min(1).default(5),
+    /** Shown before a row of "Waiting for you" that came from this source (`Error log · Checkout: …`); without it the source's name. */
+    label: z
+      .string()
+      .min(1)
+      .max(40)
+      .regex(/^[^\r\n]+$/, 'one line')
+      .optional(),
     /** The lane the source's reports name. */
     lane: z.string().min(1).optional(),
     /**
@@ -225,6 +237,8 @@ const sourceSchema = z
      * the lane above or the lane whose board row or plan names its id.
      */
     ticket: z.boolean().optional(),
+    /** The tone of the source's mark in the herd's `Sources` block while its newest report is new; without it the tone of the role `new`. */
+    tone: toneName.optional(),
     /**
      * The mapped fields whose change reports, with the old and the new value, in place of the content of `title`,
      * `author`, `body` and `url`; without it a change of that content reports.
@@ -383,6 +397,13 @@ const hintsSchema = z.strictObject({
 /** Minutes a lane works without a task signal before the watcher reports `no task signal`. */
 const DEFAULT_TASK_SIGNAL_MINUTES = 10
 
+const tonesSchema = z.strictObject({
+  waiting: toneName.default(DEFAULT_TONES.waiting),
+  new: toneName.default(DEFAULT_TONES.new),
+  running: toneName.default(DEFAULT_TONES.running),
+  resting: toneName.default(DEFAULT_TONES.resting),
+})
+
 const contextSchema = z
   .strictObject({
     /** Tokens in a lane's context from which its fill shows yellow and `/implement` offers a new chat. */
@@ -475,6 +496,8 @@ export const jackherdConfigSchema = z.strictObject({
         )
         .default(DEFAULT_LINK_KINDS.map((kind) => ({ ...kind }))),
       context: contextSchema.prefault({}),
+      /** The colour of each role in the herd, by name: what waits for you, what is new, what runs, what rests. */
+      tones: tonesSchema.prefault({}),
     })
     .prefault({}),
   /**

package/src/config/tones.ts

@@ -0,0 +1,27 @@
+/** The colours the herd paints with by name; the terminal's own palette decides how each looks, `grey` is the dimmed text colour. */
+export const TONE = {
+  amber: 'amber',
+  teal: 'teal',
+  grey: 'grey',
+  red: 'red',
+  green: 'green',
+  blue: 'blue',
+  magenta: 'magenta',
+} as const
+
+export type ToneName = (typeof TONE)[keyof typeof TONE]
+
+export const TONE_NAMES = Object.values(TONE)
+
+/** What a tone is for in the herd: what waits for you, what is new, what runs, what rests. */
+export const TONE_ROLE = { waiting: 'waiting', new: 'new', running: 'running', resting: 'resting' } as const
+
+export type ToneRole = (typeof TONE_ROLE)[keyof typeof TONE_ROLE]
+
+/** The tone of each role, as the herd looked before the tones were configurable. */
+export const DEFAULT_TONES: Record<ToneRole, ToneName> = {
+  [TONE_ROLE.waiting]: TONE.amber,
+  [TONE_ROLE.new]: TONE.amber,
+  [TONE_ROLE.running]: TONE.teal,
+  [TONE_ROLE.resting]: TONE.grey,
+}

package/src/lane-prompt/additions.ts

@@ -0,0 +1,14 @@
+/** The line that ends a written lane prompt; what the coordinator adds below it survives every new writing. */
+export const ADDITIONS_MARKER = '<!-- jackherd: additions below this line stay when the prompt is written again -->'
+
+/** What follows the marker line of a written prompt; empty for no file, no marker line or nothing below it. */
+export const additionsOf = (existing: string | null): string => {
+  if (existing === null) return ''
+  const lines = existing.split('\n')
+  const marker = lines.indexOf(ADDITIONS_MARKER)
+  return marker === -1 ? '' : lines.slice(marker + 1).join('\n')
+}
+
+/** `prompt` closed by the marker and by the additions of the file it replaces, so writing twice changes nothing. */
+export const withAdditions = (prompt: string, existing: string | null): string =>
+  `${prompt}\n${ADDITIONS_MARKER}\n${additionsOf(existing)}`

package/src/lane-prompt/command.ts

@@ -5,6 +5,7 @@ import { boardFor } from '../plans/board-pick'
 import { mainCheckout, worktreeRoot } from '../plans/git'
 import { boardRepoPathOf, readSettings, worktreeOf } from '../plans/settings'
 import { asksForHelp } from '../preview/options'
+import { withAdditions } from './additions'
 import { buildLanePrompt } from './build'
 import { type BoardSource, type LanePromptRequest, lanePromptInputOf, type ReadPlan } from './input'
 import { LANE_PROMPT_USAGE, type LanePromptOptions, parseLanePromptOptions } from './options'
@@ -53,15 +54,19 @@ const promptSourcesOf = (options: LanePromptOptions, cwd: string): PromptSources
   }
 }
 
+/** Writes `prompt` to `out`, closed by the marker and by the additions the file there already carries below it. */
 const writePrompt = (out: string, prompt: string): void => {
+  const existing = existsSync(out) ? readFileSync(out, 'utf8') : null
   mkdirSync(dirname(out), { recursive: true })
-  writeFileSync(out, prompt)
+  writeFileSync(out, withAdditions(prompt, existing))
 }
 
 /**
  * `jh lane prompt <lane> [--board <board.md>] [--out <file>] [--handover <file>]`: writes the lane's prompt, built
  * from its board row and its plan in the plan language, and prints the file's path, so the coordinator sends it with
- * `herdr agent prompt <lane> "$(cat <file>)"`. `--help` prints the usage. Exit 0 written, 1 refused or failed.
+ * `herdr agent prompt <lane> "$(cat <file>)"`. Below the marker line at the file's end the coordinator adds what the
+ * plan does not say; it stays through every new writing. A phase two open rows name is in no prompt and is reported on
+ * stderr. `--help` prints the usage. Exit 0 written, 1 refused or failed.
  */
 export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
   if (asksForHelp(args)) {
@@ -76,6 +81,7 @@ export const run = async (args: string[], cwd: string = process.cwd()): Promise<
       console.error(result.reason)
       return 1
     }
+    for (const notice of result.notices ?? []) console.error(notice)
     const out = options.out === null ? defaultPromptFile(root, options.lane) : resolve(cwd, options.out)
     writePrompt(out, buildLanePrompt(result.input))
     console.log(out)

package/src/lane-prompt/input.ts

@@ -17,7 +17,10 @@ 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 }
+/** `notices` is absent unless the board needs fixing: a phase two open rows name is in neither prompt. */
+export type LanePromptResult =
+  | { kind: 'prompt'; input: LanePromptInput; notices?: string[] }
+  | { kind: 'refused'; reason: string }
 
 type PlanSteps = { path: string; ids: string[] }
 
@@ -90,6 +93,37 @@ const plansOf = (
   return { plans }
 }
 
+/** The other open lanes whose rows name the phase `id` of the plan at `path`, by name. */
+const otherNamersOf = (others: readonly SprintLane[], directory: string, path: string, id: string): string[] =>
+  others
+    .filter((lane) => planStepsOf(lane, directory).some((steps) => steps.path === path && steps.ids.includes(id)))
+    .map((lane) => lane.name)
+
+const withoutContested = (
+  plans: readonly LanePlan[],
+  lane: string,
+  others: readonly SprintLane[],
+  directory: string,
+): { plans: LanePlan[]; notices: string[] } => {
+  const judged = plans.map((plan) => ({
+    plan,
+    phases: plan.phases.map((phase) => ({ phase, namers: otherNamersOf(others, directory, plan.path, phase.id) })),
+  }))
+  const kept = judged.map(({ plan, phases }) => ({
+    ...plan,
+    phases: phases.filter(({ namers }) => namers.length === 0).map(({ phase }) => phase),
+  }))
+  const notices = judged.flatMap(({ plan, phases }) =>
+    phases
+      .filter(({ namers }) => namers.length > 0)
+      .map(
+        ({ phase, namers }) =>
+          `${plan.path} ${phaseLabel(phase.id)} is named by ${[lane, ...namers].sort().join(' and ')}, so it is in neither prompt; fix the board`,
+      ),
+  )
+  return { plans: kept.filter((plan) => plan.phases.length > 0), notices }
+}
+
 /**
  * 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
@@ -103,7 +137,8 @@ export const lanePromptInputOf = (
   readPlan: ReadPlan,
   readLanePlan: ReadPlan = () => null,
 ): LanePromptResult => {
-  const sprintLane = parseSprintLanes(board.text, request.language).find((candidate) => candidate.name === request.lane)
+  const lanes = parseSprintLanes(board.text, request.language)
+  const sprintLane = lanes.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)
@@ -112,5 +147,11 @@ export const lanePromptInputOf = (
   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 } }
+  const others = lanes.filter((candidate) => candidate.name !== lane && !candidate.closed)
+  const { plans, notices } = withoutContested(found.plans, lane, others, board.directory)
+  if (plans.length === 0) {
+    return refused(`every open phase of lane ${lane} is also named by another lane: ${notices.join('; ')}`)
+  }
+  const input = { language, lane, plans, port: sprintLane.port, handover }
+  return notices.length === 0 ? { kind: 'prompt', input } : { kind: 'prompt', input, notices }
 }

package/src/lane-prompt/options.ts

@@ -13,6 +13,8 @@ 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.
+What you add below the marker line at the end of the file stays when the prompt is written again.
+A phase that two open rows of the board name is in neither prompt; the command reports it.
   --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`

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/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(/\/+$/, '')

package/src/plan-format/waiting.ts

@@ -12,6 +12,10 @@ 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
   /** Absent for a row of the board. */
@@ -30,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[] => {
@@ -40,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

@@ -1,13 +1,15 @@
-import { twoDigits } from '../plan-format/clock'
+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 { BlockItem } from './waiting-click'
+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; label: string; action: string }
+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[] }
@@ -18,11 +20,26 @@ 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,
-})
+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
@@ -32,7 +49,7 @@ export const appointmentRows = (board: string, language: PlanLanguage, now: Date
   readAppointmentTable(board, language, now)
     .appointments.filter(({ open }) => open)
     .sort((left, right) => left.when.getTime() - right.when.getTime())
-    .map(rowOf)
+    .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 => ({
@@ -41,7 +58,13 @@ export const appointmentBlock = (board: string, language: PlanLanguage, now: Dat
 
 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. */
+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) => ({
@@ -52,6 +75,7 @@ export const appointmentItems = (rows: readonly AppointmentRow[]): BlockItem[] =
     title: shortTitle(row.action),
     url: null,
     ask: null,
+    buttons: buttonsOf(row),
   }))
 }
 

package/src/plans/ask-coordinator.ts

@@ -17,34 +17,68 @@ export type AskDependencies = {
   run: HerdrRunner
 }
 
-type AskSentences = { question: (id: string) => string; boardRow: (key: string) => string }
+/** 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]: {
-    question: (id) => `Stell mir die offene Frage ${id} jetzt (jh waiting).`,
-    boardRow: (key) => `Stell mir die offene Board-Zeile \`${key}\` jetzt (jh waiting).`,
+    [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]: {
-    question: (id) => `Ask me the open question ${id} now (jh waiting).`,
-    boardRow: (key) => `Ask me the open board row \`${key}\` now (jh waiting).`,
+    [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
- * board row (`boardRowKey`), and nothing else from the board or the question, so a prompt line cannot be steered by
+ * 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))
+  ASK_LINES[language][target.kind](subjectKeyOf(target), scopeOf(target))
 
 const isAskable = (target: AskTarget): boolean =>
-  target.kind === ASK_KIND.question ? isQuestionId(target.id) : boardRowKey(target.since, target.item) !== ''
+  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 =>
-  target.kind === ASK_KIND.question ? `question ${target.id}` : `board row ${boardRowKey(target.since, target.item)}`
+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)
 

package/src/plans/ask-target.ts

@@ -1,11 +1,22 @@
 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
+/**
+ * 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