jackherd 1.6.0 → 1.7.0

package/src/plans/snapshot.ts

@@ -6,6 +6,7 @@ import { agentLog } from '../context/session-log'
 import {
   type LaneProgress,
   laneProgress,
+  type PlansByHref,
   readSprintDocument,
   resolvePlanPath,
   type SprintLane,
@@ -14,16 +15,20 @@ import {
 } from '../plan-format'
 import type { LaneAgent, LaneStatusSource } from '../terminal'
 import type { PlanLanguage } from '../vocabulary'
-import type { WatchBadges, WatchHealth } from '../watch/plan-badges'
+import type { SourceTicket, WatchBadges, WatchHealth } from '../watch/plan-badges'
 import { readWatchReading } from '../watch/plan-badges-read'
 import { boardRowsOf } from './board-rows'
+import { type LaneMemory, newestRowIdentity, nextMemory, withMovedPhase } from './current-phase'
 import { errorText } from './error-text'
 import { type BaseReader, baseReaderOf, gitStatusOf, refExists } from './git'
 import type { PullRequestState } from './github'
 import { type Fallbacks, laneWorkOf, readAtBase, readFallback, readPlans, textAtBase } from './lane-plans'
+import { boardRowTexts, laneTicketsOf, withoutTicketLinks } from './lane-tickets'
 import { type LaneView, sortByUrgency } from './layout'
 import { extractLinkChips } from './link-chips'
 import type { Options } from './options'
+import { laneModelsOf, type PhaseModelRecord } from './phase-models'
+import { readPhaseModels } from './phase-models-read'
 import { currentPlanFirst, followingPlans, type PlannedPlan, plannedPlans } from './planned'
 import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from './settings'
 import { boardTexts } from './texts'
@@ -68,8 +73,13 @@ export type Snapshot = {
   files: string[]
   titles: Map<string, string | null>
   errors: string[]
-  /** The watcher's health; absent when no lane has an open pull request, so the watcher was not looked at. */
+  /**
+   * The watcher's health; absent when no lane has an open pull request and no source is marked `ticket`, so the
+   * watcher was not looked at.
+   */
   watch?: WatchHealth
+  /** True when the config marks a ticket source, so a missing watcher is said without a pull request too. */
+  watchesTickets?: boolean
   /** The project's response language, for the words of the watcher's badges. */
   language?: PlanLanguage
 }
@@ -114,7 +124,28 @@ const runningState = async (sources: LaneSources, name: string, agent: LaneAgent
   }
 }
 
-const laneView = async (sources: LaneSources, lane: SprintLane, fallbacks: Fallbacks): Promise<LaneResult> => {
+/**
+ * The progress of a lane with the phase whose boxes moved since the last read as its current one: the lane's memory
+ * in `memories` is updated by this read. Without `memories` the newest board row decides alone.
+ */
+const progressWithMemory = (
+  shown: SprintLane,
+  plans: PlansByHref,
+  memories: Map<string, LaneMemory> | undefined,
+): LaneProgress => {
+  const progress = laneProgress(shown, plans)
+  if (!memories) return progress
+  const memory = nextMemory(memories.get(shown.name), plans, newestRowIdentity(progress))
+  memories.set(shown.name, memory)
+  return withMovedPhase(progress, memory.moved)
+}
+
+const laneView = async (
+  sources: LaneSources,
+  lane: SprintLane,
+  fallbacks: Fallbacks,
+  memories?: Map<string, LaneMemory>,
+): Promise<LaneResult> => {
   const { source, agents } = sources
   const { root, settings } = source
   const worktree = worktreeOf(root, settings, lane.name)
@@ -127,7 +158,7 @@ const laneView = async (sources: LaneSources, lane: SprintLane, fallbacks: Fallb
     fallbacks,
   )
   const shown = withWorkedPhases(lane, plans)
-  const progress = laneProgress(shown, plans)
+  const progress = progressWithMemory(shown, plans, memories)
   const view: LaneView = {
     progress,
     ...running,
@@ -171,6 +202,23 @@ const withBadges = (view: LaneView, badges: WatchBadges): LaneView => {
   return Object.keys(own).length > 0 ? { ...view, badges: own } : view
 }
 
+/** The view with the model each of its phases last ran on, only when there is one, so it otherwise stays as it was. */
+const withModels = (view: LaneView, records: readonly PhaseModelRecord[], sprintDirectory: string): LaneView => {
+  const models = laneModelsOf(view.progress, records, sprintDirectory)
+  return Object.keys(models).length > 0 ? { ...view, models } : view
+}
+
+/**
+ * The view with the lane's tickets, found by its source lane or by its id in the board rows and plan texts of the
+ * lane; a link chip with the URL of a shown ticket gives way to the badge. Without tickets it stays as it was.
+ */
+const withTickets = (result: LaneResult, tickets: readonly SourceTicket[]): LaneView => {
+  const { view, texts } = result
+  const lane = view.progress.lane
+  const found = laneTicketsOf(tickets, lane.name, [...boardRowTexts(lane), ...Object.values(texts)])
+  return found ? { ...view, chips: withoutTicketLinks(view.chips, found), tickets: found } : view
+}
+
 /** The terminal's agents, or none with the reason when it cannot be asked, so the screen says why lanes show "no agent". */
 const readAgents = (terminal: LaneStatusSource): { agents: LaneAgent[]; errors: string[] } => {
   try {
@@ -234,7 +282,20 @@ const readListedPlans = async (
   return Object.fromEntries(entries.flat())
 }
 
-export const loadSnapshot = async (source: Source, pullRequests: PullRequestState): Promise<Snapshot> => {
+const forgetLanes = (memories: Map<string, LaneMemory> | undefined, lanes: readonly SprintLane[]): void => {
+  const names = new Set(lanes.map((lane) => lane.name))
+  for (const name of [...(memories?.keys() ?? [])]) if (!names.has(name)) memories?.delete(name)
+}
+
+/**
+ * Reads the board, its plans and the lanes' state. `memories` holds, per lane, what the herd saw at the last read; it
+ * is how the current phase becomes the one whose boxes moved since, and it is cleaned of lanes the board dropped.
+ */
+export const loadSnapshot = async (
+  source: Source,
+  pullRequests: PullRequestState,
+  memories?: Map<string, LaneMemory>,
+): Promise<Snapshot> => {
   const { root, sprintFile, options, settings, terminal } = source
   const fallbacks: Fallbacks = []
   const base = baseReaderOf(root, baseRefOf(settings))
@@ -258,9 +319,10 @@ export const loadSnapshot = async (source: Source, pullRequests: PullRequestStat
     pullRequests,
   }
   const results = [
-    ...(await Promise.all(lanes.map((lane) => laneView(sources, lane, fallbacks)))),
+    ...(await Promise.all(lanes.map((lane) => laneView(sources, lane, fallbacks, memories)))),
     ...(await Promise.all(unlisted.map((lane) => unlistedView(sources, lane)))),
   ]
+  forgetLanes(memories, lanes)
   const listedPlans = await readListedPlans(source, base, sprintDirectory, markdown, fallbacks)
   const documentsPlans = Object.assign({}, listedPlans, ...results.map((result) => result.texts))
   const planned = options.lane
@@ -271,14 +333,25 @@ export const loadSnapshot = async (source: Source, pullRequests: PullRequestStat
         sprintDirectory,
         language: settings.planLanguage,
       })
-  const reading = results.some(({ view }) => view.pullRequests.length > 0) ? readWatchReading(root, Date.now()) : null
+  const { ticketSources } = settings
+  const watched = ticketSources.length > 0 || results.some(({ view }) => view.pullRequests.length > 0)
+  const reading = watched ? readWatchReading(root, Date.now(), ticketSources) : null
+  const phaseModels = readPhaseModels(root)
   const baseRef = baseRefOf(settings)
   const notice = fallbacks.length > 0 ? fallbackNotice(fallbacks, baseRef, refExists(root, baseRef)) : null
   const unknownLaneTitle =
     options.lane && results.length === 0 ? boardTexts(settings.board.term).laneNotListed(options.lane) : null
   return {
     title: unknownLaneTitle ?? sprintTitleOf(markdown, sprintDirectory),
-    views: sortByUrgency(results.map((result) => withBadges(result.view, reading?.badges ?? {}))),
+    views: sortByUrgency(
+      results.map((result) =>
+        withModels(
+          withBadges(withTickets(result, reading?.tickets ?? []), reading?.badges ?? {}),
+          phaseModels,
+          sprintDirectory,
+        ),
+      ),
+    ),
     documents: {
       sprint: markdown,
       plans: documentsPlans,
@@ -295,6 +368,7 @@ export const loadSnapshot = async (source: Source, pullRequests: PullRequestStat
       ...(source.boardNotice ? [source.boardNotice] : []),
     ],
     watch: reading?.health,
+    ...(ticketSources.length > 0 ? { watchesTickets: true } : {}),
     language: settings.responseLanguage,
   }
 }

package/src/plans/sprint-html.ts

@@ -15,7 +15,7 @@ import type {
   SprintPage,
 } from './sprint-page'
 import { phaseCountOf, phaseStateOf, statusSymbol, statusWord } from './symbols'
-import { laneMarkText, TEXTS } from './texts'
+import { checksText, laneMarkText, TEXTS } from './texts'
 
 const BAR_PERCENT = 100
 
@@ -149,7 +149,7 @@ const pullRequestLine = (lane: PageLane): string =>
   lane.pullRequests
     .map(
       (pull) =>
-        `<div class="pr">↗ ${linked(pull.url, `#${pull.number}`)} <span class="checks-${pull.checks}">${escapeHtml(TEXTS.checks[pull.checks])}</span> ${escapeHtml(pull.draft ? TEXTS.draft : '')}${escapeHtml(pull.title)}</div>`,
+        `<div class="pr">↗ ${linked(pull.url, `#${pull.number}`)} <span class="checks-${pull.checks}">${escapeHtml(checksText(pull))}</span> ${escapeHtml(pull.draft ? TEXTS.draft : '')}${escapeHtml(pull.title)}</div>`,
     )
     .join('')
 

package/src/plans/supervisor.ts

@@ -4,6 +4,7 @@ import { dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { pendingKitUpdate, VERSION_POLL_MS } from '../version/installed-version'
 import type { StartedKit } from '../version/started-kit'
+import { HERD_COMMAND } from './herd-command'
 import { CHILD_MARKER, exitCodeOf, isRestartTrigger, nextStep, RESTART_DEBOUNCE_MS } from './restart-decision'
 import { TERMINAL_OFF } from './view'
 
@@ -13,7 +14,7 @@ const packageSourceDirectory = (): string => dirname(dirname(fileURLToPath(impor
 
 const entryScript = (): string => {
   const script = process.argv[1]
-  if (!script) throw new Error('Cannot supervise the plans view: process.argv[1] is missing')
+  if (!script) throw new Error('Cannot supervise the herd: process.argv[1] is missing')
   return script
 }
 
@@ -21,7 +22,7 @@ const describeEnd = (code: number | null, signal: NodeJS.Signals | null): string
   signal ? `signal ${signal}` : `exit ${code}`
 
 const spawnView = (scriptPath: string, args: string[]): ChildProcess =>
-  spawn(process.execPath, [scriptPath, 'plans', ...args], {
+  spawn(process.execPath, [scriptPath, HERD_COMMAND.name, ...args], {
     stdio: 'inherit',
     env: { ...process.env, [CHILD_MARKER]: '1' },
   })
@@ -59,7 +60,7 @@ export const superviseView = (
     const waitForChange = (reason: string): void => {
       child = undefined
       process.stdout.write(TERMINAL_OFF)
-      console.log(`plans view stopped (${reason}); waiting for the next change to src/`)
+      console.log(`herd stopped (${reason}); waiting for the next change to src/`)
     }
 
     const start = (isFirst: boolean): void => {
@@ -69,7 +70,7 @@ export const superviseView = (
       current.on('error', (error) => {
         if (child !== current) return
         if (isFirst) {
-          console.error(`plans view could not start: ${error.message}`)
+          console.error(`herd could not start: ${error.message}`)
           finish(1)
           return
         }

package/src/plans/symbols.ts

@@ -1,11 +1,11 @@
 import { AGENT_STATUS, type AgentStatus, isAgentStatus } from '../terminal/types'
 
-/** The symbols and words the plans views share: herdr's own status words, and the state of a phase. */
+/** The symbols and words the herd panes share: herdr's own status words, and the state of a phase. Every lane state is one terminal cell; the layout colours it. */
 export const STATUS_SYMBOL: Record<AgentStatus, string> = {
-  [AGENT_STATUS.working]: '⚡',
-  [AGENT_STATUS.blocked]: '❓',
-  [AGENT_STATUS.idle]: '⏸',
-  [AGENT_STATUS.done]: '📨',
+  [AGENT_STATUS.working]: '●',
+  [AGENT_STATUS.blocked]: '◆',
+  [AGENT_STATUS.idle]: '○',
+  [AGENT_STATUS.done]: '◉',
 }
 export const NO_AGENT_SYMBOL = '·'
 export const NO_AGENT_WORD = 'no agent'
@@ -18,7 +18,7 @@ export const statusSymbol = (agent: string | null): string => {
 
 export const statusWord = (agent: string | null): string => agent ?? NO_AGENT_WORD
 
-/** Before a row that opens and closes: lanes, the notes of a lane, the planned phases, the ticked items of a phase. */
+/** Before a row that opens and closes: lanes, the planned phases, the ticked items of a phase. */
 export const CHEVRON = { closed: '▸', open: '▾' } as const
 
 export const chevronOf = (open: boolean): string => (open ? CHEVRON.open : CHEVRON.closed)
@@ -45,6 +45,9 @@ export const phaseStateOf = ({
 /** What a phase shows in place of a symbol: `0/5`, `✓ 15/15`, `–` without checkboxes, `?` when the plan lacks it. */
 export const PHASE_COUNT = { missing: '?', empty: '–', allTicked: '✓' } as const
 
+/** Beside the model a phase's subagent ran on: it fits the plan's recommendation, or it differs from it. */
+export const MODEL_MARK = { fits: '✓', differs: '≠' } as const
+
 export const phaseCountOf = (phase: { title: string | null; done: number; total: number }): string => {
   const state = phaseStateOf(phase)
   if (state === PHASE_STATE.missing) return PHASE_COUNT.missing

package/src/plans/texts.ts

@@ -1,9 +1,10 @@
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
-import { CHECKS, type ChecksState } from './pull-requests'
-import { NO_AGENT_WORD, PHASE_COUNT } from './symbols'
+import { CHECK_NAME_LENGTH, CHECKS, type ChecksState, type PullRequest } from './pull-requests'
+import { shownWithMore } from './shown-with-more'
+import { MODEL_MARK, NO_AGENT_WORD, PHASE_COUNT } from './symbols'
 
 /**
- * Everything the plans view says in words but the watcher's badges. The view is English whatever language the
+ * Everything the herd says in words but the watcher's badges. The herd is English whatever language the
  * project answers in; plan and phase titles come from the plans as written, and the status words are herdr's own terms.
  */
 export type PlanTexts = {
@@ -15,11 +16,10 @@ export type PlanTexts = {
   noRow: string
   notInPlan: string
   noCheckboxes: string
-  ticked: string
+  /** In place of the count of a phase whose only open box is the documentation box of its review gate. */
+  allButDocs: string
   tickedUnmerged: string
   tickedSummary: (count: number) => string
-  notesHidden: (count: number) => string
-  notesShown: (count: number) => string
   draft: string
   privateLink: string
   planned: (phases: number, plans: number) => string
@@ -59,7 +59,7 @@ export const BADGE_TEXTS: Record<PlanLanguage, BadgeTexts> = {
   },
 }
 
-/** What the view says about a board, in the word the project calls it (`board.term`). */
+/** What the herd says about a board, in the word the project calls it (`board.term`). */
 export const boardTexts = (term: string) => ({
   missing: (glob: string) => `no ${term} under ${glob}`,
   laneNotListed: (lane: string) => `lane "${lane}" is not in the ${term}`,
@@ -70,6 +70,8 @@ export const boardTexts = (term: string) => ({
   notReadable: (reason: string) => `${term} not readable: ${reason}`,
 })
 
+const ALL_BUT_DOCS = 'docs open'
+
 export const TEXTS: PlanTexts = {
   noAgent: NO_AGENT_WORD,
   waiting: (lanes) => `waiting (${lanes})`,
@@ -79,11 +81,9 @@ export const TEXTS: PlanTexts = {
   noRow: 'no row in lanes',
   notInPlan: 'not in the plan',
   noCheckboxes: 'no checkboxes',
-  ticked: 'ticked',
+  allButDocs: ALL_BUT_DOCS,
   tickedUnmerged: 'ticked, not merged',
   tickedSummary: (count) => `${count} ticked · click or a lists them`,
-  notesHidden: (count) => `${count} ${count === 1 ? 'note' : 'notes'} hidden · click or n shows them`,
-  notesShown: (count) => `${count} ${count === 1 ? 'note' : 'notes'} shown · click or n hides them`,
   draft: 'draft · ',
   privateLink: 'private',
   following: (groups) => `also open · ${groups}`,
@@ -95,13 +95,30 @@ export const TEXTS: PlanTexts = {
     [CHECKS.pending]: '… checks',
     [CHECKS.none]: 'no checks',
   },
-  hint: '↑↓ select  →← open  a all  n notes  s html  q quit  ? help',
+  hint: '↑↓ select  →← open  a show ticked  s html  q quit  ? help',
   legend: [
     'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a 📎 chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
-    '⚡ working · ❓ blocked, waits for you · 📨 done = the agent finished its answer, not the lane · ⏸ idle · · no agent = a worktree nobody works in · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · working and blocked lanes open by themselves, → ← overrule until the status changes',
-    `n/m = m checkboxes of the phase, n ticked (the phase being worked on is yellow; ticked, not merged = all ticked in the worktree, not on the base branch yet) · ${PHASE_COUNT.allTicked} n/n all ticked · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · n shows or hides the notes of a lane · s opens every lane and plan as one HTML page · ⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main`,
+    '● working · ◆ blocked, waits for you · ◉ done = the agent finished its answer, not the lane · ○ idle · (·) no agent = a worktree nobody works in · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · working and blocked lanes open by themselves, → ← overrule until the status changes',
+    `▸ ▾ open and close · ▶ next open task · ✓ finished phase · ${ALL_BUT_DOCS} = only the documentation box is open · ticked, not merged = all ticked in the worktree, not on the base branch yet · the herd follows the phase whose boxes moved last, in yellow · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a lists the ticked checkboxes one by one · s opens every lane and plan as one HTML page`,
+    `◐ lane progress · n/m = m checkboxes of the phase, n ticked · n/n in green = all ticked · 🥣 share of the context window used · Opus ${MODEL_MARK.fits} = the phase's subagent ran on the plan's model, Sonnet ${MODEL_MARK.differs} Opus in amber = on another`,
+    '↗ pull request · 💬 new feedback · ✋ changes requested · 🌐 preview · 📡 ticket: chip 📡 T-1 · status under 📎, 📡 <n> in amber on a folded lane when tickets are new',
+    '⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main',
   ],
 }
 
 /** The mark of a running lane the board has no row for; null for a lane it lists. */
 export const laneMarkText = (lane: { unlisted?: boolean }): string | null => (lane.unlisted ? TEXTS.noRow : null)
+
+/** The most red checks the checks column names; the rest is counted. */
+export const NAMED_CHECKS = 3
+
+/**
+ * The words of a pull request's check state: `✗ test, lint` names the red checks (at most `NAMED_CHECKS`, then
+ * `+<n>`), every other state and a red one without names is the fixed word of `PLAN_TEXTS.checks`.
+ */
+export const checksText = ({ checks, failedChecks }: Pick<PullRequest, 'checks' | 'failedChecks'>): string => {
+  if (checks !== CHECKS.failed || failedChecks.length === 0) return TEXTS.checks[checks]
+  const { shown, more } = shownWithMore(failedChecks, NAMED_CHECKS)
+  const names = shown.map((name) => name.slice(0, CHECK_NAME_LENGTH)).join(', ')
+  return `✗ ${names}${more > 0 ? ` +${more}` : ''}`
+}

package/src/plans/view.ts

@@ -36,6 +36,7 @@ export const renderSnapshot = (
       lanes: snapshot.views,
       planned: snapshot.planned,
       watch: snapshot.watch,
+      watchesTickets: snapshot.watchesTickets,
       language: snapshot.language,
     },
     selection,

package/src/sync/herdr-plugin.ts

@@ -142,7 +142,7 @@ export const linkHerdrPlugin = ({
     return `Could not link the herdr plugin, herdr said: ${result.output || `exit ${result.exitCode}`}`
   const linkedLine = linked
     ? `Relinked the herdr plugin from ${linked.root} to ${directory} (${reasonText(reason, linked)}).`
-    : 'Linked the herdr plugin (the pane and the action for the plans view).'
+    : 'Linked the herdr plugin (the pane and the action for the herd).'
   return joinLines(linkedLine, unlink())
 }
 

package/src/sync/next-steps.ts

@@ -36,7 +36,7 @@ export const nextSteps = ({ skillPrefix, adapter, tools, version, cli }: NextSte
     `${orchestrate}: run a board's phases in parallel lanes.`,
     herdrLine(orchestrate, adapter, tools),
     ghLine(orchestrate, tools),
-    `${cli} plans: see every plan and lane in one view.`,
+    `${cli} herd: the whole herd at a glance, the state of every lane.`,
     `Docs: https://www.npmjs.com/package/${PACKAGE_NAME}/v/${version}#documentation`,
   ]
 }

package/src/sync/render.ts

@@ -1,6 +1,6 @@
 import type { JackherdConfig } from '../config'
 import { frozenInstallCommand } from '../config/detect'
-import { ADDRESS_FORM, LANGUAGE_NAME, PLAN_VOCABULARY, SELF_MERGE_LABEL } from '../vocabulary'
+import { ADDRESS_FORM, APPROVAL_TEXTS, LANGUAGE_NAME, PLAN_VOCABULARY, SELF_MERGE_LABEL } from '../vocabulary'
 
 const PLACEHOLDER = /\{\{\s*(kit\.[A-Za-z0-9_.-]*)\s*\}\}/g
 
@@ -39,6 +39,7 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ...prefixed('board', config.board),
     ['kit.guard.selfMergeLabel', SELF_MERGE_LABEL[config.responseLanguage]],
     ['kit.guard.selfMerge', config.guard.selfMerge.offer ? 'offered' : 'not offered'],
+    ...prefixed('approval', APPROVAL_TEXTS[config.responseLanguage]),
     ['kit.merge.withoutChecks', checkFreeList(config.merge.withoutChecks)],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
   ])

package/src/sync/setup-questions.ts

@@ -11,7 +11,7 @@ const LANGUAGE_CHOICES: readonly Choice<PlanLanguage>[] = [PLAN_LANGUAGE.en, PLA
 }))
 
 const ADAPTER_CHOICES: readonly Choice<TerminalAdapter>[] = [
-  { value: TERMINAL_ADAPTER.herdr, label: 'Yes, use herdr (agent states and context fill in the plans view)' },
+  { value: TERMINAL_ADAPTER.herdr, label: 'Yes, use herdr (agent states and context fill in the herd)' },
   { value: TERMINAL_ADAPTER.none, label: 'No, not now' },
 ]
 
@@ -20,7 +20,7 @@ const RESPONSE_QUESTION = 'Which language should the skills answer you in?'
 const PLAN_QUESTION = 'Which language should plans and boards be written in? It sets their headings.'
 
 const ADAPTER_QUESTION =
-  'Use herdr? It runs parallel lanes for /orchestrate and shows each agent in the plans view; /plan and /implement work without it.'
+  'Use herdr? It runs parallel lanes for /orchestrate and shows each agent in the herd; /plan and /implement work without it.'
 
 const INSTALL_QUESTION = `herdr is not installed. It is only needed for parallel lanes. Install it now with its official installer, \`${INSTALLERS.herdr}\`?`
 

package/src/terminal/text.ts

@@ -41,6 +41,7 @@ export const paint = {
   green: style('32'),
   yellow: style('33'),
   magenta: style('35'),
+  teal: style('38;5;37'),
   cyan: style('36'),
   inverse: style('7'),
 }
@@ -67,6 +68,9 @@ export const link = (url: string, text: string): string =>
 export const badge = (url: string, text: string, hint = '', tone: BadgeTone = BADGE_TONE.grey): string =>
   `${ESC}[${tone}m ${link(url, text)}${hint ? `${FAINT_ON} ${hint}${FAINT_OFF}` : ''} ${RESET}`
 
+/** `text` as a badge without a link, for what no click opens: the background of `tone`, a cell of padding either side. */
+export const box = (text: string, tone: BadgeTone = BADGE_TONE.grey): string => `${ESC}[${tone}m ${text} ${RESET}`
+
 /** A line for output that is not a terminal: styling dropped, each link written out as `text (url)`. */
 export const plainText = (text: string): string =>
   stripAnsi(text.replace(LINK, (_, url, inner) => `${stripAnsi(inner)} (${url})`))

package/src/terminal/types.ts

@@ -16,7 +16,7 @@ export type AdoptedName = { pane: string; name: string }
 export type LaneAgent = { name: string; pane: string; status: string; session: string | null; cwd: string | null }
 
 /**
- * Where lane agents run. The plans view reads agent status and sets a short title per lane through
+ * Where lane agents run. The herd reads agent status and sets a short title per lane through
  * this; the adapter `none` stands for a setup without a terminal multiplexer.
  */
 export type LaneStatusSource = {

package/src/vocabulary/index.ts

@@ -38,6 +38,25 @@ export const SELF_MERGE_LABEL: Record<PlanLanguage, string> = {
   [PLAN_LANGUAGE.de]: 'Freigeben, und nach grünen Checks selbst mergen',
 }
 
+/**
+ * The words of an approval: the two option labels of the coordinator's question about a lane's call, which the
+ * approval gate hook matches exactly, and what the hook tells the lane when it denies. Fixed per language, not config.
+ */
+export const APPROVAL_TEXTS: Record<PlanLanguage, { allow: string; deny: string; pending: string; denied: string }> = {
+  [PLAN_LANGUAGE.en]: {
+    allow: 'Allow this call',
+    deny: 'Deny this call',
+    pending: 'Approval pending with the coordinator; retry the same call once it is approved.',
+    denied: 'The user denied this call through the coordinator; do not retry it.',
+  },
+  [PLAN_LANGUAGE.de]: {
+    allow: 'Aufruf erlauben',
+    deny: 'Aufruf ablehnen',
+    pending: 'Freigabe steht aus beim Koordinator; denselben Aufruf nach der Freigabe erneut versuchen.',
+    denied: 'Der User hat diesen Aufruf über den Koordinator abgelehnt; nicht erneut versuchen.',
+  },
+}
+
 export const isPlanLanguage = (value: string): value is PlanLanguage =>
   (Object.values(PLAN_LANGUAGE) as string[]).includes(value)
 
@@ -81,8 +100,18 @@ export type PlanVocabulary = {
   laneClosed: string
   /** Words a starts-after cell begins with when the lane may start at once. */
   startsNow: readonly string[]
+  /** Opens the parenthesis by which a board row's phases cell records a user's side order in prose. */
+  sideOrderMarker: string
   /** Words that may stand between two phases of one entry (`P1 Rule und P2 Monitor`). */
   phaseConnectors: readonly string[]
+  /** Words that open a writes cell naming another phase's set instead of listing it (`wie 15`). */
+  writesLike: readonly string[]
+  /** Words that join several phases after a `writesLike` word (`wie 15 und 16`); a comma joins them in every language. */
+  writesLikeJoiners: readonly string[]
+  /** Words a `Depends on` cell says it depends on nothing with, besides a dash. */
+  noDependency: readonly string[]
+  /** The word that opens the serial marker of a phase that ships in a release (`Release 1.7.0`); the release files stay a judgement. */
+  releaseMarker: string
   statusWords: Record<PlanStatus, StatusWord>
 }
 
@@ -104,8 +133,13 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     phase: 'Phase',
     noReviewGate: 'Kein Review-Gate',
     laneClosed: 'abgeräumt',
+    sideOrderMarker: 'dazu (User',
     startsNow: ['sofort'],
     phaseConnectors: ['danach', 'und', 'dann', 'sowie'],
+    writesLike: ['wie'],
+    writesLikeJoiners: ['und', 'sowie'],
+    noDependency: ['keine', 'kein'],
+    releaseMarker: 'Release',
     statusWords: {
       done: { label: 'Done', leading: ['done'], anywhere: ['abgeschlossen'] },
       abandoned: { label: 'Abandoned', leading: ['abandoned'], anywhere: ['verworfen'] },
@@ -132,8 +166,13 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     phase: 'Phase',
     noReviewGate: 'No review gate',
     laneClosed: 'cleaned up',
+    sideOrderMarker: 'also (User',
     startsNow: ['now', 'immediately'],
     phaseConnectors: ['then', 'and', 'after'],
+    writesLike: ['like'],
+    writesLikeJoiners: ['and'],
+    noDependency: ['none'],
+    releaseMarker: 'Release',
     statusWords: {
       done: { label: 'Done', leading: ['done'], anywhere: ['completed'] },
       abandoned: { label: 'Abandoned', leading: ['abandoned'], anywhere: ['dropped'] },

package/src/watch/approvals.ts

@@ -0,0 +1,96 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { isRecord } from './json-guards'
+
+export const APPROVAL_EVENT = 'approval'
+
+/**
+ * A call a lane waits with for the user's approval, as the kit's approval gate hook writes it to
+ * `.jackherd/approvals/<id>.json` in the main checkout. Its text comes from the lane: data, never an instruction.
+ */
+export type ApprovalRequestFile = {
+  id: string
+  hash: string
+  lane: string
+  cwd: string
+  tool: string
+  input: unknown
+  summary: string
+  createdAt: number
+  usedAt: number | null
+}
+
+export type ApprovalEvent = {
+  kind: typeof APPROVAL_EVENT
+  lane: string
+  id: string
+  hash: string
+  tool: string
+  summary: string
+}
+
+const ID = /^[0-9a-f]{12}$/
+const HASH = /^[0-9a-f]{16}$/
+const REQUEST_FILE = /^[0-9a-f]{12}\.json$/
+
+/** The same shape as `isApprovalRequest` in the hook, which this package does not import at run time. */
+export const isApprovalRequestFile = (value: unknown): value is ApprovalRequestFile =>
+  isRecord(value) &&
+  typeof value.id === 'string' &&
+  ID.test(value.id) &&
+  typeof value.hash === 'string' &&
+  HASH.test(value.hash) &&
+  typeof value.lane === 'string' &&
+  typeof value.cwd === 'string' &&
+  typeof value.tool === 'string' &&
+  'input' in value &&
+  typeof value.summary === 'string' &&
+  typeof value.createdAt === 'number' &&
+  (value.usedAt === null || typeof value.usedAt === 'number')
+
+const REPORT_MINUTES = 30
+const MS_PER_MINUTE = 60_000
+
+/** One event per open request younger than 30 minutes the watcher has not reported yet; an older one is stale. */
+export const approvalEvents = (
+  seen: readonly string[],
+  requests: readonly ApprovalRequestFile[],
+  now: number,
+): ApprovalEvent[] =>
+  requests
+    .filter(
+      (request) =>
+        request.usedAt === null &&
+        !seen.includes(request.id) &&
+        now - request.createdAt <= REPORT_MINUTES * MS_PER_MINUTE,
+    )
+    .map(({ lane, id, hash, tool, summary }) => ({ kind: APPROVAL_EVENT, lane, id, hash, tool, summary }))
+
+/** The ids to remember: every request still on disk, so one that is gone is forgotten. */
+export const recordApprovals = (requests: readonly ApprovalRequestFile[]): string[] =>
+  requests.map((request) => request.id)
+
+const requestFileNames = (directory: string): string[] => {
+  try {
+    return readdirSync(directory).filter((name) => REQUEST_FILE.test(name))
+  } catch {
+    return []
+  }
+}
+
+/**
+ * The requests in the main checkout's `.jackherd/approvals/`, a claimed one as used; a file that does not parse is
+ * skipped, and a directory that cannot be listed reads as none, so the watch goes on.
+ */
+export const readApprovalRequests = (root: string): ApprovalRequestFile[] => {
+  const directory = join(root, '.jackherd', 'approvals')
+  return requestFileNames(directory).flatMap((name) => {
+    try {
+      const request: unknown = JSON.parse(readFileSync(join(directory, name), 'utf8'))
+      if (!isApprovalRequestFile(request) || `${request.id}.json` !== name) return []
+      return [existsSync(join(directory, `${request.id}.used`)) ? { ...request, usedAt: request.createdAt } : request]
+    } catch {
+      return []
+    }
+  })
+}