jackherd 1.14.0 → 1.15.0

package/src/lane-prompt/command.ts

@@ -46,7 +46,12 @@ const promptSourcesOf = (options: LanePromptOptions, cwd: string): PromptSources
   if (board.notice) console.error(board.notice)
   const directory = dirname(boardRepoPathOf(root, settings, board.file))
   return {
-    request: { lane: options.lane, handover: options.handover, language: settings.planLanguage },
+    request: {
+      lane: options.lane,
+      handover: options.handover,
+      language: settings.planLanguage,
+      skillPrefix: settings.skillPrefix,
+    },
     board: { text: readFileSync(board.file, 'utf8'), directory, path: relative(cwd, board.file) },
     readPlan: readFirstIn([root, checkout]),
     readLanePlan: readFirstIn([worktreeOf(root, settings, options.lane)]),

package/src/lane-prompt/input.ts

@@ -5,8 +5,8 @@ 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 lane to prompt, the hand-over file of a restart (null for a fresh start), the plan language and the project's `skillPrefix`. */
+export type LanePromptRequest = { lane: string; handover: string | null; language: PlanLanguage; skillPrefix: string }
 
 /**
  * The board's text, its directory from the repository root, which its plan links are relative to, and the path a
@@ -146,12 +146,12 @@ export const lanePromptInputOf = (
   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
+  const { lane, handover, language, skillPrefix } = request
   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 }
+  const input = { language, lane, plans, port: sprintLane.port, handover, skillPrefix }
   return notices.length === 0 ? { kind: 'prompt', input } : { kind: 'prompt', input, notices }
 }

package/src/lane-prompt/texts.ts

@@ -1,3 +1,4 @@
+import { CLI_NAME } from '../version/release'
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
 
 /**
@@ -12,11 +13,12 @@ export type LanePromptTexts = {
   wholeRepository: string
   editInside: string
   writeTools: string
-  port: (port: number) => string
+  port: (port: number, implementSkill: string) => string
   noPort: string
   blocking: string
   mustNot: string
   commit: string
+  taskSignals: string
   report: (reportPath: string) => string
   textBlock: string
   secret: string
@@ -24,7 +26,7 @@ export type LanePromptTexts = {
   approvalGate: string
   helper: (helperName: string) => string
   helperPurpose: string
-  start: string
+  start: (implementSkill: string) => string
   restart: (handoverPath: string) => string
 }
 
@@ -38,15 +40,17 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
       '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.`,
+    port: (port, implementSkill) =>
+      `Port ${port}: the coordinator runs your dev server in its own pane; look at your visible changes there (\`${implementSkill}\` 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.',
+    commit:
+      'Ask before every commit (`/pre-commit` is the way where it is installed); git (commit, push, PR, merge) goes only through the coordinator and only with approval.',
+    taskSignals: `Whatever skill builds a task, report it: \`${CLI_NAME} task start "<task>"\` before and \`${CLI_NAME} task done\` after every task. The herd shows the running task from that signal, and the watcher sees a standstill by it.`,
     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:
@@ -60,7 +64,8 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
     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.',
+    start: (implementSkill) =>
+      `Start: build your phases in the order above, with \`${implementSkill}\` or a skill of your choice; the rules above hold for every one.`,
     restart: (handoverPath) => `Start: read \`${handoverPath}\` first and continue with the next step it names.`,
   },
   [PLAN_LANGUAGE.de]: {
@@ -72,15 +77,17 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
       '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.`,
+    port: (port, implementSkill) =>
+      `Port ${port}: Der Koordinator betreibt deinen Dev-Server in seinem eigenen Pane; deine sichtbaren Änderungen siehst du dort an (\`${implementSkill}\` 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.',
+    commit:
+      'Vor jedem Commit fragst du (`/pre-commit` ist der Weg, wo es installiert ist); Git (Commit, Push, PR, Merge) läuft nur über den Koordinator und nur mit Freigabe.',
+    taskSignals: `Gleich mit welchem Skill eine Aufgabe gebaut wird, meldest du sie: \`${CLI_NAME} task start "<aufgabe>"\` vor und \`${CLI_NAME} task done\` nach jeder Aufgabe. Die Herde zeigt die laufende Aufgabe an diesem Signal, und der Watcher erkennt daran einen Stillstand.`,
     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:
@@ -94,7 +101,8 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
     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.',
+    start: (implementSkill) =>
+      `Start: Baue deine Phasen in der Reihenfolge oben, mit \`${implementSkill}\` oder einem Skill deiner Wahl; die Regeln oben gelten für jeden.`,
     restart: (handoverPath) =>
       `Start: Lies zuerst \`${handoverPath}\` und mach mit dem nächsten Schritt weiter, den sie nennt.`,
   },

package/src/plan-contract/command.ts

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+import { findProjectRoot } from '../config/location'
+import { readConfig } from '../config/read-config'
+import { asksForHelp } from '../preview/options'
+import { CLI_NAME } from '../version/release'
+import type { PlanLanguage } from '../vocabulary'
+import { contractOf, type PartFinding, type PlanContract } from './contract'
+
+const CHECK_SUBCOMMAND = 'check'
+
+/** Exit codes of `jh plan check`: the contract is met, a part has a gap, the command line or the file is wrong. */
+export const PLAN_CHECK_EXIT = { met: 0, gaps: 1, error: 2 } as const
+
+export const USAGE = `usage: ${CLI_NAME} plan ${CHECK_SUBCOMMAND} <plan.md>
+
+Checks one plan against the plan contract: phases, tasks in every phase, a model for every phase, a dependency
+row for every phase (from two phases on). One line per part, \`file:line\` where a part is incomplete.
+The plan language comes from .jackherd/config.json.
+Exit 0 met, 1 with gaps, 2 for a wrong command line or an unreadable file.`
+
+const where = (file: string, line: number | null): string => (line === null ? '' : ` ${file}:${line}`)
+
+/** One line per part: `model: malformed plan.md:12 no model for P2`. */
+export const contractLines = (file: string, { parts }: PlanContract): string[] =>
+  parts.map(({ part, status, line, message }: PartFinding) => `${part}: ${status}${where(file, line)} ${message}`)
+
+type LanguageResult = { language: PlanLanguage } | { error: string }
+
+const languageOf = (home: string): LanguageResult => {
+  try {
+    const root = findProjectRoot(process.cwd(), home, existsSync) ?? process.cwd()
+    return { language: readConfig([root], home).planLanguage }
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+const readPlan = (file: string): string | null => {
+  try {
+    return readFileSync(resolve(process.cwd(), file), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const fail = (message: string): number => {
+  console.error(message)
+  return PLAN_CHECK_EXIT.error
+}
+
+export const run = (args: string[], home: string = homedir()): number => {
+  if (asksForHelp(args)) {
+    console.log(USAGE)
+    return PLAN_CHECK_EXIT.met
+  }
+  const [subcommand, file, ...rest] = args
+  if (subcommand !== CHECK_SUBCOMMAND)
+    return fail(subcommand === undefined ? USAGE : `unknown subcommand ${subcommand}\n${USAGE}`)
+  if (file === undefined || rest.length > 0) return fail(USAGE)
+  const markdown = readPlan(file)
+  if (markdown === null) return fail(`cannot read ${file}\n${USAGE}`)
+  const result = languageOf(home)
+  if ('error' in result) return fail(result.error)
+  const contract = contractOf(markdown, result.language)
+  for (const line of contractLines(file, contract)) console.log(line)
+  return contract.met ? PLAN_CHECK_EXIT.met : PLAN_CHECK_EXIT.gaps
+}

package/src/plan-contract/contract.ts

@@ -0,0 +1,144 @@
+import {
+  type ModelRow,
+  NO_DEPENDENCY_TABLE,
+  type PhaseHeading,
+  parseDependencyTable,
+  parseModelTable,
+  parsePlanPhases,
+  phaseCount,
+  phaseHeadings,
+  phaseLabels,
+} from '../plan-format'
+import type { PlanLanguage } from '../vocabulary'
+
+/** The four parts of the plan contract. */
+export const CONTRACT_PART = {
+  phases: 'phases',
+  tasks: 'tasks',
+  model: 'model',
+  dependencies: 'dependencies',
+} as const
+
+export type ContractPart = (typeof CONTRACT_PART)[keyof typeof CONTRACT_PART]
+
+/** What the plan holds of a part: all of it, none of it, or something the readers cannot use. */
+export const PART_STATUS = { present: 'present', missing: 'missing', malformed: 'malformed' } as const
+
+export type PartStatus = (typeof PART_STATUS)[keyof typeof PART_STATUS]
+
+/** `line` is the 1-based line of the first problem, or of the part's first sign; null when the plan shows none. */
+export type PartFinding = { part: ContractPart; status: PartStatus; line: number | null; message: string }
+
+/** `met` is false when a part is malformed, or phases, tasks or the model table are missing; a missing dependency table is a note. */
+export type PlanContract = { parts: PartFinding[]; met: boolean }
+
+/** Fewer phases than this need no dependency table: there is nothing to put side by side. */
+const PHASES_NEEDING_DEPENDENCIES = 2
+
+const SUB_PHASE_SUFFIX = /[a-z]$/
+const NO_MODEL_MARK = /^[—–-]/
+
+/** The phase a sub-phase belongs to (`3b` is `3`); a phase without a letter is its own base. */
+const baseOf = (id: string): string => id.replace(SUB_PHASE_SUFFIX, '')
+
+const finding = (part: ContractPart, status: PartStatus, line: number | null, message: string): PartFinding => ({
+  part,
+  status,
+  line,
+  message,
+})
+
+const uniqueHeadings = (headings: readonly PhaseHeading[]): PhaseHeading[] =>
+  headings.filter(({ id }, index) => headings.findIndex((other) => other.id === id) === index)
+
+const phasesPart = (headings: readonly PhaseHeading[]): PartFinding =>
+  headings.length === 0
+    ? finding(CONTRACT_PART.phases, PART_STATUS.missing, null, 'no phase heading')
+    : finding(CONTRACT_PART.phases, PART_STATUS.present, headings[0].line, phaseCount(headings.length))
+
+/** Present when no phase lacks the part (`ok`), else malformed at the first phase that does, naming them all. */
+const coverage = (
+  part: ContractPart,
+  without: readonly PhaseHeading[],
+  ok: { line: number | null; message: string },
+  problem: string,
+): PartFinding =>
+  without.length === 0
+    ? finding(part, PART_STATUS.present, ok.line, ok.message)
+    : finding(
+        part,
+        PART_STATUS.malformed,
+        without[0].line,
+        `${problem} ${phaseLabels(
+          without.map(({ id }) => id),
+          ', ',
+        )}`,
+      )
+
+const tasksPart = (markdown: string, language: PlanLanguage, headings: readonly PhaseHeading[]): PartFinding => {
+  if (headings.length === 0) return finding(CONTRACT_PART.tasks, PART_STATUS.missing, null, 'no phase to hold tasks')
+  const empty = new Set(
+    parsePlanPhases(markdown, language)
+      .filter(({ items }) => items.length === 0)
+      .map(({ id }) => id),
+  )
+  const without = headings.filter(({ id }) => empty.has(id))
+  return coverage(
+    CONTRACT_PART.tasks,
+    without,
+    { line: headings[0].line, message: 'every phase has tasks' },
+    'no checkbox in',
+  )
+}
+
+/** A row names a model, or marks the phase as one that needs none (`—`, a phase only a person does). */
+const isDecided = ({ models, cell }: ModelRow): boolean => models.length > 0 || NO_MODEL_MARK.test(cell)
+
+/** A phase is covered by a listed id of its own or of its base phase. */
+const lacks = (headings: readonly PhaseHeading[], listed: ReadonlySet<string>): PhaseHeading[] =>
+  headings.filter(({ id }) => !listed.has(id) && !listed.has(baseOf(id)))
+
+const modelPart = (markdown: string, language: PlanLanguage, headings: readonly PhaseHeading[]): PartFinding => {
+  const rows = parseModelTable(markdown, language)
+  if (rows === null) return finding(CONTRACT_PART.model, PART_STATUS.missing, null, 'no model table')
+  const modelled = new Set(rows.filter(isDecided).map(({ id }) => id))
+  return coverage(
+    CONTRACT_PART.model,
+    lacks(headings, modelled),
+    { line: rows[0]?.line ?? null, message: 'every phase has a model' },
+    'no model for',
+  )
+}
+
+const dependenciesPart = (markdown: string, language: PlanLanguage, headings: readonly PhaseHeading[]): PartFinding => {
+  if (headings.length < PHASES_NEEDING_DEPENDENCIES)
+    return finding(CONTRACT_PART.dependencies, PART_STATUS.present, null, 'not needed with fewer than two phases')
+  const table = parseDependencyTable(markdown, language)
+  if (table === null) return finding(CONTRACT_PART.dependencies, PART_STATUS.missing, null, NO_DEPENDENCY_TABLE)
+  return coverage(
+    CONTRACT_PART.dependencies,
+    lacks(headings, new Set(table.map(({ id }) => id))),
+    { line: null, message: 'every phase has a row' },
+    'no row for',
+  )
+}
+
+/** A missing dependency table is a note, not a gap: the phases then run one after another. */
+export const isGap = ({ part, status }: PartFinding): boolean =>
+  status === PART_STATUS.malformed || (status === PART_STATUS.missing && part !== CONTRACT_PART.dependencies)
+
+/**
+ * What a plan holds of the contract the herd, the watcher, `jh check` and a lane start read: phase headings,
+ * checkboxes in every phase, a recognised model for every phase, and (from two phases on) a dependency row for every
+ * phase. Built on the parsers those readers use, so a part is present exactly when they find it.
+ */
+export const contractOf = (markdown: string, language: PlanLanguage): PlanContract => {
+  const headings = uniqueHeadings(phaseHeadings(markdown, language))
+  const parts = [
+    phasesPart(headings),
+    tasksPart(markdown, language, headings),
+    modelPart(markdown, language, headings),
+    dependenciesPart(markdown, language, headings),
+  ]
+  return { parts, met: !parts.some(isGap) }
+}

package/src/plan-format/dependencies.ts

@@ -1,5 +1,5 @@
 import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { PHASE_ID_PREFIX, phaseLabels, spannedPhaseIds } from './lanes'
+import { PHASE_ID_PREFIX, phaseIdOf, phaseLabels, spannedPhaseIds } from './lanes'
 import { escapeRegExp, firstTableWithHeader, subsectionLines } from './markdown'
 import { type PhaseHeading, parsePlanPhases, phaseHeadings } from './phases'
 import { isPhaseFinished } from './progress'
@@ -30,7 +30,6 @@ export type PhaseWithoutRow = PhaseHeading
 type Candidate = { id: string; writes: string[]; serialMarkers: string[]; releases: string[] }
 
 const ID = '(\\d+[a-z]?)'
-const PHASE_ID = new RegExp(`^\\s*${PHASE_ID_PREFIX}?${ID}\\b`, 'i')
 const PHASE_RANGE = new RegExp(`^${PHASE_ID_PREFIX}?(\\d+)\\s*[–-]\\s*${PHASE_ID_PREFIX}?(\\d+)$`, 'i')
 const BACKTICKED = /`([^`]+)`/g
 const NO_VALUE = /^[—–-]?$/
@@ -41,8 +40,6 @@ const PACKAGE_SCOPE = /^@[^/]+\//
 /** The files a release of the package in their directory changes: the changelog and the version in the manifest. */
 const RELEASE_FILE = /(?:^|\/)(?:CHANGELOG\.md|package\.json)$/
 
-const phaseIdOf = (cell: string): string | null => PHASE_ID.exec(cell)?.[1]?.toLowerCase() ?? null
-
 const splitOutsideParentheses = (cell: string, separator: string): string[] => {
   const entries: string[] = []
   let depth = 0

package/src/plan-format/index.ts

@@ -18,9 +18,12 @@ export * from './drift'
 export * from './header'
 export {
   laneNameOf,
+  NO_DEPENDENCY_TABLE,
   PHASE_ID_PREFIX,
   type PlanStep,
   parseSprintLanes,
+  phaseCount,
+  phaseIdOf,
   phaseIdsOfCell,
   phaseLabel,
   phaseLabels,
@@ -30,6 +33,7 @@ export {
   withoutRepeats,
 } from './lanes'
 export * from './model-column'
+export * from './model-table'
 export * from './phase-tally'
 export * from './phases'
 export * from './plan-structure'

package/src/plan-format/lanes.ts

@@ -29,6 +29,17 @@ const PLAN_LINK = /\[([^\]]+)\]\(([^)]+)\)/
 /** Sprint tables name a phase `P4`; the sidebar title prints it the same way. */
 export const PHASE_ID_PREFIX = 'P'
 
+const LEADING_PHASE_ID = new RegExp(`^\\s*${PHASE_ID_PREFIX}?(\\d+[a-z]?)\\b`, 'i')
+
+/** The phase a table's first cell names (`1 — Title`, `P1`, `10c`), lower-cased; null when it names none. */
+export const phaseIdOf = (cell: string): string | null => LEADING_PHASE_ID.exec(cell)?.[1]?.toLowerCase() ?? null
+
+/** What a report says when the plan has no dependency table. */
+export const NO_DEPENDENCY_TABLE = 'no dependency table: phases run one after another'
+
+/** `1 phase`, `3 phases`. */
+export const phaseCount = (count: number): string => `${count} ${count === 1 ? 'phase' : 'phases'}`
+
 /** A phase as plans and reports name it: `P4`. */
 export const phaseLabel = (id: string): string => `${PHASE_ID_PREFIX}${id}`
 

package/src/plan-format/markdown.ts

@@ -56,13 +56,14 @@ export const firstHeading = (markdown: string, fallback: string): string =>
 
 const HEADING = /^(#{2,4})\s+(.*?)\s*$/
 
-/**
- * The lines under the first level 2 to 4 heading whose text starts with `headingText` (a suffix such as
- * `(PFLICHT ab 3 Phasen)` is allowed), up to the next heading of the same or a higher level.
- */
+/** The 0-based line index of the first level 2 to 4 heading whose text starts with `headingText` (a suffix such as `(PFLICHT ab 3 Phasen)` is allowed); -1 when there is none. */
+export const subsectionStart = (markdown: string, headingText: string): number =>
+  markdown.split('\n').findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText))
+
+/** The lines under that heading (see `subsectionStart`), up to the next heading of the same or a higher level. */
 export const subsectionLines = (markdown: string, headingText: string): string[] => {
   const lines = markdown.split('\n')
-  const start = lines.findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText))
+  const start = subsectionStart(markdown, headingText)
   if (start === -1) return []
   const level = HEADING.exec(lines[start])?.[1].length ?? 2
   const rest = lines.slice(start + 1)

package/src/plan-format/model-table.ts

@@ -0,0 +1,27 @@
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { phaseIdOf } from './lanes'
+import { firstTableRows, subsectionLines, subsectionStart } from './markdown'
+import { type ColumnModel, columnModels } from './model-column'
+
+/**
+ * A row of the model table: the phase it names, the models its model cell names (none for a dash), the model cell as
+ * written, and the row's 1-based line.
+ */
+export type ModelRow = { id: string; models: ColumnModel[]; cell: string; line: number }
+
+/**
+ * The rows of the plan's model table (`### Model-Empfehlungen pro Phase`): the phase from the first cell (`1 — Title`,
+ * `P1`, `10c`), the models from the second, read like a board's model column. A row whose first cell names no phase is
+ * skipped; null when the plan has no such section or the section holds no table.
+ */
+export const parseModelTable = (markdown: string, language: PlanLanguage): ModelRow[] | null => {
+  const heading = PLAN_VOCABULARY[language].sections.modelRecommendations
+  const rows = firstTableRows(subsectionLines(markdown, heading))
+  if (rows.length === 0) return null
+  const firstBodyLine = subsectionStart(markdown, heading) + 2
+  return rows.flatMap(({ index, cells }) => {
+    const id = phaseIdOf(cells[0] ?? '')
+    const cell = cells[1] ?? ''
+    return id === null ? [] : [{ id, models: columnModels(cell), cell, line: firstBodyLine + index }]
+  })
+}

package/src/plans/activity-read.ts

@@ -0,0 +1,98 @@
+import { CONTENT_BLOCK_TYPE, LOG_ENTRY_TYPE } from '../context/log-vocabulary'
+import { keptLogEntry } from '../context/session-log'
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+import { isRecord } from '../shared/is-record'
+import { type RunningSubagent, type SubagentActivity, type SubagentLog, subagentLabelOf } from './subagents'
+import { laneDirectoryOf } from './unlisted-lanes'
+
+/** What a running subagent did last, with the name the herd calls it by. */
+export type SubagentLine = { label: string; description: string | null; line: string }
+
+/** What a worktree shows of its subagents, and the last action of each. */
+export type LaneSubagents = SubagentActivity & { lines?: readonly SubagentLine[] }
+
+/** The end of a log that is looked at: the last action is among the last entries, however long the log is. */
+const SCANNED_ENTRIES = 60
+const LINE_LENGTH = 200
+const PATH_SEGMENTS = 2
+/** The input fields that name what a tool works on, the first one present wins. */
+const TARGET_FIELDS = ['file_path', 'command', 'pattern', 'url', 'query', 'description', 'path']
+
+const singleLine = (text: string): string => terminalSafe(text).replace(/\s+/g, ' ').trim()
+
+const shortPath = (path: string): string =>
+  path.includes('/') ? path.split('/').slice(-PATH_SEGMENTS).join('/') : path
+
+const targetOf = (input: unknown): string => {
+  if (!isRecord(input)) return ''
+  const field = TARGET_FIELDS.find((name) => typeof input[name] === 'string' && input[name] !== '')
+  if (field === undefined) return ''
+  const value = String(input[field]).split('\n')[0]
+  return singleLine(field === 'file_path' || field === 'path' ? shortPath(value) : value)
+}
+
+/** The line of one content block, null for a block that is no action: reasoning, whether it carries text or not. */
+const lineOfBlock = (block: unknown): string | null => {
+  if (!isRecord(block)) return null
+  if (block.type === CONTENT_BLOCK_TYPE.toolUse && typeof block.name === 'string')
+    return singleLine(`${block.name} ${targetOf(block.input)}`)
+  if (block.type !== CONTENT_BLOCK_TYPE.text || typeof block.text !== 'string') return null
+  const first = block.text.split('\n').find((line) => line.trim() !== '')
+  return first === undefined ? null : singleLine(first)
+}
+
+const lineOfEntry = (line: string): string | null => {
+  const entry = keptLogEntry(line)
+  if (entry?.type !== LOG_ENTRY_TYPE.assistant || !isRecord(entry.message) || !Array.isArray(entry.message.content))
+    return null
+  const blocks: unknown[] = entry.message.content
+  for (let index = blocks.length - 1; index >= 0; index--) {
+    const found = lineOfBlock(blocks[index])
+    if (found) return found
+  }
+  return null
+}
+
+const scanned = new WeakMap<readonly string[], string | null>()
+
+/**
+ * The last action in a log's lines: the newest assistant text line or tool call, a tool as its name and its short
+ * target (`Read plans/layout.ts`). Reasoning is left out, as most of it is empty in the log. Cut to a length a line of
+ * the herd can take; null when the end of the log holds none. A log that did not change (`followTailLines` hands back
+ * the very same array) is not scanned again.
+ */
+export const activityLineOf = (lines: readonly string[]): string | null => {
+  if (scanned.has(lines)) return scanned.get(lines) ?? null
+  let found: string | null = null
+  for (let index = lines.length - 1; index >= Math.max(lines.length - SCANNED_ENTRIES, 0) && found === null; index--)
+    found = lineOfEntry(lines[index])
+  const line = found === null ? null : ellipsize(found, LINE_LENGTH)
+  scanned.set(lines, line)
+  return line
+}
+
+const labelOfLog = ({ id, meta }: SubagentLog): string | null =>
+  subagentLabelOf(id, isRecord(meta) && typeof meta.agentType === 'string' ? meta.agentType : null)
+
+/**
+ * `lanes` with the last action of each running subagent added to the lane it works in; a subagent whose log holds no
+ * action, or that works in no known lane, adds none. `lanes` itself stays as it was.
+ */
+export const withSubagentLines = (
+  lanes: ReadonlyMap<string, SubagentActivity>,
+  running: readonly RunningSubagent[],
+  logs: readonly SubagentLog[],
+  worktreeDirectory: string,
+): Map<string, LaneSubagents> => {
+  const result = new Map<string, LaneSubagents>(lanes)
+  const tails = new Map(logs.flatMap((log) => [[labelOfLog(log), log.tail] as const]))
+  for (const { label, cwd, description } of running) {
+    const lane = cwd === null ? null : laneDirectoryOf(cwd, worktreeDirectory)
+    const tail = tails.get(label)
+    const known = lane === null ? undefined : result.get(lane)
+    const line = tail === undefined ? null : activityLineOf(tail)
+    if (lane === null || known === undefined || line === null) continue
+    result.set(lane, { ...known, lines: [...(known.lines ?? []), { label, description, line }] })
+  }
+  return result
+}

package/src/plans/ask-coordinator.ts

@@ -1,20 +1,23 @@
 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 { laneSenderForAsync } from '../settled/send'
+import { type HerdrAsyncRunner, 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'
 
+/** The footer line while the coordinator is being asked. */
+export const ASKING_NOTICE = 'asking the coordinator …'
+
 /** 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
+  run: HerdrAsyncRunner
 }
 
 /** A sentence takes the subject's key and, for an entry of a source, the source it belongs to (else `''`). */
@@ -80,13 +83,18 @@ const subjectOf = (target: AskTarget): string => {
   return `${SUBJECT_NAMES[target.kind]} ${subjectKeyOf(target)}${scope === '' ? '' : ` of ${scope}`}`
 }
 
-const agentNamesOf = (run: HerdrRunner): string[] => parseAgentList(run(['agent', 'list'])).map(({ name }) => name)
+const agentNamesOf = async (run: HerdrAsyncRunner): Promise<string[]> =>
+  parseAgentList(await 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 } => {
+const coordinatorOf = async ({
+  adapter,
+  repository,
+  run,
+}: AskDependencies): Promise<{ name: string } | { reason: string }> => {
   if (adapter === TERMINAL_ADAPTER.none) return { name: resolveCoordinatorName(repository, []) }
   try {
-    const names = agentNamesOf(run)
+    const names = await agentNamesOf(run)
     const name = resolveCoordinatorName(repository, names)
     return names.includes(name) ? { name } : { reason: `no agent named ${name}` }
   } catch (error) {
@@ -96,14 +104,15 @@ const coordinatorOf = ({ adapter, repository, run }: AskDependencies): { name: s
 
 /**
  * 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.
+ * coordinator that is working gets the line too: herdr queues it like a message in the middle of a turn. Resolves to
+ * the footer line, who was asked or why nobody was; the prompt waits up to `PROMPT_CONFIRM_TIMEOUT_MS`, so a live
+ * view shows `ASKING_NOTICE` meanwhile.
  */
-export const askCoordinator = (target: AskTarget, dependencies: AskDependencies): string => {
+export const askCoordinator = async (target: AskTarget, dependencies: AskDependencies): Promise<string> => {
   if (!isAskable(target)) return TEXTS.notAsked('nothing to ask')
-  const coordinator = coordinatorOf(dependencies)
+  const coordinator = await coordinatorOf(dependencies)
   if ('reason' in coordinator) return TEXTS.notAsked(coordinator.reason)
-  const failure = laneSenderFor(dependencies.adapter, dependencies.run)(
+  const failure = await laneSenderForAsync(dependencies.adapter, dependencies.run)(
     coordinator.name,
     askLine(target, dependencies.language),
   )