jackherd 1.9.0 → 1.11.0

package/src/plans/source-rows.ts

@@ -0,0 +1,188 @@
+import { TONE, type ToneName } from '../config/tones'
+import { padVisible } from '../terminal/text'
+import { textWidth } from '../terminal/width'
+import type { EntryStatus, SourceStatus } from '../watch/source-statuses'
+import { ASK_KIND } from './ask-target'
+import type { AskedCheck } from './source-asked'
+import { chevronOf } from './symbols'
+import type { BlockItem } from './waiting-click'
+
+/** A source's status with the tone its config names for the mark while its report is new; null where it names none. */
+export type HerdSource = SourceStatus & { tone?: ToneName | null }
+
+/** The sources block: the listed sources, and the clock (epoch milliseconds) their ages are counted against. */
+export type SourceBlock = { sources: HerdSource[]; now: number }
+
+/** What decides how the rows of the block look: the keys the user opened, and which entries a row of "Waiting for you" asks about. */
+export type SourceView = { expanded: ReadonlySet<string>; asked: AskedCheck }
+
+/** How many entries of an opened source show before `+<n> more`. */
+export const SOURCE_ENTRY_ROWS = 5
+
+const SOURCE_MARK = '●'
+const ENTRY_MARK = '•'
+const MORE_MARK = ' '
+const SEPARATOR = ' · '
+const ASKED_TEXT = '↑ asked'
+const MINUTE_MS = 60_000
+const HOUR_MS = 60 * MINUTE_MS
+const DAY_MS = 24 * HOUR_MS
+
+/** `just now`, `12 min ago`, `5 h ago` or `2 d ago`: the whole units since `since`, the largest that is at least one. */
+const agoOf = (since: number, now: number): string => {
+  const elapsed = Math.max(now - since, 0)
+  if (elapsed >= DAY_MS) return `${Math.floor(elapsed / DAY_MS)} d ago`
+  if (elapsed >= HOUR_MS) return `${Math.floor(elapsed / HOUR_MS)} h ago`
+  return elapsed >= MINUTE_MS ? `${Math.floor(elapsed / MINUTE_MS)} min ago` : 'just now'
+}
+
+const ranText = (ranAt: number | null, now: number): string =>
+  ranAt === null ? 'not run yet' : `ran ${agoOf(ranAt, now)}`
+
+const twoDigits = (value: number): string => String(value).padStart(2, '0')
+
+/** `11:11` for a time on the day of `now`, else the day and month before it, in the local time of the terminal. */
+const clockOf = (at: number, now: number): string => {
+  const date = new Date(at)
+  const time = `${twoDigits(date.getHours())}:${twoDigits(date.getMinutes())}`
+  return date.toDateString() === new Date(now).toDateString()
+    ? time
+    : `${twoDigits(date.getDate())}.${twoDigits(date.getMonth() + 1)}. ${time}`
+}
+
+const sourceKey = ({ name }: SourceStatus): string => `source>${name}`
+
+const entryKey = (name: string, { id }: EntryStatus): string => `source>${name}>${id}`
+
+/** The key in the herd's expanded set that shows every entry of the source, not the first five. */
+export const sourceMoreKey = (name: string): string => `more>source>${name}`
+
+const isUnaskedNew = (name: string, entry: EntryStatus, asked: AskedCheck): boolean =>
+  entry.isNew && !asked(name, entry.title)
+
+/**
+ * Red while the source fails; else the source's own tone or `newTone` while it has a new entry nobody asked about (for a
+ * source without entries: while its newest report is new); none otherwise.
+ */
+const toneOf = (source: HerdSource, newTone: ToneName, asked: AskedCheck): ToneName | undefined => {
+  if (source.failingSince !== null) return TONE.red
+  const hasNew =
+    source.entries.length > 0
+      ? source.entries.some((entry) => isUnaskedNew(source.name, entry, asked))
+      : source.latest?.isNew === true
+  return hasNew ? (source.tone ?? newTone) : undefined
+}
+
+const textOf = (source: HerdSource, now: number, expanded: boolean): string => {
+  const chevron = source.entries.length > 0 ? `${chevronOf(expanded)} ` : ''
+  const parts = [
+    ...(source.failingSince === null ? [] : [`failing since ${agoOf(source.failingSince, now)}`]),
+    ranText(source.ranAt, now),
+    ...(source.latest && source.entries.length === 0 ? [source.latest.title] : []),
+  ]
+  return `${chevron}${parts.join(SEPARATOR)}`
+}
+
+const headerOf = (
+  source: HerdSource,
+  view: SourceView,
+  now: number,
+  newTone: ToneName,
+  nameWidth: number,
+): BlockItem => {
+  const key = sourceKey(source)
+  const hasEntries = source.entries.length > 0
+  return {
+    key,
+    mark: SOURCE_MARK,
+    lead: padVisible(source.name, nameWidth),
+    text: textOf(source, now, view.expanded.has(key)),
+    url: hasEntries ? null : (source.latest?.url ?? null),
+    ask: null,
+    tone: toneOf(source, newTone, view.asked),
+    ...(hasEntries ? { toggle: key } : {}),
+  }
+}
+
+const entryToneOf = (
+  isAsked: boolean,
+  entry: EntryStatus,
+  source: HerdSource,
+  newTone: ToneName,
+): ToneName | undefined => {
+  if (isAsked) return TONE.grey
+  return entry.isNew ? (source.tone ?? newTone) : undefined
+}
+
+const entryTextOf = (entry: EntryStatus, now: number, isAsked: boolean): string =>
+  [entry.count === null ? '' : `${entry.count}×`, clockOf(entry.at, now), isAsked ? ASKED_TEXT : '']
+    .filter((part) => part !== '')
+    .join(' ')
+
+const entryItem = (
+  source: HerdSource,
+  entry: EntryStatus,
+  view: SourceView,
+  now: number,
+  newTone: ToneName,
+  titleWidth: number,
+): BlockItem => {
+  const isAsked = view.asked(source.name, entry.title)
+  const tone = entryToneOf(isAsked, entry, source, newTone)
+  return {
+    key: entryKey(source.name, entry),
+    mark: ENTRY_MARK,
+    lead: padVisible(entry.title, titleWidth),
+    text: entryTextOf(entry, now, isAsked),
+    url: entry.url,
+    ask: { kind: ASK_KIND.sourceEntry, source: source.name, title: entry.title },
+    ...(tone && { tone }),
+    ...(isAsked && { dim: true }),
+  }
+}
+
+const moreItem = (name: string, hidden: number, showsAll: boolean): BlockItem => ({
+  key: sourceMoreKey(name),
+  mark: MORE_MARK,
+  text: showsAll ? '▴ fewer' : `+${hidden} more`,
+  url: null,
+  ask: null,
+  toggle: sourceMoreKey(name),
+})
+
+const entryItems = (source: HerdSource, view: SourceView, now: number, newTone: ToneName): BlockItem[] => {
+  const showsAll = view.expanded.has(sourceMoreKey(source.name))
+  const shown = showsAll ? source.entries : source.entries.slice(0, SOURCE_ENTRY_ROWS)
+  const titleWidth = Math.max(0, ...shown.map(({ title }) => textWidth(title)))
+  const hidden = source.entries.length - SOURCE_ENTRY_ROWS
+  return [
+    ...shown.map((entry) => entryItem(source, entry, view, now, newTone, titleWidth)),
+    ...(hidden > 0 ? [moreItem(source.name, hidden, showsAll)] : []),
+  ]
+}
+
+const DEFAULT_VIEW: SourceView = { expanded: new Set(), asked: () => false }
+
+/**
+ * The rows of the sources block: per source one row with its name, when it ran, since when it fails and, for a source
+ * without entries, its newest report. A source with entries is folded to that row, and a click on it opens its entries
+ * (`view.expanded` holds its key): each with title, count and time, at most five and then `+<n> more`, a click on an
+ * entry opens its address, `[ask]` asks the coordinator to look at exactly that entry. An entry that a row of
+ * "Waiting for you" already asks about is dim and says `↑ asked`, and it does not make the source amber.
+ * `newTone` is the tone of the role `new`, which a source without its own tone wears while it has something new.
+ */
+export const sourceItems = (
+  sources: readonly HerdSource[],
+  now: number,
+  newTone: ToneName,
+  view: SourceView = DEFAULT_VIEW,
+): BlockItem[] => {
+  const nameWidth = Math.max(0, ...sources.map(({ name }) => textWidth(name)))
+  return sources.flatMap((source) => [
+    headerOf(source, view, now, newTone, nameWidth),
+    ...(view.expanded.has(sourceKey(source)) ? entryItems(source, view, now, newTone) : []),
+  ])
+}
+
+/** The keys of all rows: what the fold of the block remembers. */
+export const sourceKeys = (sources: readonly SourceStatus[]): string[] => sources.map(sourceKey)

package/src/plans/sprint-export.ts

@@ -1,7 +1,7 @@
-import { mkdirSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
 import { dirname } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import { pageDirectoryOf, systemLocation } from '../shared/private-location'
 import { openInBrowser } from '../terminal/open'
 import { errorText } from './error-text'
 import { baseRefInfo, remoteBlobBase } from './git'
@@ -11,19 +11,19 @@ import { renderPlanBody, renderSprintHtml } from './sprint-html'
 import { buildSprintPage, type SprintPage, sprintPagePath } from './sprint-page'
 import { boardTexts } from './texts'
 
-const DIRECTORY_MODE = 0o700
-const FILE_MODE = 0o600
-
-/** What writing and opening the page needs from outside; the defaults are the real ones. */
+/**
+ * What writing and opening the page needs from outside; the defaults are the real ones. `pageDirectory` is the
+ * user's own directory the page goes into, verified private before anything is written.
+ */
 export type ExportEnvironment = {
   now: () => Date
-  temporaryDirectory: string
+  pageDirectory: string
   open: (target: string) => string | null
 }
 
 const systemEnvironment = (): ExportEnvironment => ({
   now: () => new Date(),
-  temporaryDirectory: tmpdir(),
+  pageDirectory: pageDirectoryOf(systemLocation()),
   open: (target) => openInBrowser(target),
 })
 
@@ -46,10 +46,10 @@ const writePage = (
   { sprintFile, root, settings }: Source,
   environment: ExportEnvironment,
 ): WrittenPage | { error: string } => {
-  const path = sprintPagePath(environment.temporaryDirectory, dirname(boardRepoPathOf(root, settings, sprintFile)))
+  const path = sprintPagePath(environment.pageDirectory, dirname(boardRepoPathOf(root, settings, sprintFile)))
   try {
-    mkdirSync(dirname(path), { recursive: true, mode: DIRECTORY_MODE })
-    writeFileSync(path, renderSprintHtml(page), { mode: FILE_MODE })
+    ensurePrivateDirectory(environment.pageDirectory)
+    writePrivateFile(path, renderSprintHtml(page))
   } catch (error) {
     return { error: errorText(error) }
   }

package/src/plans/sprint-page.ts

@@ -16,6 +16,7 @@ import type { PlanLanguage } from '../vocabulary'
 import type { LaneView } from './layout'
 import { extractLinkChips, type LinkChip } from './link-chips'
 import { planAnchorOf } from './markdown-html'
+import { mainPhaseIdOf } from './phase-ids'
 import type { PullRequest } from './pull-requests'
 import type { Snapshot } from './snapshot'
 
@@ -150,14 +151,13 @@ const uniqueId = (base: string, taken: Set<string>): string => {
 }
 
 const phaseOf = (phase: PhaseProgress, dependencies: Record<string, string>): PagePhase => {
-  const numbered = phase.id.replace(/[a-z]$/, '')
   return {
     id: phase.id,
     title: phase.title,
     done: phase.done,
     total: phase.total,
     items: phase.items,
-    dependsOn: dependencies[phase.id] ?? dependencies[numbered] ?? null,
+    dependsOn: dependencies[phase.id] ?? dependencies[mainPhaseIdOf(phase.id)] ?? null,
   }
 }
 
@@ -282,6 +282,6 @@ export const buildSprintPage = (snapshot: Snapshot, context: PageContext): Sprin
   }
 }
 
-/** The file the page is written to: `<temporary directory>/jackherd/<board directory>.html`. */
-export const sprintPagePath = (temporaryDirectory: string, sprintDirectory: string): string =>
-  join(temporaryDirectory, 'jackherd', `${posix.basename(sprintDirectory) || 'board'}.html`)
+/** The file the page is written to: `<page directory>/<board directory>.html`. */
+export const sprintPagePath = (pageDirectory: string, sprintDirectory: string): string =>
+  join(pageDirectory, `${posix.basename(sprintDirectory) || 'board'}.html`)

package/src/plans/subagent-phases.ts

@@ -0,0 +1,95 @@
+import { isPhaseOpen, type PlanPhase } from '../plan-format'
+import { PHASE_ID_PREFIX, spannedPhaseIds } from '../plan-format/lanes'
+import { isNamedBy } from './phase-ids'
+
+/** The agent types that review a phase; they sit on its review gate. */
+export const REVIEW_TYPE = {
+  uncleBob: 'uncle-bob',
+  specReview: 'spec-review',
+  securityAudit: 'security-audit',
+  review: 'review',
+  ive: 'ive',
+  jobs: 'jobs',
+} as const
+
+export type ReviewType = (typeof REVIEW_TYPE)[keyof typeof REVIEW_TYPE]
+
+/**
+ * The phases a running subagent names in its description, its review type (null for no review), and when its log was
+ * last written. `ids` is empty only for a review that names no phase: the lane places it (`PhaselessReview`).
+ */
+export type SubagentPhaseRun = { ids: string[]; review: ReviewType | null; at: number }
+
+/** A running review whose description names no phase: it sits on the lane's signalled phase, else shows as its description. */
+export type PhaselessReview = { review: ReviewType; at: number; description: string | null }
+
+/** What the subagents say about one phase of the lane: the types of the reviews among them, and the newest log write. */
+export type SubagentPhase = { reviews: ReviewType[]; at: number }
+
+const isReviewTypeName = (type: string): type is ReviewType => (Object.values(REVIEW_TYPE) as string[]).includes(type)
+
+/** `P21`, `P17-P20`, `P17 – 19`, `Phase 21`, `Phase 10c`: the first number, an optional sub-phase letter, an optional end. */
+const PHASE_MENTION = new RegExp(
+  `(?:\\b${PHASE_ID_PREFIX}|\\bPhase\\s+)(\\d+)([a-z]?)(?:\\s*[-–—]\\s*(?:${PHASE_ID_PREFIX})?(\\d+)\\b)?`,
+  'gi',
+)
+
+/** The ids of a range `first`-`last`; a range that runs backwards or is absurdly wide names only its first end. */
+const rangeIds = (first: number, last: number): string[] => {
+  const spanned = spannedPhaseIds(first, last)
+  return spanned.length > 0 ? spanned : [String(first)]
+}
+
+/** The ids of the phases a description names, in the order named; a range names every phase between its ends. */
+export const phaseIdsOfDescription = (description: string): string[] =>
+  [...description.matchAll(PHASE_MENTION)].flatMap(([, first = '', letter = '', last]) =>
+    last === undefined ? [`${Number(first)}${letter.toLowerCase()}`] : rangeIds(Number(first), Number(last)),
+  )
+
+const withoutPrefix = (type: string, prefixes: readonly string[]): string => {
+  const prefix = prefixes.find((each) => each !== '' && type.startsWith(each))
+  return prefix === undefined ? type : type.slice(prefix.length)
+}
+
+/** The `REVIEW_TYPE` an agent type is, plain or with one of the skill `prefixes` of a copy; null for any other type. */
+export const reviewTypeOf = (type: string | null, prefixes: readonly string[]): ReviewType | null => {
+  const plain = type === null ? null : withoutPrefix(type, prefixes)
+  return plain !== null && isReviewTypeName(plain) ? plain : null
+}
+
+/**
+ * The run of a subagent from its `description` and `agentType`: null when the description names no phase and the
+ * subagent is no review. The description is read whole, not cut for the display.
+ */
+export const subagentPhaseRunOf = (
+  description: string | null,
+  agentType: string | null,
+  at: number,
+  reviewPrefixes: readonly string[],
+): SubagentPhaseRun | null => {
+  const ids = description === null ? [] : phaseIdsOfDescription(description)
+  const review = reviewTypeOf(agentType, reviewPrefixes)
+  return ids.length === 0 && review === null ? null : { ids, review, at }
+}
+
+const names = (run: SubagentPhaseRun, id: string): boolean => isNamedBy(id, new Set(run.ids))
+
+const reviewsOf = (runs: readonly SubagentPhaseRun[]): ReviewType[] => [
+  ...new Set(runs.flatMap(({ review }) => (review === null ? [] : [review]))),
+]
+
+/**
+ * The open phases of the lane that running subagents name, by phase id: a sub-phase (`21b`) is named by its main phase.
+ * Phases the lane does not hold are left out, since another lane's phases are not its own.
+ */
+export const subagentPhases = (
+  phases: readonly Pick<PlanPhase, 'id' | 'items'>[],
+  runs: readonly SubagentPhaseRun[],
+): Map<string, SubagentPhase> =>
+  new Map(
+    phases.filter(isPhaseOpen).flatMap(({ id }) => {
+      const naming = runs.filter((run) => names(run, id))
+      if (naming.length === 0) return []
+      return [[id, { reviews: reviewsOf(naming), at: Math.max(...naming.map(({ at }) => at)) }]]
+    }),
+  )

package/src/plans/subagent-tasks.ts

@@ -0,0 +1,51 @@
+import type { ActiveTask } from './active-tasks'
+import type { TaskPhase } from './current-task'
+import { taskNameOf } from './task-name'
+
+/** A running subagent that is no review: its description as the herd shows it, and when its log was last written. */
+export type DescribedSubagent = { description: string; at: number }
+
+/** Where the subagents sit: their tasks by phase id, and the descriptions placed, which show no line of their own. */
+export type SubagentTaskPlacements = { byPhase: Map<string, ActiveTask[]>; placed: string[] }
+
+type NamedTask = { phaseId: string; index: number; name: string }
+
+/** A letter or digit right after the name continues a word, so `Probe` does not name `Proben lesen`. */
+const WORD_GOES_ON = /^[\p{L}\p{N}]/u
+
+/** The open tasks that carry a short name, the longest names first, so a name that starts another loses to it. */
+const namedOpenTasks = (phases: readonly TaskPhase[]): NamedTask[] =>
+  phases
+    .flatMap(({ id, items }) =>
+      items.flatMap((item, index) => {
+        const name = item.done || item.gate ? null : taskNameOf(item.text)
+        return name === null ? [] : [{ phaseId: id, index, name }]
+      }),
+    )
+    .sort((first, second) => second.name.length - first.name.length)
+
+const startsWithName = (description: string, name: string): boolean =>
+  description.toLowerCase().startsWith(name.toLowerCase()) && !WORD_GOES_ON.test(description.slice(name.length))
+
+/**
+ * The open task each subagent works on, from the short name its description starts with (`/implement` Step 0b, case
+ * ignored): it gets its `▶` like a reported task, one per task however many subagents share it. A ticked task and a
+ * review gate item take none; a subagent whose description starts with no name stays where it was.
+ */
+export const subagentTaskPlacements = (
+  phases: readonly TaskPhase[],
+  subagents: readonly DescribedSubagent[],
+): SubagentTaskPlacements => {
+  const tasks = namedOpenTasks(phases)
+  const byPhase = new Map<string, ActiveTask[]>()
+  const placed: string[] = []
+  for (const { description, at } of subagents) {
+    const task = tasks.find(({ name }) => startsWithName(description, name))
+    if (task === undefined) continue
+    placed.push(description)
+    const known = byPhase.get(task.phaseId) ?? []
+    if (known.some(({ index }) => index === task.index)) continue
+    byPhase.set(task.phaseId, [...known, { index: task.index, agent: null, guessed: false, startedAt: at }])
+  }
+  return { byPhase, placed }
+}

package/src/plans/subagents-read.ts

@@ -1,9 +1,11 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { projectDirectoryOf, readTailLines } from '../context/session-log'
+import { defaultProjectsDirectory, projectDirectoryOf, readTailLines } from '../context/session-log'
 import { MS_PER_MINUTE } from '../plan-format/clock'
+import { DEFAULT_SKILL_PREFIX } from '../sync/init'
 import { readApprovalRequests } from '../watch/approvals'
 import {
+  type RunningSubagent,
   runningSubagents,
   SUBAGENT_STALE_MINUTES,
   type SubagentActivity,
@@ -19,8 +21,19 @@ export type SubagentSource = {
   approvalsRoot: string
   /** The absolute worktree directory. */
   worktreeDirectory: string
+  /** The project's `skillPrefix`, which its copies of the review agents carry; without it only the default one counts. */
+  skillPrefix?: string
 }
 
+/** The source of the main checkout `root`: Claude Code's own session logs, the gate's requests in the checkout itself. */
+export const subagentSourceOf = (root: string, worktreeDirectory: string, skillPrefix?: string): SubagentSource => ({
+  projects: defaultProjectsDirectory(),
+  root,
+  approvalsRoot: root,
+  worktreeDirectory,
+  skillPrefix,
+})
+
 /** The end of a log that holds the directory of the last entries. */
 const TAIL_BYTES = 64 * 1024
 const META_FILE = /^agent-([0-9a-f]+)\.meta\.json$/
@@ -35,6 +48,15 @@ const directoriesOf = (path: string): string[] => {
   }
 }
 
+/** The entry names of `path`; none when it is missing or cannot be read. */
+const namesIn = (path: string): string[] => {
+  try {
+    return readdirSync(path)
+  } catch {
+    return []
+  }
+}
+
 const logOf = (directory: string, name: string, id: string, now: number): SubagentLog[] => {
   try {
     const logPath = join(directory, `agent-${id}.jsonl`)
@@ -47,22 +69,39 @@ const logOf = (directory: string, name: string, id: string, now: number): Subage
   }
 }
 
-/**
- * The subagents with a recently written log in the sessions started in the main checkout `root`, from Claude Code's
- * `<projects>/<project>/<session>/subagents/agent-<id>.{meta.json,jsonl}`; whatever cannot be read is left out.
- */
-export const readSubagentLogs = (projects: string, root: string, now: number): SubagentLog[] => {
-  const project = join(projects, projectDirectoryOf(root))
-  return directoriesOf(project).flatMap((session) => {
+/** The subagent logs of every session in one project directory. */
+const sessionLogsOf = (project: string, now: number): SubagentLog[] =>
+  directoriesOf(project).flatMap((session) => {
     const directory = join(project, session, 'subagents')
-    if (!existsSync(directory)) return []
-    return readdirSync(directory).flatMap((name) => {
+    return namesIn(directory).flatMap((name) => {
       const id = META_FILE.exec(name)?.[1]
       return id ? logOf(directory, name, id, now) : []
     })
   })
+
+/**
+ * The project directories Claude Code keeps for sessions started in the main checkout `root` and, when
+ * `worktreeDirectory` is given, in a worktree below it: a lane's own subagents, its reviews among them, live there.
+ */
+const projectDirectoriesOf = (projects: string, root: string, worktreeDirectory?: string): string[] => {
+  const main = projectDirectoryOf(root)
+  const lanes = worktreeDirectory === undefined ? null : `${projectDirectoryOf(worktreeDirectory)}-`
+  return directoriesOf(projects).filter((name) => name === main || (lanes !== null && name.startsWith(lanes)))
 }
 
+/**
+ * The subagents with a recently written log in the sessions started in the main checkout `root` and its worktrees,
+ * from Claude Code's `<projects>/<project>/<session>/subagents/agent-<id>.{meta.json,jsonl}`; whatever cannot be read
+ * is left out.
+ */
+export const readSubagentLogs = (
+  projects: string,
+  root: string,
+  now: number,
+  worktreeDirectory?: string,
+): SubagentLog[] =>
+  projectDirectoriesOf(projects, root, worktreeDirectory).flatMap((name) => sessionLogsOf(join(projects, name), now))
+
 /** The names the gate holds an open request under, as the watcher reads them. */
 const heldNames = (root: string, now: number): Set<string> =>
   new Set(
@@ -71,12 +110,22 @@ const heldNames = (root: string, now: number): Set<string> =>
       .map((request) => request.lane),
   )
 
-/** The state of every worktree a subagent of the main checkout's sessions works in. */
-export const readSubagentActivity = (
-  { projects, root, approvalsRoot, worktreeDirectory }: SubagentSource,
+/**
+ * The subagents at work in the sessions of the main checkout and its worktrees: their logs read, the finished and the
+ * stale left out. The one chain the herd (`readSubagentActivity`) and the watcher's heartbeat share.
+ */
+export const readRunningSubagents = (
+  { projects, root, approvalsRoot, worktreeDirectory, skillPrefix }: SubagentSource,
   now: number = Date.now(),
-): Map<string, SubagentActivity> =>
-  subagentsByLane(
-    runningSubagents(readSubagentLogs(projects, root, now), heldNames(approvalsRoot, now), now, worktreeDirectory),
+): RunningSubagent[] =>
+  runningSubagents(
+    readSubagentLogs(projects, root, now, worktreeDirectory),
+    heldNames(approvalsRoot, now),
+    now,
     worktreeDirectory,
+    skillPrefix === undefined ? [DEFAULT_SKILL_PREFIX] : [DEFAULT_SKILL_PREFIX, skillPrefix],
   )
+
+/** The state of every worktree a subagent of the main checkout's sessions works in. */
+export const readSubagentActivity = (source: SubagentSource, now: number = Date.now()): Map<string, SubagentActivity> =>
+  subagentsByLane(readRunningSubagents(source, now), source.worktreeDirectory)

package/src/plans/subagents.ts

@@ -4,6 +4,8 @@ import { terminalSafe } from '../plan-format/terminal-text'
 import { isRecord } from '../shared/is-record'
 import { AGENT_STATUS, type AgentStatus } from '../terminal/types'
 import { activityTextOf } from './current-task'
+import { type PhaselessReview, type SubagentPhaseRun, subagentPhaseRunOf } from './subagent-phases'
+import type { DescribedSubagent } from './subagent-tasks'
 import { laneDirectoryOf } from './unlisted-lanes'
 
 /** What the log files of one subagent say: its id, its `meta.json` as parsed, when the log was written, its last lines. */
@@ -17,10 +19,25 @@ export type RunningSubagent = {
   status: Extract<AgentStatus, 'working' | 'blocked'>
   /** The text of its last log entries, from which the herd tells the task it works on (`taskSignalsOf`). */
   activity: string
+  /** The phases its full description names (`P21`, `P17-P20`), none for a review that names none; null for any other. */
+  phaseRun: SubagentPhaseRun | null
+  /** When its log was last written. */
+  writtenAt: number
 }
 
-/** What a worktree shows of the subagents working in it. */
-export type SubagentActivity = Pick<RunningSubagent, 'status' | 'description' | 'activity'>
+/** What a worktree shows of the subagents working in it; `phaseRuns` are those of all its subagents that name a phase. */
+export type SubagentActivity = Pick<RunningSubagent, 'status' | 'description' | 'activity'> & {
+  phaseRuns: SubagentPhaseRun[]
+  /** Its reviews that name no phase; the lane places them on its signalled phase (`laneSummary`). */
+  phaselessReviews: PhaselessReview[]
+  /**
+   * The descriptions of its other subagents that name no phase: what they work on, a signal of the lane like a
+   * reported task.
+   */
+  taskDescriptions: string[]
+  /** Its subagents that are no review, phase or not; one whose description starts with a task's short name sits on it. */
+  describedSubagents: DescribedSubagent[]
+}
 
 /**
  * A log untouched this long is not at work: Claude Code marks a finished subagent with `finished: true` in its
@@ -85,18 +102,21 @@ const workingDirectory = (tail: readonly string[], worktreeDirectory: string): s
 /**
  * The subagents at work: no `finished` mark in the meta, and the log written within `SUBAGENT_STALE_MINUTES`. One
  * waits for an answer while the approval gate holds a request under its name (`openRequests` are the names of the open
- * requests); the transcript alone cannot tell a permission dialog from a long tool call.
+ * requests); the transcript alone cannot tell a permission dialog from a long tool call. `reviewPrefixes` are the skill
+ * prefixes a copy of the review agents may carry.
  */
 export const runningSubagents = (
   logs: readonly SubagentLog[],
   openRequests: ReadonlySet<string>,
   now: number,
   worktreeDirectory: string,
+  reviewPrefixes: readonly string[],
 ): RunningSubagent[] =>
   logs.flatMap(({ id, meta, modifiedAt, tail }) => {
     if (!isRecord(meta) || meta.finished === true || now - modifiedAt > SUBAGENT_STALE_MINUTES * MS_PER_MINUTE)
       return []
-    const label = subagentLabelOf(id, textOrNull(meta.agentType))
+    const agentType = textOrNull(meta.agentType)
+    const label = subagentLabelOf(id, agentType)
     if (label === null) return []
     const description = textOrNull(typeof meta.description === 'string' ? terminalSafe(meta.description) : null)
     const shortDescription = description?.slice(0, DESCRIPTION_LENGTH) ?? null
@@ -107,25 +127,63 @@ export const runningSubagents = (
         description: shortDescription,
         status: openRequests.has(label) ? AGENT_STATUS.blocked : AGENT_STATUS.working,
         activity: activityTextOf(tail, ACTIVITY_ENTRIES),
+        phaseRun: subagentPhaseRunOf(description, agentType, modifiedAt, reviewPrefixes),
+        writtenAt: modifiedAt,
       },
     ]
   })
 
+/** The description of a subagent that names no phase, as a list of at most one; empty for a review or one that names a phase. */
+const taskDescriptionOf = ({ phaseRun, description }: RunningSubagent): string[] =>
+  phaseRun === null && description !== null ? [description] : []
+
+/** A subagent that is no review, with its description, as a list of at most one. */
+const describedSubagentOf = ({ phaseRun, description, writtenAt }: RunningSubagent): DescribedSubagent[] =>
+  description !== null && (phaseRun === null || phaseRun.review === null) ? [{ description, at: writtenAt }] : []
+
+/** The run of a subagent that names a phase, as a list of at most one. */
+const namedRunOf = ({ phaseRun }: RunningSubagent): SubagentPhaseRun[] =>
+  phaseRun !== null && phaseRun.ids.length > 0 ? [phaseRun] : []
+
+/** A review that names no phase, as a list of at most one. */
+const phaselessReviewOf = ({ phaseRun, description }: RunningSubagent): PhaselessReview[] => {
+  if (phaseRun === null || phaseRun.review === null || phaseRun.ids.length > 0) return []
+  return [{ review: phaseRun.review, at: phaseRun.at, description }]
+}
+
 /** The worktrees below `worktreeDirectory` the subagents work in; one that waits for an answer decides the state. */
 export const subagentsByLane = (
   running: readonly RunningSubagent[],
   worktreeDirectory: string,
 ): Map<string, SubagentActivity> => {
   const lanes = new Map<string, SubagentActivity>()
-  for (const { cwd, status, description, activity } of running) {
+  for (const subagent of running) {
+    const { cwd, status, description, activity } = subagent
     const lane = cwd === null ? null : laneDirectoryOf(cwd, worktreeDirectory)
     if (lane === null) continue
     const known = lanes.get(lane)
-    if (!known) lanes.set(lane, { status, description, activity })
+    const runs = namedRunOf(subagent)
+    const reviews = phaselessReviewOf(subagent)
+    const tasks = taskDescriptionOf(subagent)
+    const described = describedSubagentOf(subagent)
+    if (!known)
+      lanes.set(lane, {
+        status,
+        description,
+        activity,
+        phaseRuns: runs,
+        phaselessReviews: reviews,
+        taskDescriptions: tasks,
+        describedSubagents: described,
+      })
     else
       lanes.set(lane, {
         ...(status === AGENT_STATUS.blocked && known.status !== AGENT_STATUS.blocked ? { status, description } : known),
         activity: `${known.activity} ${activity}`,
+        phaseRuns: [...known.phaseRuns, ...runs],
+        phaselessReviews: [...known.phaselessReviews, ...reviews],
+        taskDescriptions: [...known.taskDescriptions, ...tasks],
+        describedSubagents: [...known.describedSubagents, ...described],
       })
   }
   return lanes