jackherd 1.9.0 → 1.11.0

package/src/plans/lane-plans.ts

@@ -1,8 +1,10 @@
 import { existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { type PlansByHref, parsePlanPhases, resolvePlanPath, type SprintLane } from '../plan-format'
+import { type PlanPhase, type PlansByHref, resolvePlanPath, type SprintLane } from '../plan-format'
 import type { BaseReader } from './git'
-import { hasOwnWork, mergePlanPhases } from './phase-source'
+import { hasOwnWork, mergePlanPhases, newerPhases } from './phase-source'
+import { type PlanRound, parsedPlanPhases } from './plan-cache'
+import type { PlanHead } from './plan-heads'
 import type { PlansSettings } from './settings'
 
 /** Paths that could not be read at the base ref and were read from a checkout instead. */
@@ -10,8 +12,20 @@ export type Fallbacks = string[]
 
 export type LaneWork = { worktree: string | null; ahead: number | null; dirty: number }
 
+/** Parses a plan's text, kept under `key` in the round's cache. */
+type ParsePlan = (markdown: string, key: string) => PlanPhase[]
+
 /** What reading a lane's plans needs: the main checkout, the settings, the base ref's reader, the board's directory. */
-export type PlanSources = { root: string; settings: PlansSettings; base: BaseReader; sprintDirectory: string }
+export type PlanSources = {
+  root: string
+  settings: PlansSettings
+  base: BaseReader
+  sprintDirectory: string
+  /** The heads of the open pull requests that change a plan, besides the lane's own; a phase they ticked further counts. */
+  heads: readonly PlanHead[]
+  /** Kept between reads, so a plan whose text did not change is not parsed again; `used` collects the keys of one round. */
+  parsed?: PlanRound
+}
 
 const isOutsideRepository = (path: string): boolean => path.startsWith('..')
 
@@ -49,10 +63,30 @@ export const laneWorkOf = (worktree: string, status: { ahead: number | null; dir
 })
 
 /**
- * The plans of a lane. The base ref is the truth; while the lane has work of its own in its worktree, the phases
- * its rows name, and those new there or ticked further, come from the worktree (`mergePlanPhases`). A plan the base ref lacks is read from the lane's worktree, else from the main
- * checkout (a repository that ignores `docs/` keeps plan and board only there). `files` are the plan files to
- * watch for changes, `modified` when each was last written, by plan link (`nextActivity` bounds a movement by it).
+ * The base's phases with each phase an open pull request ticked further taken from that pull request's head, in
+ * the heads' order. A head whose ref was not fetched reads nothing and changes nothing; its phases are never the
+ * lane's work, so none is marked `touched`.
+ */
+const withPullRequestHeads = (
+  base: PlanPhase[],
+  heads: readonly PlanHead[],
+  path: string,
+  parse: ParsePlan,
+): PlanPhase[] =>
+  heads
+    .filter((head) => head.files.includes(path))
+    .reduce((phases, head) => {
+      const headText = head.read(path)
+      return headText === null ? phases : newerPhases(phases, parse(headText, `${path}\0pr${head.number}`))
+    }, base)
+
+/**
+ * The plans of a lane. The base ref is the truth, raised by the heads of open pull requests that ticked a phase
+ * further (`withPullRequestHeads`); while the lane has work of its own in its worktree, the phases its rows name,
+ * and those new there or ticked further, come from the worktree (`mergePlanPhases`). A plan the base ref lacks is
+ * read from the lane's worktree, else from the main checkout (a repository that ignores `docs/` keeps plan and
+ * board only there). `files` are the plan files to watch for changes, `modified` when each was last written, by
+ * plan link (`nextActivity` bounds a movement by it).
  */
 export const readPlans = async (lane: SprintLane, sources: PlanSources, work: LaneWork, fallbacks: Fallbacks) => {
   const { root, settings, sprintDirectory } = sources
@@ -68,12 +102,9 @@ export const readPlans = async (lane: SprintLane, sources: PlanSources, work: La
     if (text === null) continue
     const own = worktreeFile === file && hasOwnWork(work) ? await Bun.file(file).text() : null
     const laneIds = lane.steps.filter((step) => step.planHref === href).flatMap((step) => step.phaseIds)
-    plans[href] = mergePlanPhases(
-      parsePlanPhases(text, settings.planLanguage),
-      own === null ? null : parsePlanPhases(own, settings.planLanguage),
-      laneIds,
-      work,
-    )
+    const parse: ParsePlan = (markdown, key) => parsedPlanPhases(sources.parsed, key, markdown, settings.planLanguage)
+    const base = withPullRequestHeads(parse(text, path), sources.heads, path, parse)
+    plans[href] = mergePlanPhases(base, own === null ? null : parse(own, `${file}\0own`), laneIds, work)
     files.push(file)
     texts[href] = text
     if (existsSync(file)) modified[href] = statSync(file).mtimeMs

package/src/plans/lane-summary.ts

@@ -1,17 +1,27 @@
 import {
   isPhaseFinished,
   isPhaseOpen,
-  isTickedUnmerged,
   type LaneProgress,
   type PhaseProgress,
   type PlanPhase,
   type PlansByHref,
   phaseProgress,
 } from '../plan-format'
+import { MS_PER_MINUTE } from '../plan-format/clock'
 import type { TaskSignal } from '../task-signals/types'
 import { type ActiveTask, assignSignals, freshSignals, type UnplannedTask } from './active-tasks'
 import { type ActivityTimes, activityKey } from './current-phase'
 import { currentTasks, type TaskActivity } from './current-task'
+import { isNamedBy } from './phase-ids'
+import { signalledPhase } from './signalled-phase'
+import {
+  type PhaselessReview,
+  type ReviewType,
+  type SubagentPhase,
+  type SubagentPhaseRun,
+  subagentPhases,
+} from './subagent-phases'
+import { type DescribedSubagent, subagentTaskPlacements } from './subagent-tasks'
 
 /**
  * A phase the lane works on now: an open one ticked less than `STALE_ACTIVITY_MINUTES` ago, one an agent reports, or
@@ -29,10 +39,13 @@ export type ActivePhase = {
   tasks: ActiveTask[]
 }
 
+/** A phase with the step that shows it (null for none), which keys its row (`phaseKey`). */
+export type PlacedPhase = { phase: PhaseProgress; stepIndex: number | null }
+
 /** Open phases that do not run, by number; `planTitle` is null for the lane's current plan, the board's title for another. */
 export type WaitingPhases = { planTitle: string | null; phaseIds: string[] }
 
-export type FinishedPhase = { id: string; unmerged: boolean }
+export type FinishedPhase = { id: string }
 
 /** A phase the lane's board rows name that has nothing to run: `missing` when the plan lacks it, else it has no checkbox. */
 export type UnwrittenPhase = { id: string; missing: boolean }
@@ -46,13 +59,21 @@ export type LaneSummary = {
   active: ActivePhase[]
   /** The open phase of the current plan moved last, at any age; null while none has a time. */
   latest: PhaseProgress | null
+  /** The open phase the lane's newest report or its branch names (`signalledPhase`); it runs and the lane line names it. */
+  signalled: PhaseProgress | null
   /** The open phases of the current plan that do not run, then the open phases of the lane's other plans. */
   waiting: WaitingPhases[]
+  /** The phases behind `waiting`, in its order, for the rows `next` opens to. */
+  waitingPhases: PlacedPhase[]
   finished: FinishedPhase[]
+  /** The phases behind `finished`, for the rows `✓` opens to. */
+  finishedPhases: PlacedPhase[]
   unwritten: UnwrittenPhase[]
   tally: PlanTally
   /** What agents report doing that no open task of the plan names. */
   unplanned: UnplannedTask[]
+  /** What the running subagents without a phase in their description work on, as they described it. */
+  subagentTasks: string[]
 }
 
 /**
@@ -67,13 +88,21 @@ export type SummaryInput = {
   guesses?: readonly TaskActivity[]
   /** What the lane's agents report doing (task lists, `jh task`), matched to open tasks of the current plan. */
   reported?: readonly TaskSignal[]
+  /** The phases the descriptions of the lane's running subagents name; a signal like a report, never a tick. */
+  subagents?: readonly SubagentPhaseRun[]
+  /** The descriptions of the running subagents that name no phase; the folded lane shows them as tasks. */
+  subagentTasks?: readonly string[]
+  /** The running reviews that name no phase; they sit on the `signalled` phase, else show as tasks like `subagentTasks`. */
+  phaselessReviews?: readonly PhaselessReview[]
+  /** The running subagents that are no review; one whose description starts with a task's short name sits on it (`subagentTaskPlacements`). */
+  describedSubagents?: readonly DescribedSubagent[]
+  /** The branch checked out in the lane's worktree; a phase it names (`branchPhaseId`) is current while no report names one. */
+  branch?: string | null
 }
 
 /** Minutes without a tick after which a phase no longer runs, unless an agent reports it. */
 export const STALE_ACTIVITY_MINUTES = 20
 
-const MINUTE = 60_000
-
 const isWritten = ({ total }: PhaseProgress): boolean => total > 0
 
 const planHrefs = ({ steps }: LaneProgress): string[] => [
@@ -92,18 +121,12 @@ const stepPhases = ({ steps }: LaneProgress, href: string): PhaseProgress[] => {
   return shown.filter((phase, index) => shown.findIndex(({ id }) => id === phase.id) === index)
 }
 
-const SUB_PHASE_LETTERS = /[a-z]+$/i
-
 /** The ids the lane's steps on `href` name, a row's repeats and the phases it worked on without a row included. */
 const namedIds = ({ steps }: LaneProgress, href: string): Set<string> =>
   new Set(
     steps.flatMap(({ step }) => (step.planHref === href ? [...step.phaseIds, ...(step.namedPhaseIds ?? [])] : [])),
   )
 
-/** A plan phase the lane names: by its own id, or a sub-phase (`10c`) of a phase it names (`P10`). */
-const isNamed = (id: string, named: ReadonlySet<string>): boolean =>
-  named.has(id) || named.has(id.replace(SUB_PHASE_LETTERS, ''))
-
 /**
  * The phases of `href` the lane names, in plan order: another lane's phases of the same plan are not its own, however
  * lately they moved.
@@ -112,7 +135,7 @@ const phasesOf = (input: SummaryInput, href: string): PhaseProgress[] => {
   const plan: readonly PlanPhase[] | undefined = input.phases[href]
   if (!plan) return stepPhases(input.progress, href)
   const named = namedIds(input.progress, href)
-  return plan.filter(({ id }) => isNamed(id, named)).map(({ id }) => phaseProgress(plan, id))
+  return plan.filter(({ id }) => isNamedBy(id, named)).map(({ id }) => phaseProgress(plan, id))
 }
 
 const newestStepShowing = ({ steps }: LaneProgress, href: string, id: string): number | null => {
@@ -135,56 +158,166 @@ const isStarted = ({ items }: PhaseProgress): boolean => {
   return tasks.some(({ done }) => done) && tasks.some(({ done }) => !done)
 }
 
+const minutesSince = (at: number, now: number): number => Math.max(Math.floor((now - at) / MS_PER_MINUTE), 0)
+
 /** The open phases with a time of their last movement, the one moved last first; a phase without a time is absent. */
 const timedPhases = (input: SummaryInput, href: string, phases: PhaseProgress[], now: number): TimedPhase[] =>
   phases
     .filter(isPhaseOpen)
     .flatMap((phase) => {
       const at = input.activity[activityKey(href, phase.id)]
-      return at === undefined ? [] : [{ phase, minutesAgo: Math.max(Math.floor((now - at) / MINUTE), 0) }]
+      return at === undefined ? [] : [{ phase, minutesAgo: minutesSince(at, now) }]
     })
     .sort((first, second) => first.minutesAgo - second.minutesAgo)
 
 const newest = (times: readonly number[]): number | null => (times.length > 0 ? Math.max(...times) : null)
 
-const minutesSince = (at: number, now: number): number => Math.max(Math.floor((now - at) / MINUTE), 0)
-
 const isListed = (listed: readonly RunningPhase[], phase: PhaseProgress): boolean =>
   listed.some((each) => each.phase.id === phase.id)
 
-/** The open phases a reported task names that are not `listed` yet, aged from the newest report. */
+/** What names a phase as running besides its ticks, by phase id: the tasks agents reported and the subagents at work. */
+type PhaseSignals = {
+  reported: ReadonlyMap<string, ActiveTask[]>
+  subagents: ReadonlyMap<string, SubagentPhase>
+}
+
+/** When the newest report or running subagent of a phase began, in milliseconds; null for none. */
+const reportedAt = (id: string, { reported, subagents }: PhaseSignals): number | null => {
+  const subagent = subagents.get(id)
+  return newest([
+    ...(reported.get(id) ?? []).flatMap((task) => task.startedAt ?? []),
+    ...(subagent === undefined ? [] : [subagent.at]),
+  ])
+}
+
+/** The open phases a reported task or a running subagent names that are not `listed` yet, aged from the newest of them. */
 const reportedPhases = (
   phases: PhaseProgress[],
-  reported: ReadonlyMap<string, ActiveTask[]>,
+  signals: PhaseSignals,
   listed: readonly RunningPhase[],
   now: number,
 ): RunningPhase[] =>
   phases
-    .filter((phase) => isPhaseOpen(phase) && reported.has(phase.id) && !isListed(listed, phase))
+    .filter(
+      (phase) =>
+        isPhaseOpen(phase) &&
+        (signals.reported.has(phase.id) || signals.subagents.has(phase.id)) &&
+        !isListed(listed, phase),
+    )
     .map((phase) => {
-      const startedAt = newest((reported.get(phase.id) ?? []).flatMap((task) => task.startedAt ?? []))
+      const startedAt = reportedAt(phase.id, signals)
       return { phase, minutesAgo: startedAt === null ? 0 : minutesSince(startedAt, now) }
     })
 
+/**
+ * Whether a text names the review type as a word (`/security-audit`, `` `uncle-bob` ``): `review` is not named by
+ * `skill-review` or `Review-Gate`. The types hold no character a pattern reads specially.
+ */
+const namesReview = (text: string, review: ReviewType): boolean =>
+  new RegExp(`(?<![\\w-])${review}(?![\\w-])`).test(text)
+
+/**
+ * The review gate box a running review sits on, which gets its `▶` like a reported task: the open one that names the
+ * review, else the first open one. A phase whose gate is ticked or that has none shows no arrow.
+ */
+const reviewTask = ({ items }: PhaseProgress, review: ReviewType, at: number): ActiveTask[] => {
+  const isOpenGate = (item: PhaseProgress['items'][number]): boolean => item.gate === true && !item.done
+  const named = items.findIndex((item) => isOpenGate(item) && namesReview(item.text, review))
+  const index = named === -1 ? items.findIndex(isOpenGate) : named
+  return index === -1 ? [] : [{ index, agent: null, guessed: false, startedAt: at }]
+}
+
+/** Adds `tasks` to the phase's tasks in `merged`, each task once. */
+const addTasks = (merged: Map<string, ActiveTask[]>, phaseId: string, tasks: readonly ActiveTask[]): void => {
+  const known = merged.get(phaseId) ?? []
+  merged.set(phaseId, [...known, ...tasks.filter(({ index }) => !known.some((task) => task.index === index))])
+}
+
+/** The reported tasks with the gate box each running review of a phase sits on added, unless a report names it already. */
+const withReviewTasks = (
+  reported: ReadonlyMap<string, ActiveTask[]>,
+  phases: PhaseProgress[],
+  subagents: ReadonlyMap<string, SubagentPhase>,
+): Map<string, ActiveTask[]> => {
+  const merged = new Map(reported)
+  for (const phase of phases) {
+    const found = subagents.get(phase.id)
+    if (!found) continue
+    for (const review of found.reviews) addTasks(merged, phase.id, reviewTask(phase, review, found.at))
+  }
+  return merged
+}
+
+/** The reported tasks with the tasks the subagents sit on added (`subagentTaskPlacements`), unless a report names them already. */
+const withTasks = (
+  reported: ReadonlyMap<string, ActiveTask[]>,
+  added: ReadonlyMap<string, ActiveTask[]>,
+): Map<string, ActiveTask[]> => {
+  const merged = new Map(reported)
+  for (const [phaseId, tasks] of added) addTasks(merged, phaseId, tasks)
+  return merged
+}
+
+/** The signalled phase when a review can sit on it: one with an open gate box, else none. */
+const reviewPhaseOf = (signalled: PhaseProgress | null): PhaseProgress | null =>
+  signalled?.items.some((item) => item.gate && !item.done) ? signalled : null
+
+/**
+ * The runs of the lane's subagents, its reviews that name no phase placed on the `signalled` phase while its gate has
+ * an open box; otherwise they stay unplaced and show as tasks (`unplacedTasks`), so a running review never vanishes.
+ */
+const placedRuns = (input: SummaryInput, signalled: PhaseProgress | null): SubagentPhaseRun[] => {
+  const phase = reviewPhaseOf(signalled)
+  return [
+    ...(input.subagents ?? []),
+    ...(phase === null
+      ? []
+      : (input.phaselessReviews ?? []).map(({ review, at }) => ({ ids: [phase.id], review, at }))),
+  ]
+}
+
+/**
+ * The descriptions of the subagents that name no phase and sit on no task (`placed`), then those of the reviews no
+ * signalled phase takes.
+ */
+const unplacedTasks = (input: SummaryInput, signalled: PhaseProgress | null, placed: readonly string[]): string[] => [
+  ...(input.subagentTasks ?? []).filter((description) => !placed.includes(description)),
+  ...(reviewPhaseOf(signalled) === null
+    ? (input.phaselessReviews ?? []).flatMap(({ description }) => (description === null ? [] : [description]))
+    : []),
+]
+
 /** The open phases with a ticked task (`isStarted`) that are not `listed` yet, aged from their last tick when one is known. */
 const startedPhases = (phases: PhaseProgress[], timed: TimedPhase[], listed: readonly RunningPhase[]): RunningPhase[] =>
   phases
     .filter((phase) => isPhaseOpen(phase) && isStarted(phase) && !isListed(listed, phase))
     .map((phase) => ({ phase, minutesAgo: timed.find((each) => each.phase.id === phase.id)?.minutesAgo ?? null }))
 
+/** The signalled phase when no other source lists it yet, aged from its last tick when one is known. */
+const signalledRunning = (
+  signalled: PhaseProgress | null,
+  timed: TimedPhase[],
+  listed: readonly RunningPhase[],
+): RunningPhase[] =>
+  signalled && !isListed(listed, signalled)
+    ? [{ phase: signalled, minutesAgo: timed.find((each) => each.phase.id === signalled.id)?.minutesAgo ?? null }]
+    : []
+
 /**
- * The phases that run: the timed ones ticked less than `STALE_ACTIVITY_MINUTES` ago, the phases a reported task
- * names, then every other open phase with a ticked task (`isStarted`), with the age of its last tick when one is
- * known, else none (17:38). A phase only written down, without a tick or a report, waits.
+ * The phases that run: the timed ones ticked less than `STALE_ACTIVITY_MINUTES` ago, the phases a reported task or a
+ * running subagent names, the signalled phase (`signalledPhase`), then every other open phase with a ticked task
+ * (`isStarted`), with the age of its last tick when one is known, else none. A phase only written down, without a
+ * tick, a report or the lane's branch naming it, waits.
  */
 const runningPhases = (
   timed: TimedPhase[],
   phases: PhaseProgress[],
-  reported: ReadonlyMap<string, ActiveTask[]>,
+  signals: PhaseSignals & { signalled: PhaseProgress | null },
   now: number,
 ): RunningPhase[] => {
   const moved = timed.filter(({ minutesAgo }) => minutesAgo < STALE_ACTIVITY_MINUTES)
-  const listed = [...moved, ...reportedPhases(phases, reported, moved, now)]
+  const reported = [...moved, ...reportedPhases(phases, signals, moved, now)]
+  const listed = [...reported, ...signalledRunning(signals.signalled, timed, reported)]
   return [...listed, ...startedPhases(phases, timed, listed)]
 }
 
@@ -193,7 +326,7 @@ const runningPhases = (
  * passes no phase while an agent reports, so a lane with a report guesses nothing.
  */
 const guessedTasks = (input: SummaryInput, phases: PhaseProgress[], now: number): ReadonlyMap<string, number> =>
-  currentTasks(phases, input.guesses ?? [], now, STALE_ACTIVITY_MINUTES * MINUTE)
+  currentTasks(phases, input.guesses ?? [], now, STALE_ACTIVITY_MINUTES * MS_PER_MINUTE)
 
 /** The running phases, each with the tasks agents reported on it, else its task in `guessed`, marked as guessed. */
 const activeOf = (
@@ -234,6 +367,16 @@ const otherPlans = (input: SummaryInput, hrefs: string[]): WaitingPhases[] =>
     return open.length > 0 ? [{ planTitle: titleOf(input.progress, href), phaseIds: open.map(({ id }) => id) }] : []
   })
 
+const byPhaseNumber = (first: PhaseProgress, second: PhaseProgress): number =>
+  first.id.localeCompare(second.id, undefined, { numeric: true })
+
+/** The open phases of the current plan that do not run, by number. */
+const waitingIn = (phases: PhaseProgress[], running: ReadonlySet<string>): PhaseProgress[] =>
+  phases.filter((phase) => isPhaseOpen(phase) && !running.has(phase.id)).sort(byPhaseNumber)
+
+const otherHrefs = (input: SummaryInput, href: string): string[] =>
+  planHrefs(input.progress).filter((each) => each !== href)
+
 /** The open phases of the current plan that do not run, by number, then the open phases of the lane's other plans. */
 const waitingOf = (
   input: SummaryInput,
@@ -241,24 +384,75 @@ const waitingOf = (
   phases: PhaseProgress[],
   running: ReadonlySet<string>,
 ): WaitingPhases[] => {
-  const waiting = phases
-    .filter((phase) => isPhaseOpen(phase) && !running.has(phase.id))
-    .map(({ id }) => id)
-    .sort((first, second) => first.localeCompare(second, undefined, { numeric: true }))
-  const others = otherPlans(
-    input,
-    planHrefs(input.progress).filter((each) => each !== href),
-  )
-  return [...(waiting.length > 0 ? [{ planTitle: null, phaseIds: waiting }] : []), ...others]
+  const waiting = waitingIn(phases, running).map(({ id }) => id)
+  return [
+    ...(waiting.length > 0 ? [{ planTitle: null, phaseIds: waiting }] : []),
+    ...otherPlans(input, otherHrefs(input, href)),
+  ]
 }
 
-/** The finished phases of the current plan, each marked while its ticks are not merged. */
+const placedIn =
+  (progress: LaneProgress, href: string) =>
+  (phase: PhaseProgress): PlacedPhase => ({ phase, stepIndex: newestStepShowing(progress, href, phase.id) })
+
+/** The phases behind `waitingOf`, in its order, each with the step that shows it. */
+const waitingPlaced = (
+  input: SummaryInput,
+  href: string,
+  phases: PhaseProgress[],
+  running: ReadonlySet<string>,
+): PlacedPhase[] => [
+  ...waitingIn(phases, running).map(placedIn(input.progress, href)),
+  ...otherHrefs(input, href).flatMap((other) =>
+    phasesOf(input, other).filter(isPhaseOpen).map(placedIn(input.progress, other)),
+  ),
+]
+
+/** The finished phases of the current plan. */
 const finishedOf = (phases: PhaseProgress[]): FinishedPhase[] =>
-  phases.filter(isPhaseFinished).map((phase) => ({ id: phase.id, unmerged: isTickedUnmerged(phase) }))
+  phases.filter(isPhaseFinished).map((phase) => ({ id: phase.id }))
+
+type Resting = Pick<LaneSummary, 'waiting' | 'waitingPhases' | 'finished' | 'finishedPhases' | 'unwritten'>
+
+/** What does not run: the phases that wait or are finished, as ids and as phases to open, and those without a checkbox. */
+const restingOf = (input: SummaryInput, href: string, phases: PhaseProgress[], active: ActivePhase[]): Resting => {
+  const running = new Set(active.map(({ phase }) => phase.id))
+  return {
+    waiting: waitingOf(input, href, phases, running),
+    waitingPhases: waitingPlaced(input, href, phases, running),
+    finished: finishedOf(phases),
+    finishedPhases: phases.filter(isPhaseFinished).map(placedIn(input.progress, href)),
+    unwritten: stepPhases(input.progress, href)
+      .filter((phase) => !isWritten(phase))
+      .map(({ id, title }) => ({ id, missing: title === null })),
+  }
+}
+
+type ActiveSources = {
+  phases: PhaseProgress[]
+  timed: TimedPhase[]
+  /** The tasks agents reported, by phase id. */
+  reported: ReadonlyMap<string, ActiveTask[]>
+  /** Whether any report is fresh; the herd guesses no task then. */
+  anyFresh: boolean
+  signalled: PhaseProgress | null
+  /** The runs of the lane's subagents, the reviews that name no phase placed (`placedRuns`). */
+  subagents: readonly SubagentPhaseRun[]
+}
+
+/** The running phases of the plan on `href`, each with the tasks reported on it, the review gate or the guessed one. */
+const activePhases = (input: SummaryInput, href: string, sources: ActiveSources, now: number): ActivePhase[] => {
+  const { phases, timed, reported, anyFresh, signalled } = sources
+  const named = subagentPhases(phases, sources.subagents)
+  const running = runningPhases(timed, phases, { reported, subagents: named, signalled }, now)
+  const tasks = withReviewTasks(reported, phases, named)
+  const guessable = anyFresh ? [] : running.map(({ phase }) => phase).filter(({ id }) => !tasks.has(id))
+  return activeOf(input, href, running, tasks, guessedTasks(input, guessable, now))
+}
 
 /**
  * The lane summed up over its plans at `now`: the open phases running in its current plan (`runningPhases`), the open
- * phase moved last, the open phases that wait, the finished ones (marked when not merged yet), the phases its rows
+ * phase moved last, the open phases that wait, the finished ones, the phases its rows
  * name with nothing to run, and the tally over every plan of the lane. A phase ticked to the end, review gate
  * included, is finished, never running.
  */
@@ -266,24 +460,38 @@ export const laneSummary = (input: SummaryInput, now: number): LaneSummary => {
   const href = focusHref(input.progress)
   const tally = tallyOf(planHrefs(input.progress).flatMap((each) => phasesOf(input, each)))
   if (href === null) {
-    return { active: [], latest: null, waiting: [], finished: [], unwritten: [], tally, unplanned: [] }
+    const subagentTasks = unplacedTasks(input, null, [])
+    return {
+      active: [],
+      latest: null,
+      signalled: null,
+      waiting: [],
+      waitingPhases: [],
+      finished: [],
+      finishedPhases: [],
+      unwritten: [],
+      tally,
+      unplanned: [],
+      subagentTasks,
+    }
   }
   const phases = phasesOf(input, href)
   const timed = timedPhases(input, href, phases, now)
   const fresh = freshSignals(input.reported ?? [], newest(Object.values(input.activity)))
   const { byPhase, unplanned } = assignSignals(phases, fresh)
-  const running = runningPhases(timed, phases, byPhase, now)
-  const guessable = fresh.length > 0 ? [] : running.map(({ phase }) => phase).filter(({ id }) => !byPhase.has(id))
-  const active = activeOf(input, href, running, byPhase, guessedTasks(input, guessable, now))
+  const signalled = signalledPhase(phases, byPhase, input.branch ?? null)
+  const subagents = placedRuns(input, signalled)
+  const onTasks = subagentTaskPlacements(phases, input.describedSubagents ?? [])
+  const reported = withTasks(byPhase, onTasks.byPhase)
+  const sources = { phases, timed, reported, anyFresh: fresh.length > 0, signalled, subagents }
+  const active = activePhases(input, href, sources, now)
   return {
     active,
     latest: timed[0]?.phase ?? null,
-    waiting: waitingOf(input, href, phases, new Set(active.map(({ phase }) => phase.id))),
-    finished: finishedOf(phases),
-    unwritten: stepPhases(input.progress, href)
-      .filter((phase) => !isWritten(phase))
-      .map(({ id, title }) => ({ id, missing: title === null })),
+    signalled,
+    ...restingOf(input, href, phases, active),
     tally,
     unplanned,
+    subagentTasks: unplacedTasks(input, signalled, onTasks.placed),
   }
 }

package/src/plans/layout-phase.ts

@@ -11,6 +11,7 @@ import type { LinkChip } from './link-chips'
 import type { PhaseModel } from './phase-models'
 import { itemKey, type Selection, tickedKey } from './selection'
 import { chevronOf, MODEL_MARK, PHASE_COUNT, PHASE_STATE, type PhaseState, phaseStateOf } from './symbols'
+import { taskBodyOf, taskNameOf } from './task-name'
 import { type BadgeTexts, TEXTS } from './texts'
 
 /** What every block of one lane is drawn with. */
@@ -57,6 +58,9 @@ const PHASE_MARK: Record<PhaseState, string> = {
 
 export const plain = (text: string): string => text.replace(MARKDOWN_MARKS, '')
 
+/** What a task reads as on one row: its short name where it carries one (`taskNameOf`), else its whole text. */
+export const taskTitle = (text: string): string => plain(taskNameOf(text) ?? text)
+
 export const countText = (done: number, total: number): string =>
   `${String(done).padStart(COUNT_PLACES)}/${String(total).padEnd(COUNT_PLACES)}`
 
@@ -117,9 +121,16 @@ export const agentCell = (agent: string | null): string => (agent ? paint.dim(te
 /** Two cells: a task row hangs under its phase's label, which an arrow would otherwise push right. */
 export const TASK_INDENT = '  '
 
+/** `▶ <label> <text>`, the text bold, the agent dim at the right edge. */
+const labelledLine = (label: string, { text, agent }: UnplannedTask, width: number): string =>
+  spread(`${activeArrow(false)} ${label} ${paint.bold(plain(terminalSafe(text)))}`, agentCell(agent), width)
+
 /** `▶ now: <text>`: what an agent reports that no task of the plan names; the agent dim at the right edge. */
-export const nowLine = ({ text, agent }: UnplannedTask, width: number): string =>
-  spread(`${activeArrow(false)} ${TEXTS.now} ${paint.bold(plain(terminalSafe(text)))}`, agentCell(agent), width)
+export const nowLine = (task: UnplannedTask, width: number): string => labelledLine(TEXTS.now, task, width)
+
+/** `▶ Subagent: <description>`: a running subagent that names no phase and sits on none. */
+export const subagentLine = (description: string, width: number): string =>
+  labelledLine(TEXTS.subagent, { text: description, agent: null }, width)
 
 type TaskLook = { mark: string; style: (line: string) => string; suffix: string }
 
@@ -137,15 +148,26 @@ const taskLook = ({ done }: ChecklistItem, active: ActiveTask | undefined): Task
     : { mark: '☐', style: (line) => line, suffix: '' }
 }
 
-/** A closed task as one row, cut at the pane's edge with `…`. */
+/** A closed task as one row, its short name or its text cut at the pane's edge with `…`. */
 const closedTaskRow = (item: ChecklistItem, active: ActiveTask | undefined, width: number): string[] => {
   const { mark, style } = taskLook(item, active)
-  return [spread(`${mark} ${style(plain(item.text))}`, agentCell(active?.agent ?? null), width)]
+  return [spread(`${mark} ${style(taskTitle(item.text))}`, agentCell(active?.agent ?? null), width)]
 }
 
-/** An open task as rows: its whole text wrapped. */
-const openTaskRows = (item: ChecklistItem, active: ActiveTask | undefined, width: number): string[] =>
-  markedLines(item.text, taskLook(item, active), width)
+/** A named task opened: its name bold beside the mark, below it the line after the name (`taskBodyOf`) wrapped. */
+const namedTaskRows = (name: string, item: ChecklistItem, look: TaskLook, width: number): string[] => {
+  const body = wrap(plain(taskBodyOf(item.text)), Math.max(width - 2, 1)).map(
+    (line) => `  ${item.done ? paint.dim(line) : line}`,
+  )
+  return [fit(`${look.mark} ${paint.bold(plain(name))}${look.suffix}`, width), ...body]
+}
+
+/** An open task as rows: a named one by `namedTaskRows`, else its whole text wrapped. */
+const openTaskRows = (item: ChecklistItem, active: ActiveTask | undefined, width: number): string[] => {
+  const name = taskNameOf(item.text)
+  const look = taskLook(item, active)
+  return name ? namedTaskRows(name, item, look, width) : markedLines(item.text, look, width)
+}
 
 /** A task as a selectable row under its `key`: clickable across every line it takes, the cursor on its first. */
 export const taskFrame = (key: string, rows: string[], context: Pick<LaneContext, 'state' | 'width'>): Frame =>
@@ -155,8 +177,11 @@ export const taskFrame = (key: string, rows: string[], context: Pick<LaneContext
 const deferredRow = ({ text, target }: DeferredItem, width: number): string =>
   fit(paint.dim(`${DEFERRED_MARK} ${phaseLabel(target)} ${plain(text)}`), width)
 
-const tickedSummaryFrame = (count: number, phaseRowKey: string, width: number): Frame => ({
-  lines: [fit(paint.dim(`${chevronOf(false)} ${TEXTS.tickedSummary(count)}`), width)],
+/** The clickable line of a phase's ticked tasks: `▸ <n> ticked · …lists them`, or `▾ …folds them` above the listed ones. */
+const tickedSummaryFrame = (count: number, phaseRowKey: string, width: number, listed: boolean): Frame => ({
+  lines: [
+    fit(paint.dim(`${chevronOf(listed)} ${listed ? TEXTS.tickedFold(count) : TEXTS.tickedSummary(count)}`), width),
+  ],
   cursorLine: -1,
   targets: [{ line: 0, from: 0, to: width, key: tickedKey(phaseRowKey), wholeLine: true }],
 })
@@ -181,7 +206,7 @@ export const phaseChildren = (
   const framesWhere = (done: boolean): Frame[] =>
     phase.items.flatMap((item, index) => (item.done === done ? [frameOf(item, index)] : []))
   const tickedCount = phase.items.filter((item) => item.done).length
-  const summary = tickedCount > 0 ? [tickedSummaryFrame(tickedCount, phaseRowKey, width)] : []
+  const summary = tickedCount > 0 ? [tickedSummaryFrame(tickedCount, phaseRowKey, width, state.showDone)] : []
   const deferred = (phase.deferred ?? []).map((item) => textFrame([deferredRow(item, width)]))
-  return [...framesWhere(false), ...deferred, ...(state.showDone ? framesWhere(true) : summary)]
+  return [...framesWhere(false), ...deferred, ...summary, ...(state.showDone ? framesWhere(true) : [])]
 }