jackherd 1.23.3 → 1.25.0

package/src/plan-format/plan-structure.ts

@@ -1,7 +1,9 @@
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { LINE_KEY, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
 import { changedOpenLaneRows, type OpenLaneRow, phaseIdsOfCell } from './lanes'
-import { escapeRegExp, sectionLines } from './markdown'
+import { escapeRegExp, markedKeyOf, sectionLines } from './markdown'
 import {
+  BOLD_OPENING,
+  decidesPurpose,
   deferralTarget,
   endsPhase,
   isCheckboxLine,
@@ -11,6 +13,7 @@ import {
   type PlanPhase,
   parsePlanPhases,
   phaseHeadingPattern,
+  phasePurposeOf,
 } from './phases'
 import { terminalSafe } from './terminal-text'
 
@@ -26,10 +29,21 @@ export type PhaseWithOpenBoxes = PhaseWithoutGate & { openLines: number[] }
 /** A `PhaseWithOpenBoxes` whose tasks are all ticked on the base branch. */
 export type MergedPhaseWithOpenBoxes = PhaseWithOpenBoxes
 
-type PhaseSection = PhaseWithoutGate & { tasks: boolean; gate: boolean; openLines: number[] }
+/** A `### Phase` heading (1-based line) whose section has tasks and no purpose line directly under the heading. */
+export type PhaseWithoutPurpose = PhaseHeading
 
-const noGatePattern = (language: PlanLanguage): RegExp =>
-  new RegExp(`^\\s*\\*\\*${escapeRegExp(PLAN_VOCABULARY[language].noReviewGate)}\\b`, 'i')
+type PhaseSection = PhaseWithoutGate & { tasks: boolean; gate: boolean; purpose: boolean | null; openLines: number[] }
+
+const NO_GATE_WORDS = new RegExp(
+  `^\\s*\\*\\*(?:${Object.values(PLAN_VOCABULARY)
+    .map(({ noReviewGate }) => escapeRegExp(noReviewGate))
+    .join('|')})\\b`,
+  'i',
+)
+
+/** The line by which a phase says it has no review gate on purpose: a bold opening with the words of any known language, or with the marker. */
+const isNoGateLine = (line: string): boolean =>
+  NO_GATE_WORDS.test(line) || (BOLD_OPENING.test(line) && markedKeyOf(line) === LINE_KEY.noReviewGate)
 
 const tickCount = (phase: PlanPhase): number => phase.items.filter((item) => item.done).length
 
@@ -39,10 +53,13 @@ const tasksDone = (phase: PlanPhase): boolean => {
   return tasks.length > 0 && tasks.every((item) => item.done)
 }
 
+const settlePurpose = (section: PhaseSection, line: string, language: PlanLanguage): void => {
+  if (decidesPurpose(section.purpose !== null, line)) section.purpose = phasePurposeOf(line, language) !== null
+}
+
 /** Every `### Phase` section with whether it has tasks and whether it has a gate or says why it has none. */
 const phaseSections = (markdown: string, language: PlanLanguage): PhaseSection[] => {
   const heading = phaseHeadingPattern(language)
-  const noGate = noGatePattern(language)
   const sections: PhaseSection[] = []
   let open: PhaseSection | null = null
   for (const [index, line] of markdown.split('\n').entries()) {
@@ -54,14 +71,16 @@ const phaseSections = (markdown: string, language: PlanLanguage): PhaseSection[]
         title: terminalSafe(match[2]).trim(),
         tasks: false,
         gate: false,
+        purpose: null,
         openLines: [],
       }
       sections.push(open)
     } else if (endsPhase(line)) {
       open = null
     } else if (open) {
+      settlePurpose(open, line, language)
       open.tasks ||= isCheckboxLine(line)
-      open.gate ||= isReviewGateLine(line) || noGate.test(line)
+      open.gate ||= isReviewGateLine(line) || isNoGateLine(line)
       if (isOpenCheckboxLine(line) && deferralTarget(line, open.id) === null) open.openLines.push(index + 1)
     }
   }
@@ -87,6 +106,23 @@ export const newPhasesWithoutReviewGate = (
     .filter(({ id, tasks, gate }) => tasks && !gate && !previousIds.has(id))
     .map(({ line, id, title }) => ({ line, id, title }))
 
+/**
+ * The phases a plan gained against `previousIds` that have checkboxes and no purpose line as the first non-empty line
+ * under the heading (`phasePurposeOf`). Phases the plan already had are not read, like in `newPhasesWithoutReviewGate`.
+ */
+export const newPhasesWithoutPurpose = (
+  markdown: string,
+  language: PlanLanguage,
+  previousIds: ReadonlySet<string>,
+): PhaseWithoutPurpose[] =>
+  phaseSections(markdown, language)
+    .filter(({ id, tasks, purpose }) => tasks && !purpose && !previousIds.has(id))
+    .map(({ line, id, title }) => ({ line, id, title }))
+
+/** Every phase of the plan with tasks and without a purpose line: for a plan read whole, where no phase is older than the change. */
+export const phasesWithoutPurpose = (markdown: string, language: PlanLanguage): PhaseWithoutPurpose[] =>
+  newPhasesWithoutPurpose(markdown, language, new Set())
+
 /** Whether the document has a lanes table (`## Spuren`): a board, not a plan. */
 export const hasLanesTable = (markdown: string, language: PlanLanguage): boolean =>
   sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes).some((line) => line.startsWith('|'))

package/src/plan-format/progress.ts

@@ -8,6 +8,8 @@ import { type ChecklistItem, type DeferredItem, type PhaseWorkFields, type PlanP
 export type PhaseProgress = {
   id: string
   title: string | null
+  /** The phase's purpose sentence; absent when the plan has none or lacks the phase. */
+  purpose?: string
   done: number
   total: number
   items: ChecklistItem[]
@@ -46,6 +48,7 @@ export const phaseProgress = (phases: readonly PlanPhase[], id: string): PhasePr
     done: items.filter((item) => item.done).length,
     total: items.length,
     items,
+    ...(phase?.purpose ? { purpose: phase.purpose } : {}),
     ...(phase?.deferred ? { deferred: phase.deferred } : {}),
     ...(phase?.work ? phaseWorkFields(phase.work) : {}),
   }

package/src/plan-format/sprint-document.ts

@@ -1,5 +1,5 @@
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { allTables, firstTableWithHeader, sectionLines, subsectionLines } from './markdown'
+import { COLUMN_KEY, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { allTables, columnIndex, firstTableWithHeader, sectionLines, subsectionLines } from './markdown'
 
 const PHASE_ID_IN_CELL = /^(\d+[a-z]?)\b/
 
@@ -57,9 +57,9 @@ export const readSprintDocument = (markdown: string, language: PlanLanguage): Sp
  * first cell of a row starts with the id (`3 — Sync-Engine`); a plan without the table gives an empty map.
  */
 export const readPhaseDependencies = (planMarkdown: string, language: PlanLanguage): Record<string, string> => {
-  const { sections, columns } = PLAN_VOCABULARY[language]
+  const { sections } = PLAN_VOCABULARY[language]
   const { header, rows } = firstTableWithHeader(subsectionLines(planMarkdown, sections.dependencies))
-  const column = header.indexOf(columns.dependsOn)
+  const column = columnIndex(header, COLUMN_KEY.dependsOn, language)
   if (column === -1) return {}
   const entries = rows.flatMap((cells) => {
     const id = PHASE_ID_IN_CELL.exec(cells[0] ?? '')?.[1]

package/src/plan-format/unrecognized-sections.ts

@@ -0,0 +1,21 @@
+import { isSectionKey, sectionOfHeading } from '../vocabulary'
+import { markedKeyOf, SECTION_HEADING } from './markdown'
+
+const isRecognized = (lines: readonly string[], index: number): boolean => {
+  const text = SECTION_HEADING.exec(lines[index])?.[1] ?? ''
+  const marked = markedKeyOf(lines[index + 1] ?? '')
+  return sectionOfHeading(text) !== null || (marked !== null && isSectionKey(marked))
+}
+
+/**
+ * The 1-based line of the first `##` heading of a board or plan when it has such headings and jh reads none of them,
+ * neither by the heading of a known language nor by a marker `<!-- jh: <key> -->` directly under it: a document in a
+ * language without vocabulary and without markers, which every reader would take for empty. Null when the document has
+ * no `##` heading or reads at least one.
+ */
+export const firstUnrecognizedSectionLine = (markdown: string): number | null => {
+  const lines = markdown.split('\n')
+  const headings = lines.flatMap((line, index) => (SECTION_HEADING.test(line) ? [index] : []))
+  if (headings.length === 0 || headings.some((index) => isRecognized(lines, index))) return null
+  return headings[0] + 1
+}

package/src/plan-format/waiting.ts

@@ -1,5 +1,6 @@
-import { type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
-import { firstTableWithHeader, sectionLines } from './markdown'
+import { COLUMN_KEY, type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
+import { columnIndex, firstTableWithHeader, sectionLines } from './markdown'
+import { isOpenStatus } from './open-status'
 import { terminalSafe } from './terminal-text'
 
 /** `file` for a file or an Artifact that was sent, `question` for a dialog that ended unanswered. */
@@ -35,11 +36,9 @@ const namesOf = (cell: string): string[] =>
     .map((name) => name.replaceAll('`', '').trim())
     .filter(Boolean)
 
-/** An empty status counts as open: a row nobody closed is not dropped in silence. */
-const isOpen = (status: string, language: PlanLanguage): boolean => {
-  const lower = status.toLowerCase()
-  return lower === '' || WAITING_VOCABULARY[language].open.some((word) => lower.startsWith(word))
-}
+const OPEN_WORDS = Object.values(WAITING_VOCABULARY).flatMap(({ open }) => open)
+
+const isOpen = (status: string): boolean => isOpenStatus(status, OPEN_WORDS)
 
 /**
  * The rows of the board's waiting section in `language` (`## Wartet auf dich`, `## Waiting for you`), its columns
@@ -47,14 +46,15 @@ const isOpen = (status: string, language: PlanLanguage): boolean => {
  * column, a section without a table and a row without an item give nothing.
  */
 export const readWaitingItems = (board: string, language: PlanLanguage): WaitingItem[] => {
-  const { heading, columns, statusAlso } = WAITING_VOCABULARY[language]
+  const { heading } = WAITING_VOCABULARY[language]
   const { header, rows } = firstTableWithHeader(sectionLines(board, heading))
-  const statusName = [columns.status, ...statusAlso].find((name) => header.includes(name)) ?? columns.status
-  const positions = [columns.since, columns.item, statusName].map((name) => header.indexOf(name))
+  const positions = [COLUMN_KEY.since, COLUMN_KEY.item, COLUMN_KEY.status].map((key) =>
+    columnIndex(header, key, language),
+  )
   if (positions.includes(-1)) return []
   const [since, item, status] = positions
-  const originPosition = header.indexOf(columns.origin)
-  const unblocksPosition = header.indexOf(columns.unblocks)
+  const originPosition = columnIndex(header, COLUMN_KEY.origin, language)
+  const unblocksPosition = columnIndex(header, COLUMN_KEY.unblocks, language)
   return rows.flatMap((cells) => {
     const text = oneLine(cells[item] ?? '')
     const origin = oneLine(cells[originPosition] ?? '')
@@ -65,7 +65,7 @@ export const readWaitingItems = (board: string, language: PlanLanguage): Waiting
           {
             since: oneLine(cells[since] ?? ''),
             item: text,
-            open: isOpen(cells[status] ?? '', language),
+            open: isOpen(cells[status] ?? ''),
             ...(origin === '' ? {} : { origin }),
             ...(unblocks.length === 0 ? {} : { unblocks }),
           },

package/src/plans/board-close.ts

@@ -1,12 +1,19 @@
 import { twoDigits } from '../plan-format/clock'
-import { firstTableRows, sectionLines, sectionStart } from '../plan-format/markdown'
-import { APPOINTMENT_VOCABULARY, PLAN_LANGUAGE, type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
+import { columnIndex, firstTableRows, sectionLines, sectionStart } from '../plan-format/markdown'
+import {
+  APPOINTMENT_VOCABULARY,
+  COLUMN_KEY,
+  type ColumnKey,
+  PLAN_LANGUAGE,
+  type PlanLanguage,
+  WAITING_VOCABULARY,
+} from '../vocabulary'
 
 type SectionColumns = {
   heading: string
-  /** The header names of the two cells that identify a row, then the names that count as the status column. */
-  keys: readonly [string, string]
-  status: readonly string[]
+  /** The columns of the two cells that identify a row; the status column is found beside them. */
+  keys: readonly [ColumnKey, ColumnKey]
+  language: PlanLanguage
 }
 
 const DONE_WORD: Record<PlanLanguage, string> = { [PLAN_LANGUAGE.de]: 'erledigt', [PLAN_LANGUAGE.en]: 'done' }
@@ -17,15 +24,17 @@ export const doneStatus = (language: PlanLanguage, now: Date): string =>
 
 const squeezed = (text: string): string => text.replace(/\s+/g, ' ').trim()
 
-const waitingColumns = (language: PlanLanguage): SectionColumns => {
-  const { heading, columns, statusAlso } = WAITING_VOCABULARY[language]
-  return { heading, keys: [columns.since, columns.item], status: [columns.status, ...statusAlso] }
-}
+const waitingColumns = (language: PlanLanguage): SectionColumns => ({
+  heading: WAITING_VOCABULARY[language].heading,
+  keys: [COLUMN_KEY.since, COLUMN_KEY.item],
+  language,
+})
 
-const appointmentColumns = (language: PlanLanguage): SectionColumns => {
-  const { heading, columns, statusAlso } = APPOINTMENT_VOCABULARY[language]
-  return { heading, keys: [columns.when, columns.action], status: [columns.status, ...statusAlso] }
-}
+const appointmentColumns = (language: PlanLanguage): SectionColumns => ({
+  heading: APPOINTMENT_VOCABULARY[language].heading,
+  keys: [COLUMN_KEY.when, COLUMN_KEY.action],
+  language,
+})
 
 /** The line with the status cell (the `index`th between the bars) replaced; the other cells keep their text as written. */
 const withStatus = (line: string, index: number, status: string): string => {
@@ -42,7 +51,7 @@ const withStatus = (line: string, index: number, status: string): string => {
  */
 const closeRow = (
   board: string,
-  { heading, keys: keyNames, status: statusNames }: SectionColumns,
+  { heading, keys: keyColumns, language }: SectionColumns,
   keys: readonly [string, string],
   status: string,
 ): string | null => {
@@ -55,8 +64,8 @@ const closeRow = (
     .slice(1, header.endsWith('|') ? -1 : undefined)
     .split('|')
     .map((cell) => cell.trim())
-  const positions = keyNames.map((name) => names.indexOf(name))
-  const statusAt = names.findIndex((name) => statusNames.includes(name))
+  const positions = keyColumns.map((key) => columnIndex(names, key, language))
+  const statusAt = columnIndex(names, COLUMN_KEY.status, language)
   if (positions.includes(-1) || statusAt === -1) return null
   const row = firstTableRows(lines).find(({ cells }) =>
     positions.every((position, index) => squeezed(cells[position] ?? '') === squeezed(keys[index])),

package/src/plans/board-pick.ts

@@ -20,7 +20,7 @@ const changedAtOf = (root: string, settings: PlansSettings, file: string): numbe
 
 const candidateOf = (root: string, settings: PlansSettings, file: string): BoardCandidate => ({
   path: relative(root, file),
-  lanes: parseSprintLanes(readFileSync(file, 'utf8'), settings.planLanguage).map((lane) => lane.name),
+  lanes: parseSprintLanes(readFileSync(file, 'utf8'), settings.boardLanguage).map((lane) => lane.name),
   changedAt: changedAtOf(root, settings, file),
 })
 

package/src/plans/ensure-panes.ts

@@ -21,7 +21,7 @@ import {
   withAgentPanes,
   withForeground,
 } from './plan-panes'
-import type { PlansSettings } from './settings'
+import { type PlansSettings } from './settings'
 
 const panesWithForeground = (agentPanes: readonly string[]): { panes: PaneState[]; notes: string[] } =>
   withForeground(withAgentPanes(paneListOf(runHerdr(['pane', 'list'])), agentPanes), (pane) =>
@@ -30,7 +30,7 @@ const panesWithForeground = (agentPanes: readonly string[]): { panes: PaneState[
 
 /** The board's lanes that have a worktree, closed ones left out. */
 const lanesOf = (root: string, settings: PlansSettings, boardFile: string) =>
-  parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.planLanguage)
+  parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.boardLanguage)
     .filter((lane) => !lane.closed)
     .map((lane) => ({ name: lane.name, cwd: join(root, settings.worktreeDirectory, lane.name) }))
     .filter((lane) => existsSync(lane.cwd))

package/src/plans/layout-summary.ts

@@ -170,6 +170,10 @@ const checklistFrames = (
   return [...folder, ...frames, ...(open ? deferredFrames(active.phase, context.width) : [])]
 }
 
+/** The phase's purpose sentence, dim, on one row cut at `width`; no row for a phase without one. */
+const purposeFrame = (purpose: string | undefined, width: number): Frame =>
+  purpose ? textFrame([fit(paint.dim(plain(purpose)), width)]) : textFrame([])
+
 /**
  * A phase the lane works on: its head with the bar, no row of its own; under it the checklist of its tasks in the
  * plan's order, the running one marked (`checklistFrames`). `laneRuns` is false for a phase that only waits.
@@ -184,7 +188,10 @@ const activeFrame = (context: SummaryContext, active: ActivePhase, laneRuns = tr
   const running = runningTasks(active, laneRuns)
   return joinFrames([
     textFrame([phaseHead(active, current, context, model)]),
-    indented(joinFrames(checklistFrames(inner, key, active, running)), TASK_INDENT),
+    indented(
+      joinFrames([purposeFrame(active.phase.purpose, inner.width), ...checklistFrames(inner, key, active, running)]),
+      TASK_INDENT,
+    ),
   ])
 }
 

package/src/plans/layout.ts

@@ -182,6 +182,8 @@ export type OverviewView = {
   awaiting?: WaitingItem[]
   /** What is the user's turn, in a block under the title; absent for a herd without a board. */
   yourTurn?: YourTurnBlock
+  /** True when the board has `##` headings and jh reads none of them: an empty "Your turn" then says so instead of that nothing waits. */
+  boardUnread?: true
   /** The sources the watcher runs that are not tickets, in a block of their own under "Your turn". */
   sourceBlock?: SourceBlock
   /** Whole days since the board was groomed (`groomedDaysAgo`), beside the clock; null or absent when unknown. */
@@ -1403,9 +1405,9 @@ const turnMarkPaint = (mark: string): string => {
 }
 
 /** "Your turn" without a point: one line that cannot be opened, its name in the column of the other block names. */
-const emptyTurnLines = (): BlockLines => ({
+const emptyTurnLines = (emptyText: string): BlockLines => ({
   open: false,
-  lines: [`${blockBar()} ${TEXTS.yourTurnHeading} ${paint.dim(`${ITEM_SEPARATOR} ${TEXTS.yourTurnEmpty}`)}`],
+  lines: [`${blockBar()} ${TEXTS.yourTurnHeading} ${paint.dim(`${ITEM_SEPARATOR} ${emptyText}`)}`],
   hit: { rows: [], moreKey: null },
 })
 
@@ -1413,9 +1415,14 @@ const emptyTurnLines = (): BlockLines => ({
  * What is the user's turn, on top of the herd: the head `Your turn · <n>` with its balance, folded until the user opens
  * it; open, the now rows and the planned rows (`turnRows`), told apart by their mark alone.
  */
-const yourTurnLines = ({ turn, now }: YourTurnBlock, state: Selection, width: number): BlockLines => {
+const yourTurnLines = (
+  { turn, now }: YourTurnBlock,
+  state: Selection,
+  width: number,
+  emptyText: string,
+): BlockLines => {
   const count = turn.now.length + turn.planned.length
-  if (count === 0) return emptyTurnLines()
+  if (count === 0) return emptyTurnLines(emptyText)
   const opened = { allNow: state.expanded.has(YOUR_TURN_MORE_KEY), allPlanned: state.expanded.has(YOUR_TURN_LATER_KEY) }
   const clock = new Date(now)
   const block: TopBlock = {
@@ -1702,6 +1709,7 @@ export const renderScreen = (
     watchesTickets,
     awaiting = [],
     yourTurn,
+    boardUnread,
     sourceBlock,
     groomedDays,
     unplaced = [],
@@ -1719,7 +1727,8 @@ export const renderScreen = (
   const notice = watchNotice({ lanes: active, watch, watchesTickets }, badgeTexts)
   const status = [notice ? paint.yellow(notice) : '', groomedCell(groomedDays)].filter(Boolean).join(COLUMN_SEPARATOR)
   const titleLine = spread(`${HEADER_MARK} ${paint.bold(title)}`, status, width)
-  const turn = yourTurn ? yourTurnLines(yourTurn, state, width) : null
+  const emptyTurnText = boardUnread ? TEXTS.boardUnread : TEXTS.yourTurnEmpty
+  const turn = yourTurn ? yourTurnLines(yourTurn, state, width, emptyTurnText) : null
   const nowLines = unplaced.map((task) => nowLine(task, width, taskStyle))
   const above = nowLines.length > 0 ? [titleLine, rule(width), ...nowLines] : [titleLine]
   const listed = sourceLinesOf(sourceBlock, awaiting, state, width)

package/src/plans/live.ts

@@ -511,7 +511,7 @@ const applyBlockClick = (live: Live, outcome: BlockClick): void => {
   if ('done' in outcome) {
     const { closed, notice } = closeRow(outcome.done, {
       sprintFile: live.source.sprintFile,
-      language: live.source.settings.planLanguage,
+      language: live.source.settings.boardLanguage,
       now: new Date(),
       closeRecords: (ids) => closeWaiting(live.source.root, ids, Date.now()),
     })

package/src/plans/plan-panes.ts

@@ -151,7 +151,7 @@ export const isIdleShell = ({ agent, foreground }: PaneState): boolean =>
  * A restored pane whose shell is still starting: nothing in the foreground yet, or a shell first (its prompt may run
  * `git` beside it). Another program there, an editor or a pager, would take the command as its input.
  */
-const isStartingShell = ({ agent, foreground }: PaneState): boolean =>
+export const isStartingShell = ({ agent, foreground }: PaneState): boolean =>
   !agent && (foreground.length === 0 || SHELLS.has(programOf(foreground[0])))
 
 const hasHerdBeside = (panes: readonly PaneState[], agent: PaneState): boolean =>

package/src/plans/settings.ts

@@ -16,6 +16,8 @@ export type PlansSettings = Pick<
   JackherdConfig,
   'planDirectory' | 'board' | 'worktreeDirectory' | 'baseBranch' | 'planLanguage' | 'responseLanguage' | 'skillPrefix'
 > & {
+  /** The language jh writes the board in: the config's `boardLanguage`, or its `planLanguage` when it sets none. */
+  boardLanguage: JackherdConfig['planLanguage']
   adapter: JackherdConfig['terminal']['adapter']
   /** Free gigabytes a new lane needs on the disk (`lanes.minFreeGb`). */
   minFreeGb: number
@@ -23,6 +25,8 @@ export type PlansSettings = Pick<
   basePort: number
   /** The command `jh lane dev` starts a lane's dev server with (`lanes.devCommand`); undefined when none is set. */
   devCommand: string | undefined
+  /** The shared backend of the lanes (`lanes.backend`); undefined when none is set. */
+  backend: JackherdConfig['lanes']['backend']
   fetchIntervalMinutes: number
   /** Whether the running task of a folded lane shimmers; `NO_COLOR` keeps it still whatever this says. */
   shimmer: boolean
@@ -63,12 +67,14 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   worktreeDirectory: config.worktreeDirectory,
   baseBranch: config.baseBranch,
   planLanguage: config.planLanguage,
+  boardLanguage: config.boardLanguage ?? config.planLanguage,
   responseLanguage: config.responseLanguage,
   skillPrefix: config.skillPrefix,
   adapter: config.terminal.adapter,
   minFreeGb: config.lanes.minFreeGb ?? DEFAULT_MIN_FREE_GB,
   basePort: config.lanes.basePort ?? DEFAULT_BASE_PORT,
   devCommand: config.lanes.devCommand,
+  backend: config.lanes.backend,
   fetchIntervalMinutes: config.plans.fetchIntervalMinutes,
   shimmer: config.plans.shimmer,
   linkKinds: config.plans.linkKinds,

package/src/plans/snapshot.ts

@@ -15,6 +15,7 @@ import {
   shortTitle,
   sprintTitleOf,
 } from '../plan-format'
+import { firstUnrecognizedSectionLine } from '../plan-format/unrecognized-sections'
 import type { WaitingItem } from '../plan-format/waiting'
 import { dropUnused } from '../shared/stat-cache'
 import type { TaskSignal } from '../task-signals/types'
@@ -140,6 +141,8 @@ export type Snapshot = {
   groomedDays?: number | null
   /** What is the user's turn: `waiting`, the board's open appointments and its next section, one row per topic. */
   yourTurn?: YourTurnBlock
+  /** True when the board has `##` headings and jh reads none of them (`firstUnrecognizedSectionLine`). */
+  boardUnread?: true
   /** The sources of `watch.sources` not marked `ticket`, from the watcher's state, for the block under "Your turn". */
   sourceBlock?: SourceBlock
   /** The tone of each role, from the config, which `renderSnapshot` sets before it draws. */
@@ -535,7 +538,7 @@ const readBoardLanes = async (
   const atBase = textAtBase(base, boardPath)
   const markdown = atBase ?? (await readFallback(boardPath, sprintFile, fallbacks)) ?? ''
   const liveMarkdown = atBase !== null && existsSync(sprintFile) ? await Bun.file(sprintFile).text() : markdown
-  return { markdown, liveMarkdown, lanes: rowsOf(markdown, liveMarkdown, settings.planLanguage).lanes }
+  return { markdown, liveMarkdown, lanes: rowsOf(markdown, liveMarkdown, settings.boardLanguage).lanes }
 }
 
 /** The plans the sprint's plans tables name, read at the base ref, by link; lanes read theirs themselves. */
@@ -547,7 +550,7 @@ const readListedPlans = async (
   fallbacks: Fallbacks,
 ): Promise<Record<string, string>> => {
   const hrefs = new Set(
-    readSprintDocument(markdown, source.settings.planLanguage).planTables.flatMap(({ rows }) =>
+    readSprintDocument(markdown, source.settings.boardLanguage).planTables.flatMap(({ rows }) =>
       rows.flatMap((row) => (row.href ? [row.href] : [])),
     ),
   )
@@ -757,7 +760,7 @@ export const loadSnapshot = async (
   await gate.pass()
   const waitingRecords = readWaitingRecords(root)
   const waiting = withSourcePrefix(
-    waitingItemsOf(liveBoard, settings.planLanguage, waitingRecords, now),
+    waitingItemsOf(liveBoard, settings.boardLanguage, waitingRecords, now),
     sourceSettings.sourceLabels,
   )
   const sentChips = sentChipsByLane(waitingRecords.sent, worktrees, now)
@@ -810,8 +813,9 @@ export const loadSnapshot = async (
     errors: [...laneSet.errors, ...pullRequests.errors, ...(notice ? [notice] : [])],
     watch: reading?.health,
     waiting,
-    groomedDays: groomedDaysAgo(liveBoard, settings.planLanguage, new Date(now)),
-    yourTurn: yourTurnOfBoard(liveBoard, settings.planLanguage, waiting, now),
+    groomedDays: groomedDaysAgo(liveBoard, settings.boardLanguage, new Date(now)),
+    yourTurn: yourTurnOfBoard(liveBoard, settings.boardLanguage, waiting, now),
+    ...(firstUnrecognizedSectionLine(liveBoard) === null ? {} : { boardUnread: true as const }),
     ...(reading?.sources ? { sourceBlock: { sources: withSourceStyle(reading.sources, sourceSettings), now } } : {}),
     tones: settings.tones,
     ...(coordinator ? { coordinator: coordinator.view } : {}),

package/src/plans/sprint-export.ts

@@ -37,7 +37,7 @@ const pageOf = ({ root, sprintFile, settings }: Source, snapshot: Snapshot, envi
     baseRef: baseRefInfo(root, baseRefOf(settings)),
     repoBlobBase: remoteBlobBase(root, settings.baseBranch),
     sprintDirectory: dirname(boardRepoPathOf(root, settings, sprintFile)),
-    language: settings.planLanguage,
+    language: settings.boardLanguage,
     linkKinds: settings.linkKinds,
   })
 

package/src/plans/texts.ts

@@ -84,6 +84,8 @@ export type PlanTexts = {
   hintDonePhases: string
   /** After the head of "Your turn" when nothing waits for the user and nothing is planned. */
   yourTurnEmpty: string
+  /** After the head of "Your turn" when the board has `##` headings and jh reads none of them, so nothing can be said to wait. */
+  boardUnread: string
   notInPlan: string
   /** Before a task an agent reports that no task of the plan names. */
   now: string
@@ -189,6 +191,7 @@ export const TEXTS: PlanTexts = {
   hintNextPhases: 'the next phases',
   hintDonePhases: 'the done phases',
   yourTurnEmpty: 'nothing waits for you',
+  boardUnread: 'board: no section recognised',
   notInPlan: 'not in the plan',
   now: 'now:',
   subagent: 'Subagent:',

package/src/plans/view.ts

@@ -47,6 +47,7 @@ const overviewOf = (snapshot: Snapshot, shimmer: boolean): OverviewView => {
     awaiting: snapshot.waiting,
     groomedDays: snapshot.groomedDays,
     yourTurn: snapshot.yourTurn,
+    boardUnread: snapshot.boardUnread,
     sourceBlock: snapshot.sourceBlock,
     unplaced: snapshot.unplaced,
     coordinator: snapshot.coordinator,

package/src/resume/coordinator-read.ts

@@ -103,7 +103,7 @@ const lanesOf = ({ root, settings }: Place, board: string | null, agents: readon
   discoverLanes({
     worktrees: worktreeNames(join(root, settings.worktreeDirectory)),
     agentNames: (agents ?? []).flatMap((agent) => agent.name ?? []),
-    sprintLanes: board === null ? [] : parseSprintLanes(board, settings.planLanguage).map((lane) => lane.name),
+    sprintLanes: board === null ? [] : parseSprintLanes(board, settings.boardLanguage).map((lane) => lane.name),
   })
 
 /** `jh resume --coordinator`: prints what a cleared coordinator takes up, then the reference on it. Reads only. */
@@ -117,7 +117,7 @@ export const printCoordinatorState = async (boardPath: string | null): Promise<v
   const lines = coordinatorStateLines({
     boardPath: relative(root, boardFile),
     board,
-    language: settings.planLanguage,
+    language: settings.boardLanguage,
     lanes: lanes.map((lane) => laneFactsOf(place, agents, lane)),
     herdrAnswered: agents !== null,
     pullRequests: await readPullRequestsSafely(place, lanes),

package/src/settled/command.ts

@@ -54,7 +54,7 @@ export const run = async (args: string[]): Promise<number> => {
       foundLanesOf(root, settings, () => terminal.listAgents().map((agent) => agent.name)),
     )
     if (board.notice) console.error(board.notice)
-    const context = { now: new Date(), planLanguage: settings.planLanguage }
+    const context = { now: new Date(), boardLanguage: settings.boardLanguage }
     const outcome = settle(request, context, portsFor(checkout, board.file, settings.adapter))
     printOutcome(outcome)
     return outcome.exitCode

package/src/settled/settle.ts

@@ -15,7 +15,7 @@ export type SettlePorts = {
 }
 
 /** When it runs and in which language the board is written; the lane is told in English. */
-export type SettleContext = { now: Date; planLanguage: PlanLanguage }
+export type SettleContext = { now: Date; boardLanguage: PlanLanguage }
 
 export const SETTLE_EXIT = { settled: 0, refused: 1, notSent: 2 } as const
 
@@ -48,10 +48,10 @@ const chatLine = (request: CheckedRequest): string =>
  * not be written, or null; the send has failed either way, so a board error must not turn exit 2 into exit 1.
  */
 const noteFailure = (entry: SettledEntry, error: string, context: SettleContext, ports: SettlePorts): string | null => {
-  const row = settledRow(entry, context.planLanguage)
-  const noted = settledRow(withSendFailure(entry, error, context.planLanguage), context.planLanguage)
+  const row = settledRow(entry, context.boardLanguage)
+  const noted = settledRow(withSendFailure(entry, error, context.boardLanguage), context.boardLanguage)
   try {
-    ports.writeBoard(withReplacedRow(ports.readBoard(), row, noted, context.planLanguage))
+    ports.writeBoard(withReplacedRow(ports.readBoard(), row, noted, context.boardLanguage))
     return null
   } catch (noteError) {
     return errorText(noteError)
@@ -80,7 +80,7 @@ export const settle = (request: SettledRequest, context: SettleContext, ports: S
   }
   const { checked } = result
   const entry = entryOf(checked, context.now, ports.evidenceVersion(checked.evidence.path))
-  ports.writeBoard(withSettledRow(ports.readBoard(), settledRow(entry, context.planLanguage), context.planLanguage))
+  ports.writeBoard(withSettledRow(ports.readBoard(), settledRow(entry, context.boardLanguage), context.boardLanguage))
   const error = ports.send(checked.lane, laneMessageOf(checked))
   if (error === null) return { exitCode: SETTLE_EXIT.settled, stdout: [chatLine(checked)], stderr: [] }
   return notSent(checked, error, noteFailure(entry, error, context, ports))

package/src/shared/shell-word.ts

@@ -0,0 +1,2 @@
+/** One shell word that cannot start an option: a name that goes into a command line unquoted. */
+export const SHELL_WORD = /^(?!-)[\w@./:-]+$/