jackherd 1.7.0 → 1.8.0

package/src/plan-format/dependencies.ts

@@ -1,13 +1,15 @@
 import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { PHASE_ID_PREFIX } from './lanes'
+import { PHASE_ID_PREFIX, phaseLabels } from './lanes'
 import { escapeRegExp, firstTableWithHeader, subsectionLines } from './markdown'
 import { type PhaseHeading, parsePlanPhases, phaseHeadings } from './phases'
+import { isPhaseFinished } from './progress'
 
 /**
  * A row of the dependency table. `after` holds the phases it waits for, `external` the entries that name no phase
  * (`User: Zuruf`) or a range that cannot be expanded; `writes` are the paths of the writes cell (`''` is the whole
  * repository), `writesLike` the phases whose sets the cell takes over (`wie 15 und 16`); `serialMarkers` are the
- * entries of the marker cell that keep two phases apart.
+ * entries of the marker cell that keep two phases apart, `releases` the packages its release markers name
+ * (`Release jackherd 1.8.0` is `jackherd`).
  */
 export type PhaseDependency = {
   id: string
@@ -16,12 +18,16 @@ export type PhaseDependency = {
   writes: string[]
   writesLike: string[]
   serialMarkers: string[]
+  releases: string[]
 }
 
+/** The open phases in waves (each starts once the ones before it are done), the longest chain, and the open phases no wave holds. */
+export type PhaseSchedule = { waves: string[][]; criticalPath: string[]; unplaced: string[] }
+
 /** A phase heading (1-based line) the dependency table has no row for. */
 export type PhaseWithoutRow = PhaseHeading
 
-type Candidate = { id: string; writes: string[]; serialMarkers: string[] }
+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')
@@ -30,6 +36,10 @@ const BACKTICKED = /`([^`]+)`/g
 const NO_VALUE = /^[—–-]?$/
 const TRAILING_NOTE = /\s*\([^)]*\)\s*$/
 const GLOB_CHARACTER = /[*?{[]/
+const VERSION = /^v?\d+(?:[.\-+][\w.-]*)?$/i
+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 MAX_RANGE = 50
 
 const phaseIdOf = (cell: string): string | null => PHASE_ID.exec(cell)?.[1]?.toLowerCase() ?? null
@@ -109,18 +119,51 @@ const writesOf = (cell: string, language: PlanLanguage): Pick<PhaseDependency, '
   writesLike: writesLikeOf(cell, language),
 })
 
-/**
- * The marker cell's entries, split at `;`, without a trailing note in parentheses and without the release entry: the
- * release word followed by a space or the end, in any case (`Release-Pipeline` is a marker of its own).
- */
-const markersOf = (cell: string, language: PlanLanguage): string[] => {
-  const release = new RegExp(`^${escapeRegExp(PLAN_VOCABULARY[language].releaseMarker)}(?:\\s|$)`, 'i')
-  return cell
+const releasePattern = (language: PlanLanguage): RegExp =>
+  new RegExp(`^${escapeRegExp(PLAN_VOCABULARY[language].releaseMarker)}(?:\\s|$)`, 'i')
+
+const markerEntries = (cell: string): string[] =>
+  cell
     .split(';')
     .map((entry) => entry.replace(TRAILING_NOTE, '').trim())
-    .filter((entry) => !NO_VALUE.test(entry) && !release.test(entry))
+    .filter((entry) => !NO_VALUE.test(entry))
+
+/** A package as releases compare it: without its scope, in lower case (`@x/UI` and `packages/ui` are both `ui`). */
+const packageKey = (name: string): string => name.replace(PACKAGE_SCOPE, '').toLowerCase()
+
+/** The package a release entry names: the words after the release word that are no version (`Release @x/ui 2.0` is `ui`). */
+const releasedPackageOf = (entry: string): string[] => {
+  const name = entry
+    .split(/\s+/)
+    .slice(1)
+    .filter((word) => !VERSION.test(word))
+    .join(' ')
+  return name ? [packageKey(name)] : []
 }
 
+/**
+ * The marker cell split once into its entries at `;`, each without a trailing note in parentheses: the release
+ * entries (the release word followed by a space or the end, in any case; `Release-Pipeline` is a marker of its own)
+ * give the packages they name, a release entry with a version alone (`Release 1.7.0`) none; every other entry is a
+ * serial marker.
+ */
+const markerCellOf = (cell: string, language: PlanLanguage): Pick<PhaseDependency, 'serialMarkers' | 'releases'> => {
+  const release = releasePattern(language)
+  const entries = markerEntries(cell)
+  return {
+    serialMarkers: entries.filter((entry) => !release.test(entry)),
+    releases: entries.filter((entry) => release.test(entry)).flatMap(releasedPackageOf),
+  }
+}
+
+/** The packages whose release files a write set touches, by the last segment of their directory (`.` for the root). */
+const releasedByFiles = (writes: readonly string[]): string[] =>
+  writes.flatMap((path) => {
+    if (!RELEASE_FILE.test(path)) return []
+    const directory = path.split('/').slice(0, -1)
+    return [packageKey(directory.at(-1) ?? '.')]
+  })
+
 /**
  * The rows of the plan's dependency table (`### Abhängigkeiten und Parallelisierung`); null when the plan has no
  * such table or the table lacks one of its three columns, so a plan that never had one is not asked for rows.
@@ -140,7 +183,7 @@ export const parseDependencyTable = (markdown: string, language: PlanLanguage):
         id,
         ...dependsOf(cells[after] ?? '', language),
         ...writesOf(cells[writes] ?? '', language),
-        serialMarkers: markersOf(cells[marker] ?? '', language),
+        ...markerCellOf(cells[marker] ?? '', language),
       },
     ]
   })
@@ -154,6 +197,9 @@ export const phasesWithoutDependencyRow = (markdown: string, language: PlanLangu
   return phaseHeadings(markdown, language).filter(({ id }) => !listed.has(id))
 }
 
+const longestChain = (chains: readonly string[][]): string[] =>
+  chains.reduce<string[]>((longest, chain) => (chain.length > longest.length ? chain : longest), [])
+
 const mergeSets = (sets: readonly (string[] | null)[]): string[] | null =>
   sets.some((set) => set === null) ? null : sets.flatMap((set) => set ?? [])
 
@@ -172,30 +218,26 @@ const writeSetOf = (
 const overlaps = (left: string, right: string): boolean =>
   left === '' || right === '' || left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)
 
-const sharesMarker = (first: Candidate, second: Candidate): boolean => {
-  const markers = new Set(second.serialMarkers.map((marker) => marker.trim().toLowerCase()))
-  return first.serialMarkers.some((marker) => markers.has(marker.trim().toLowerCase()))
+const sharesEntry = (first: readonly string[], second: readonly string[]): boolean => {
+  const entries = new Set(second.map((entry) => entry.trim().toLowerCase()))
+  return first.some((entry) => entries.has(entry.trim().toLowerCase()))
 }
 
+/** A shared serial marker, or a release of the same package: two releases of one package never run side by side. */
+const sharesMarker = (first: Candidate, second: Candidate): boolean =>
+  sharesEntry(first.serialMarkers, second.serialMarkers) || sharesEntry(first.releases, second.releases)
+
 const collides = (first: Candidate, second: Candidate): boolean =>
   sharesMarker(first, second) || first.writes.some((path) => second.writes.some((other) => overlaps(path, other)))
 
 const candidateOf = (row: PhaseDependency, byId: ReadonlyMap<string, PhaseDependency>): Candidate[] => {
   const writes = writeSetOf(row, byId, [])
-  return writes === null || writes.length === 0 ? [] : [{ id: row.id, writes, serialMarkers: row.serialMarkers }]
+  if (writes === null || writes.length === 0) return []
+  const releases = [...new Set([...row.releases, ...releasedByFiles(writes)])]
+  return [{ id: row.id, writes, serialMarkers: row.serialMarkers, releases }]
 }
 
-/**
- * The phases that can run side by side, as groups in table order: the first group can start now, a later one holds
- * the ready phases that collide with an earlier group's members. A phase is offered when it is not in `doneIds`,
- * every phase in its `Depends on` cell is, and the cell names no external gate: nothing in the plan says such a gate
- * holds, so the phase stays out and the caller asks. Two phases share a group only when no path of one lies at or
- * below a path of the other (a root path lies below nothing and above everything) and they share no serial marker,
- * compared without case (a release marker does not count). A `wie N` writes cell takes the set of phase N; a phase
- * whose set is empty, whose `wie` target is unknown, or whose `wie` chain is a cycle, cannot be shown disjoint and
- * stays out. Whether two phases collide in content, or in the release files, is not decided here.
- */
-export const parallelGroups = (rows: readonly PhaseDependency[], doneIds: ReadonlySet<string>): string[][] => {
+const candidateGroups = (rows: readonly PhaseDependency[], doneIds: ReadonlySet<string>): Candidate[][] => {
   const byId = new Map(rows.map((row) => [row.id, row]))
   const ready = rows
     .filter((row) => !doneIds.has(row.id) && row.external.length === 0 && row.after.every((id) => doneIds.has(id)))
@@ -206,22 +248,92 @@ export const parallelGroups = (rows: readonly PhaseDependency[], doneIds: Readon
     if (group) group.push(candidate)
     else groups.push([candidate])
   }
-  return groups.map((group) => group.map(({ id }) => id))
+  return groups
+}
+
+/**
+ * The phases that can run side by side, as groups in table order: the first group can start now, a later one holds
+ * the ready phases that collide with an earlier group's members. A phase is offered when it is not in `doneIds`,
+ * every phase in its `Depends on` cell is, and the cell names no external gate: nothing in the plan says such a gate
+ * holds, so the phase stays out and the caller asks. Two phases share a group only when no path of one lies at or
+ * below a path of the other (a root path lies below nothing and above everything) and they share no serial marker,
+ * compared without case, and release no package the other releases: a release marker naming it (`Release jackherd
+ * 1.8.0`) or a write of its release files (`CHANGELOG.md`, `package.json` in its directory), the package compared by
+ * its name without scope and the last segment of its directory. A release marker without a name keeps nobody apart.
+ * A `wie N` writes cell takes the set of phase N; a phase whose set is empty, whose `wie` target is unknown, or whose
+ * `wie` chain is a cycle, cannot be shown disjoint and stays out. Whether two phases collide in content is not decided here.
+ */
+export const parallelGroups = (rows: readonly PhaseDependency[], doneIds: ReadonlySet<string>): string[][] =>
+  candidateGroups(rows, doneIds).map((group) => group.map(({ id }) => id))
+
+/**
+ * The whole sequence of parallel groups, computed ahead: the first wave is the first group of `parallelGroups`, each
+ * later wave the first group once the waves before it are done. A phase `parallelGroups` never offers (an external
+ * gate, an empty or unresolvable writes set) is in no wave, and neither is a phase waiting for it.
+ */
+export const phaseWaves = (rows: readonly PhaseDependency[], doneIds: ReadonlySet<string>): string[][] => {
+  const waves: string[][] = []
+  const done = new Set(doneIds)
+  let wave = parallelGroups(rows, done)[0]
+  while (wave) {
+    waves.push(wave)
+    for (const id of wave) done.add(id)
+    wave = parallelGroups(rows, done)[0]
+  }
+  return waves
+}
+
+/**
+ * The longest chain of open phases in `waves`, counted in phases: a phase follows another that it depends on, or one
+ * of an earlier wave it shares a serial marker or a package release with. A shared path alone does not chain, so a
+ * plan with more waves than its critical path is long loses the difference to overlapping writes. The first longest
+ * chain in wave order; empty without waves.
+ */
+export const criticalPath = (rows: readonly PhaseDependency[], waves: readonly string[][]): string[] => {
+  const byId = new Map(rows.map((row) => [row.id, row]))
+  const candidates = new Map(rows.flatMap((row) => candidateOf(row, byId)).map((each) => [each.id, each]))
+  const chains = new Map<string, string[]>()
+  const follows = (later: string, earlier: string): boolean => {
+    const [first, second] = [candidates.get(earlier), candidates.get(later)]
+    const chained = first !== undefined && second !== undefined && sharesMarker(first, second)
+    return chained || (byId.get(later)?.after.includes(earlier) ?? false)
+  }
+  waves.forEach((wave, index) => {
+    const earlier = waves.slice(0, index).flat()
+    for (const id of wave) {
+      const before = longestChain(earlier.filter((other) => follows(id, other)).map((other) => chains.get(other) ?? []))
+      chains.set(id, [...before, id])
+    }
+  })
+  return longestChain([...chains.values()])
 }
 
 /** The phases as a report names them, side by side: `P19 ∥ P20`. */
-export const phasesText = (phases: readonly string[]): string =>
-  phases.map((id) => `${PHASE_ID_PREFIX}${id}`).join(' ∥ ')
+export const phasesText = (phases: readonly string[]): string => phaseLabels(phases, ' ∥ ')
 
 const donePhaseIds = (markdown: string, language: PlanLanguage): Set<string> =>
   new Set(
     parsePlanPhases(markdown, language)
-      .filter(({ items }) => items.length > 0 && items.every((item) => item.done))
+      .filter(isPhaseFinished)
       .map(({ id }) => id),
   )
 
-/** `parallelGroups` of the plan's own dependency table and ticks (a phase is done when every box is ticked); null for a plan without a table. */
+/** `parallelGroups` of the plan's own dependency table and ticks (a phase is done once `isPhaseFinished`); null for a plan without a table. */
 export const parallelGroupsOfPlan = (markdown: string, language: PlanLanguage): string[][] | null => {
   const table = parseDependencyTable(markdown, language)
   return table === null ? null : parallelGroups(table, donePhaseIds(markdown, language))
 }
+
+/** The waves, the critical path and the open phases in no wave, of the plan's own table and ticks; null for a plan without a table. */
+export const wavesOfPlan = (markdown: string, language: PlanLanguage): PhaseSchedule | null => {
+  const table = parseDependencyTable(markdown, language)
+  if (table === null) return null
+  const done = donePhaseIds(markdown, language)
+  const waves = phaseWaves(table, done)
+  const placed = new Set(waves.flat())
+  return {
+    waves,
+    criticalPath: criticalPath(table, waves),
+    unplaced: table.filter(({ id }) => !done.has(id) && !placed.has(id)).map(({ id }) => id),
+  }
+}

package/src/plan-format/index.ts

@@ -1,13 +1,17 @@
 export * from '../vocabulary'
 export * from './board-prose'
 export {
+  criticalPath,
   type PhaseDependency,
+  type PhaseSchedule,
   type PhaseWithoutRow,
   parallelGroups,
   parallelGroupsOfPlan,
   parseDependencyTable,
   phasesText,
   phasesWithoutDependencyRow,
+  phaseWaves,
+  wavesOfPlan,
 } from './dependencies'
 export * from './documentation-gate'
 export * from './drift'
@@ -18,6 +22,8 @@ export {
   type PlanStep,
   parseSprintLanes,
   phaseIdsOfCell,
+  phaseLabel,
+  phaseLabels,
   resolvePlanPath,
   type SprintLane,
   sprintTitleOf,

package/src/plan-format/lanes.ts

@@ -29,6 +29,12 @@ const PLAN_LINK = /\[([^\]]+)\]\(([^)]+)\)/
 /** Sprint tables name a phase `P4`; the sidebar title prints it the same way. */
 export const PHASE_ID_PREFIX = 'P'
 
+/** A phase as plans and reports name it: `P4`. */
+export const phaseLabel = (id: string): string => `${PHASE_ID_PREFIX}${id}`
+
+/** Phases as plans and reports name them, joined by `separator`: `P3 P4`, `P19 ∥ P20`. */
+export const phaseLabels = (ids: readonly string[], separator: string): string => ids.map(phaseLabel).join(separator)
+
 const PHASES_COLUMN = 3
 const CLAUSE_SEPARATOR = /([;,]|\.(?=\s))\s*/
 const ENTRY_END = new Set([';', '.'])

package/src/plan-format/progress.ts

@@ -1,4 +1,4 @@
-import { PHASE_ID_PREFIX, type PlanStep, type SprintLane } from './lanes'
+import { type PlanStep, phaseLabel, type SprintLane } from './lanes'
 import type { ChecklistItem, DeferredItem, PlanPhase } from './phases'
 
 /**
@@ -37,7 +37,8 @@ export const sumPhases = (phases: readonly PhaseProgress[]): { done: number; tot
 const phaseById = <T extends { id: string }>(phases: readonly T[], id: string): T | undefined =>
   phases.find((phase) => phase.id === id)
 
-const phaseProgress = (phases: PlanPhase[], id: string): PhaseProgress => {
+/** The progress of the phase `id` of a plan; a phase the plan lacks has a null title and no checkboxes. */
+export const phaseProgress = (phases: readonly PlanPhase[], id: string): PhaseProgress => {
   const phase = phaseById(phases, id)
   const items = phase?.items ?? []
   return {
@@ -51,7 +52,17 @@ const phaseProgress = (phases: PlanPhase[], id: string): PhaseProgress => {
   }
 }
 
-const isOpen = ({ done, total }: PhaseProgress): boolean => done < total
+/**
+ * A phase is finished once every checkbox it has is ticked, its tasks and its review gate alike: `/implement` and
+ * `jh check --parallel` read it so, and an open documentation box keeps the phase open. A phase without a checkbox is
+ * never finished.
+ */
+export const isPhaseFinished = ({ items }: Pick<PlanPhase, 'items'>): boolean =>
+  items.length > 0 && items.every(({ done }) => done)
+
+/** A phase with a checkbox that is not finished; a phase without a checkbox is neither. */
+export const isPhaseOpen = (phase: Pick<PlanPhase, 'items'>): boolean =>
+  phase.items.length > 0 && !isPhaseFinished(phase)
 
 /** A phase the plan has written: one with at least one checkbox, not one missing from the plan or without any. */
 const isWritten = ({ total }: PhaseProgress): boolean => total > 0
@@ -68,7 +79,7 @@ const isTouched = (phase: PhaseProgress): boolean => phase.touched === true && i
  * A phase the lane ticked to the end in its worktree while the base branch does not carry those ticks yet: still
  * the lane's work until it is merged, not a finished phase.
  */
-export const isTickedUnmerged = (phase: PhaseProgress): boolean => isTouched(phase) && !isOpen(phase)
+export const isTickedUnmerged = (phase: PhaseProgress): boolean => isTouched(phase) && isPhaseFinished(phase)
 
 /** The first phase `pick` finds in a step, from the newest step back. */
 const newestStepWith = (
@@ -112,7 +123,7 @@ const rowPhases = (steps: readonly StepProgress[], stepIndex: number): LocatedPh
 }
 
 const touchedOpenPhaseOf = (phases: readonly PhaseProgress[]): PhaseProgress | undefined =>
-  phases.find((phase) => isTouched(phase) && isOpen(phase))
+  phases.find((phase) => isTouched(phase) && isPhaseOpen(phase))
 
 const lastTickedUnmergedOf = (phases: readonly PhaseProgress[]): PhaseProgress | undefined =>
   phases.filter(isTickedUnmerged).at(-1)
@@ -126,7 +137,7 @@ const lastTickedUnmergedOf = (phases: readonly PhaseProgress[]): PhaseProgress |
 const newestRowPhase = (steps: readonly StepProgress[]): LaneProgress['current'] => {
   const located = rowPhases(steps, newestRowIndex(steps)).filter(({ phase }) => isWritten(phase))
   const phases = located.map(({ phase }) => phase)
-  const phase = touchedOpenPhaseOf(phases) ?? lastTickedUnmergedOf(phases) ?? phases.find(isOpen)
+  const phase = touchedOpenPhaseOf(phases) ?? lastTickedUnmergedOf(phases) ?? phases.find(isPhaseOpen)
   return located.find((entry) => entry.phase === phase)?.current ?? null
 }
 
@@ -141,7 +152,7 @@ const phaseFromTicks = (steps: readonly StepProgress[]): LaneProgress['current']
   const touched = newestStepWith(steps, touchedOpenPhaseOf) ?? newestStepWith(steps, lastTickedUnmergedOf)
   if (touched) return touched
   const lastIndex = newestWrittenStepIndex(steps)
-  const phase = steps[lastIndex]?.phases.find(isOpen)
+  const phase = steps[lastIndex]?.phases.find(isPhaseOpen)
   return phase ? { stepIndex: lastIndex, phaseId: phase.id } : null
 }
 
@@ -175,6 +186,6 @@ export const activeItem = (phase: Pick<PhaseProgress, 'items'>): ChecklistItem |
 /** The sidebar title of a lane, e.g. `P4 · 7/12` or `P4 · 12/12` while ticked and not merged; null when nothing of the lane could be counted. */
 export const shortTitle = (progress: LaneProgress): string | null => {
   const phase = currentPhase(progress)
-  if (phase) return `${PHASE_ID_PREFIX}${phase.id} · ${phase.done}/${phase.total}`
+  if (phase) return `${phaseLabel(phase.id)} · ${phase.done}/${phase.total}`
   return progress.total > 0 ? `✓ ${progress.done}/${progress.total}` : null
 }

package/src/plans/command.ts

@@ -6,26 +6,35 @@ import { boardFor, foundLanesOf } from './board-pick'
 import { ensurePlanPanes } from './ensure-panes'
 import { mainCheckout, worktreeRoot } from './git'
 import { fetchPullRequests } from './github'
+import { recallLanes, rememberLanes } from './herd-memory'
 import { runLive } from './live'
 import { parseOptions } from './options'
 import { isSupervisedChild } from './restart-decision'
-import { clockLocaleOf, readSettings } from './settings'
+import { CLOCK_LOCALE, readSettings } from './settings'
 import { loadSnapshot, type Source } from './snapshot'
 import { superviseView } from './supervisor'
 import { frameText, paneWidth, renderSnapshot, startSelection } from './view'
 
 const printOnce = async (source: Source): Promise<void> => {
-  const snapshot = await loadSnapshot(source, await fetchPullRequests(source.root))
+  const memories = recallLanes(source.root)
+  const snapshot = await loadSnapshot(source, await fetchPullRequests(source.root), memories)
+  rememberLanes(source.root, memories, snapshot.documents.laneOrder)
   const screen = renderSnapshot(
     snapshot,
     startSelection(snapshot, source.options),
     snapshot.errors,
     paneWidth(),
-    clockLocaleOf(source.settings),
+    CLOCK_LOCALE,
   )
   console.log(frameText(screen, Boolean(process.stdout.isTTY)))
 }
 
+/** One print, with why this board was chosen once on stderr: never in the frame (the watcher's `armed:` keeps it). */
+const printOnceWithNotice = async (source: Source, notice: string | null): Promise<void> => {
+  if (notice) console.error(notice)
+  await printOnce(source)
+}
+
 /**
  * `jh herd [<board.md>] [--lane <name>] [--once | --ensure]`: a live view of a board's lanes and their plan
  * progress; `--ensure` instead brings back the missing herd panes beside the coordinator and each lane.
@@ -48,8 +57,8 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
       for (const line of lines.length > 0 ? lines : ['every herd pane is running']) console.log(line)
       return 0
     }
-    const source = { root, sprintFile: picked.file, options, settings, terminal, boardNotice: picked.notice }
-    if (options.once || !process.stdout.isTTY) await printOnce(source)
+    const source = { root, sprintFile: picked.file, options, settings, terminal }
+    if (options.once || !process.stdout.isTTY) await printOnceWithNotice(source, picked.notice)
     else if (isSupervisedChild(process.env)) runLive(source)
     else return await superviseView(args, await startedKit())
     return 0

package/src/plans/current-phase.ts

@@ -6,34 +6,90 @@ export type PhaseRef = { planHref: string; phaseId: string }
 /** Per plan link and phase id, the state of its checkboxes as `1` (ticked) and `0` (open) in plan order. */
 export type TickSnapshot = Record<string, Record<string, string>>
 
+/** When a phase's ticks or task lines last moved, in milliseconds, by `activityKey`. */
+export type ActivityTimes = Readonly<Record<string, number>>
+
 /**
- * What the herd remembers of a lane between two reads: the ticks it saw, the phase whose ticks moved last and the
- * identity of the newest board row (`newestRowIdentity`), which a new row changes.
+ * What the herd remembers of a lane between two reads: the ticks it saw, the phase whose ticks moved last, the
+ * identity of the newest board row (`newestRowIdentity`), which a new row changes, and when each phase last moved.
  */
-export type LaneMemory = { ticks: TickSnapshot; moved: PhaseRef | null; row: string }
+export type LaneMemory = { ticks: TickSnapshot; moved: PhaseRef | null; row: string; activity?: ActivityTimes }
+
+/** The key of a phase in `ActivityTimes`. */
+export const activityKey = (planHref: string, phaseId: string): string => `${planHref}#${phaseId}`
+
+/** Marks a tick string of the tasks alone; one remembered before, with the review gate in it, has no mark. */
+const TASK_TICKS = 't:'
 
+/**
+ * The ticks of each phase's tasks outside the review gate (D67): ticking the gate is bookkeeping, not work on the
+ * phase, so it moves nothing in the herd.
+ */
 export const tickSnapshotOf = (plans: PlansByHref): TickSnapshot =>
   Object.fromEntries(
     Object.entries(plans).map(([href, phases]) => [
       href,
       Object.fromEntries(
-        phases.map((phase) => [phase.id, phase.items.map((item) => (item.done ? '1' : '0')).join('')]),
+        phases.map((phase) => [
+          phase.id,
+          `${TASK_TICKS}${phase.items
+            .filter((item) => !item.gate)
+            .map((item) => (item.done ? '1' : '0'))
+            .join('')}`,
+        ]),
       ),
     ]),
   )
 
 /**
- * The phases both reads have whose ticks differ, in plan order; a plan or phase new in `next` has no state to move
- * from. A task added to or removed from a phase changes its tick string and counts as movement.
+ * The phases both reads have whose ticks differ, in plan order; a plan or phase new in `next`, or one remembered in
+ * the format before D67, has no state to move from. A task added to or removed from a phase changes its tick string
+ * and counts as movement.
  */
 export const movedPhases = (previous: TickSnapshot, next: TickSnapshot): PhaseRef[] =>
   Object.entries(next).flatMap(([planHref, phases]) =>
     Object.entries(phases).flatMap(([phaseId, ticks]) => {
       const before = previous[planHref]?.[phaseId]
-      return before !== undefined && before !== ticks ? [{ planHref, phaseId }] : []
+      return before?.startsWith(TASK_TICKS) && before !== ticks ? [{ planHref, phaseId }] : []
     }),
   )
 
+/** The phases `next` has in a plan `previous` read already but without them: task lines a lane wrote into a new phase. */
+const addedPhases = (previous: TickSnapshot, next: TickSnapshot): PhaseRef[] =>
+  Object.entries(next).flatMap(([planHref, phases]) => {
+    const before = previous[planHref]
+    if (before === undefined) return []
+    return Object.keys(phases).flatMap((phaseId) => (phaseId in before ? [] : [{ planHref, phaseId }]))
+  })
+
+/** When each plan file was last written, in milliseconds, by plan link; a plan without an entry is bounded by the clock. */
+export type PlanModified = Readonly<Record<string, number>>
+
+/**
+ * When each phase last moved, after a read at `now` whose ticks are `ticks`: a phase whose ticks or task lines changed
+ * since `previous`, or that is new in a plan `previous` read already, takes the time its plan file was last written
+ * (`modified`), bounded by `now`, so a change first seen long after it was made is not taken for a fresh one; the
+ * others keep their time. The first read knows no movement, so without a remembered read no phase has a time.
+ */
+export const nextActivity = (
+  previous: LaneMemory | undefined,
+  ticks: TickSnapshot,
+  now: number,
+  modified: PlanModified = {},
+): ActivityTimes => {
+  if (!previous) return {}
+  const changed = [...movedPhases(previous.ticks, ticks), ...addedPhases(previous.ticks, ticks)]
+  return {
+    ...previous.activity,
+    ...Object.fromEntries(
+      changed.map(({ planHref, phaseId }) => [
+        activityKey(planHref, phaseId),
+        Math.min(now, modified[planHref] ?? now),
+      ]),
+    ),
+  }
+}
+
 /** The newest board row of a lane as its step index and the phase ids it shows, a step `withWorkedPhases` added not counted. */
 export const newestRowIdentity = ({ steps }: LaneProgress): string => {
   const index = steps.reduce((last, { step }, stepIndex) => (step.withoutRow ? last : stepIndex), -1)

package/src/plans/current-task.ts

@@ -0,0 +1,51 @@
+import type { PlanPhase } from '../plan-format'
+
+/**
+ * A hint that a phase's task is being worked on: `taskIndex` is the task's index in the phase's checkboxes, `at` when
+ * it was seen, in milliseconds. No source writes one yet, so the heuristic of `currentTasks` decides alone.
+ */
+export type TaskSignal = { phaseId: string; taskIndex: number; at: number }
+
+/** A phase as `currentTasks` reads it: its id and checkboxes. */
+export type TaskPhase = Pick<PlanPhase, 'id' | 'items'>
+
+const isOpenTask = (phase: TaskPhase, index: number): boolean => phase.items[index]?.done === false
+
+/** The task the newest signal younger than `staleAfterMs` points at, when it is still open; null otherwise. */
+const signalledTask = (
+  phase: TaskPhase,
+  signals: readonly TaskSignal[],
+  now: number,
+  staleAfterMs: number,
+): number | null => {
+  const fresh = signals
+    .filter((signal) => signal.phaseId === phase.id && now - signal.at < staleAfterMs)
+    .filter((signal) => isOpenTask(phase, signal.taskIndex))
+  const newest = fresh.reduce<TaskSignal | null>((last, signal) => (last && last.at >= signal.at ? last : signal), null)
+  return newest?.taskIndex ?? null
+}
+
+/** The first open task outside the review gate; with only gate boxes open, the first of them; -1 when none is open. */
+const firstOpenTask = ({ items }: TaskPhase): number => {
+  const outsideGate = items.findIndex((item) => !item.done && !item.gate)
+  return outsideGate === -1 ? items.findIndex((item) => !item.done) : outsideGate
+}
+
+/**
+ * The task each phase is on, by phase id, as its index in the phase's checkboxes: the open task a fresh signal names
+ * (the newest), else the first open task outside the review gate, else the first open gate box. A phase without an
+ * open task is absent. Derived only, never written into the plan.
+ */
+export const currentTasks = (
+  plan: readonly TaskPhase[],
+  signals: readonly TaskSignal[],
+  now: number,
+  staleAfterMs: number,
+): ReadonlyMap<string, number> =>
+  new Map(
+    plan.flatMap((phase) => {
+      const first = firstOpenTask(phase)
+      if (first === -1) return []
+      return [[phase.id, signalledTask(phase, signals, now, staleAfterMs) ?? first] as const]
+    }),
+  )

package/src/plans/ensure-panes.ts

@@ -1,11 +1,12 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { basename, join } from 'node:path'
-import { defaultCoordinatorName } from '../context/coordinator-name'
+import { resolveCoordinatorName } from '../context/coordinator-name'
 import { parseSprintLanes } from '../plan-format'
-import { parseAgentList, runHerdr } from '../terminal/herdr'
+import { parseAgentList, renameArguments, runHerdr } from '../terminal/herdr'
 import { errorText } from './error-text'
 import {
   agentPanesOf,
+  coordinatorLabelOf,
   coordinatorPaneOf,
   foregroundOf,
   missingCoordinatorNote,
@@ -46,21 +47,37 @@ const apply = (action: PaneAction): string => {
   }
 }
 
+/** Labels the coordinator's pane; the label is decoration, so a failure is dropped. */
+const labelCoordinator = (label: { pane: string; label: string } | null) => {
+  if (!label) return
+  try {
+    runHerdr(renameArguments(label.pane, label.label))
+  } catch {
+    // A pane herdr cannot rename keeps its old label; the views are what counts here.
+  }
+}
+
 /**
  * `herd --ensure`: brings back every missing herd pane beside the coordinator and each lane of the board, and
  * leaves running ones alone, so it can run after every start. A lane gets its view once its agent runs. One line per
- * action or skipped target, none when every view runs.
+ * action or skipped target, none when every view runs. The coordinator's pane is labelled `🐾 Jack` on the way.
  */
 export const ensurePlanPanes = (root: string, settings: PlansSettings, boardFile: string): string[] => {
   const agents = runHerdr(['agent', 'list'])
+  const listed = parseAgentList(agents)
   const panes = panesWithForeground(agentPanesOf(agents))
-  const coordinatorName = defaultCoordinatorName(basename(root))
+  const coordinatorName = resolveCoordinatorName(
+    basename(root),
+    listed.map((agent) => agent.name),
+  )
+  const coordinator = coordinatorPaneOf(panes, root, {
+    named: listed.find((agent) => agent.name === coordinatorName)?.pane ?? null,
+    caller: process.env.HERDR_PANE_ID ?? null,
+  })
+  labelCoordinator(coordinatorLabelOf(panes, coordinator))
   const { actions, notes } = planPaneActions({
     panes,
-    coordinator: coordinatorPaneOf(panes, root, {
-      named: parseAgentList(agents).find((agent) => agent.name === coordinatorName)?.pane ?? null,
-      caller: process.env.HERDR_PANE_ID ?? null,
-    }),
+    coordinator,
     lanes: lanesOf(root, settings, boardFile),
     root,
     worktrees: join(root, settings.worktreeDirectory),