jackherd 1.8.0 → 1.9.0

package/src/plans/snapshot.ts

@@ -1,8 +1,8 @@
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import type { ContextReading } from '../context'
 import { type AgentLogReader, contextOfAgent } from '../context/report'
-import { agentLog } from '../context/session-log'
+import { agentLog, defaultProjectsDirectory } from '../context/session-log'
 import {
   type LaneProgress,
   laneProgress,
@@ -13,9 +13,12 @@ import {
   shortTitle,
   sprintTitleOf,
 } from '../plan-format'
+import { openWaitingItems, type WaitingItem } from '../plan-format/waiting'
+import type { TaskSignal } from '../task-signals/types'
 import type { LaneAgent, LaneStatusSource } from '../terminal'
 import type { SourceTicket, WatchBadges, WatchHealth } from '../watch/plan-badges'
 import { readWatchReading } from '../watch/plan-badges-read'
+import { assignSignals, laneOfDirectory, type UnplannedTask } from './active-tasks'
 import { boardRowsOf } from './board-rows'
 import {
   type ActivityTimes,
@@ -26,19 +29,25 @@ import {
   type PlanModified,
   withMovedPhase,
 } from './current-phase'
+import { activityTextOf, taskSignalsOf } from './current-task'
 import { errorText } from './error-text'
 import { type BaseReader, baseReaderOf, gitStatusOf, refExists } from './git'
 import type { PullRequestState } from './github'
 import { type Fallbacks, laneWorkOf, readAtBase, readFallback, readPlans, textAtBase } from './lane-plans'
 import { laneSummary } from './lane-summary'
 import { boardRowTexts, laneTicketsOf, withoutTicketLinks } from './lane-tickets'
-import { type LaneView, sortByUrgency } from './layout'
+import type { LaneView } from './layout'
 import { extractLinkChips } from './link-chips'
 import type { Options } from './options'
 import { laneModelsOf, type PhaseModelRecord } from './phase-models'
 import { readPhaseModels } from './phase-models-read'
 import { type PlannedPlan, plannedPlans } from './planned'
+import { type SentChip, type SentFileRecord, sentChipsByLane, sentWaitingItems } from './sent-files'
+import { readSentRecords } from './sent-files-read'
 import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from './settings'
+import { readAllSignals } from './signals-read'
+import type { SubagentActivity } from './subagents'
+import { readSubagentActivity } from './subagents-read'
 import { boardTexts } from './texts'
 import { type UnlistedLane, unlistedLanes, unlistedSprintLane } from './unlisted-lanes'
 import { withWorkedPhases } from './worked-phases'
@@ -52,6 +61,10 @@ export type Source = {
   terminal: LaneStatusSource
   /** The log lines of an agent's chat, null without one; defaults to reading them from `~/.claude/projects`. */
   readAgentLog?: AgentLogReader
+  /** The worktrees subagents of the coordinator work in; defaults to reading them from `~/.claude/projects`. */
+  readSubagents?: (root: string, worktreeDirectory: string) => Map<string, SubagentActivity>
+  /** What agents report doing (Claude's task lists, `jh task`); defaults to reading `~/.claude/projects` and `.jackherd/tasks/`. */
+  readSignals?: (root: string, worktreeDirectory: string, now: number) => TaskSignal[]
 }
 
 /**
@@ -86,6 +99,10 @@ export type Snapshot = {
   watch?: WatchHealth
   /** True when the config marks a ticket source, so a missing watcher is said without a pull request too. */
   watchesTickets?: boolean
+  /** What waits on the user's answer: the open rows of the board's section for it, from the checkout's board file. */
+  waiting?: WaitingItem[]
+  /** What agents report doing that no lane takes: the coordinator's own, or a lane the board does not list. */
+  unplaced?: UnplannedTask[]
 }
 
 type LaneSources = {
@@ -93,7 +110,15 @@ type LaneSources = {
   base: BaseReader
   sprintDirectory: string
   agents: LaneAgent[]
+  /** What subagents of the coordinator do in each worktree; a herdr agent in the worktree comes first. */
+  subagents: Map<string, SubagentActivity>
+  /** The agents' log reader, asking once per agent however often the read is used in one snapshot. */
+  readLog: AgentLogReader
   pullRequests: PullRequestState
+  /** What agents report doing, in every lane and outside them. */
+  signals: TaskSignal[]
+  /** The directory the lanes' worktrees lie in, which tells a signal's lane. */
+  worktrees: string
 }
 
 type BoardLanes = { markdown: string; lanes: SprintLane[] }
@@ -102,23 +127,54 @@ const SHOWN_NAMES = 2
 
 type LaneResult = { view: LaneView; files: string[]; texts: Record<string, string>; pane: string | null }
 
+/** The board's lanes the view shows, the running lanes it does not list, and what the lanes read from. */
+type LaneSet = { lanes: SprintLane[]; unlisted: UnlistedLane[]; sources: LaneSources; errors: string[] }
+
+/** What a lane's view is decorated with after it was read. */
+type Decorations = {
+  reading: ReturnType<typeof readWatchReading> | null
+  phaseModels: readonly PhaseModelRecord[]
+  sprintDirectory: string
+  sentChips: ReadonlyMap<string | null, SentChip[]>
+}
+
 /** How full the agent's context is, null when the terminal gave no session or the session has no log. */
-const contextOf = (agent: LaneAgent | undefined, source: Source): ContextReading | null => {
-  const report = contextOfAgent(agent, source.readAgentLog ?? agentLog, source.settings.context)
+const contextOf = (agent: LaneAgent | undefined, source: Source, readLog: AgentLogReader): ContextReading | null => {
+  const report = contextOfAgent(agent, readLog, source.settings.context)
   return report && { share: report.share, level: report.level }
 }
 
+/** A reader that asks once per agent (session and directory), so context and task signal share one read of a large log. */
+const onceReader = (read: AgentLogReader): AgentLogReader => {
+  const answers = new Map<string, string[] | null>()
+  return (agent) => {
+    const key = `${agent.session}\0${agent.cwd}`
+    if (!answers.has(key)) answers.set(key, read(agent))
+    return answers.get(key) ?? null
+  }
+}
+
+const WORK_ENTRIES = 40
+
+/** What the agents of a lane did lately: the end of its own agent's log and the log ends of subagents working in its worktree. */
+const workText = ({ readLog, subagents }: LaneSources, lane: string, agent: LaneAgent | undefined): string => {
+  const lines = agent ? readLog(agent) : null
+  return [lines ? activityTextOf(lines, WORK_ENTRIES) : '', subagents.get(lane)?.activity ?? ''].join(' ')
+}
+
 /** What a lane's worktree and agent say, listed in the sprint or not: git state, pull requests, context. */
 const runningState = async (sources: LaneSources, name: string, agent: LaneAgent | undefined) => {
   const { source, pullRequests } = sources
   const gitStatus = await gitStatusOf(worktreeOf(source.root, source.settings, name), baseRefOf(source.settings))
+  const subagent = agent ? undefined : sources.subagents.get(name)
+  const title = agent?.title ?? subagent?.description
   return {
     gitStatus,
     view: {
-      status: { agent: agent?.status ?? null, ...gitStatus },
-      ...(agent?.title ? { sessionTitle: agent.title } : {}),
+      status: { agent: agent?.status ?? subagent?.status ?? null, ...gitStatus },
+      ...(title ? { sessionTitle: title } : {}),
       pullRequests: gitStatus.branch ? (pullRequests.byBranch.get(gitStatus.branch) ?? []) : [],
-      context: contextOf(agent, source),
+      context: contextOf(agent, source, sources.readLog),
     },
   }
 }
@@ -175,7 +231,16 @@ const laneView = async (
     chips: Object.fromEntries(
       Object.entries(texts).map(([href, text]) => [href, extractLinkChips(text, settings.linkKinds)]),
     ),
-    summary: laneSummary({ progress, phases: phasesByHref, texts, activity, language: settings.planLanguage }, now),
+    summary: laneSummary(
+      {
+        progress,
+        phases: phasesByHref,
+        activity,
+        guesses: taskSignalsOf(Object.values(phasesByHref).flat(), workText(sources, lane.name, agent), now),
+        reported: sources.signals.filter(({ cwd }) => laneOfDirectory(cwd, sources.worktrees) === lane.name),
+      },
+      now,
+    ),
   }
   return { view, files, texts, pane: agent?.pane ?? null }
 }
@@ -185,14 +250,14 @@ const laneView = async (
  * and without phases, marked as unlisted.
  */
 const unlistedView = async (sources: LaneSources, { name, agent }: UnlistedLane): Promise<LaneResult> => {
-  const { view: running } = await runningState(sources, name, agent)
+  const { view: running } = await runningState(sources, name, agent ?? undefined)
   const view: LaneView = {
     progress: laneProgress(unlistedSprintLane(name), {}),
     ...running,
     chips: {},
     unlisted: true,
   }
-  return { view, files: [], texts: {}, pane: agent.pane }
+  return { view, files: [], texts: {}, pane: agent?.pane ?? null }
 }
 
 /** The view with the watcher's badges of its own pull requests, only when there are any, so it otherwise stays as it was. */
@@ -223,6 +288,30 @@ const withTickets = (result: LaneResult, tickets: readonly SourceTicket[]): Lane
   return found ? { ...view, chips: withoutTicketLinks(view.chips, found), tickets: found } : view
 }
 
+/** What agents report doing; nothing when it cannot be read. */
+const readSignals = ({ root, readSignals: read }: Source, worktrees: string, now: number): TaskSignal[] => {
+  try {
+    return (
+      read ??
+      ((main, directory, at) =>
+        readAllSignals({ projects: defaultProjectsDirectory(), root: main, worktrees: directory }, at))
+    )(root, worktrees, now)
+  } catch {
+    return []
+  }
+}
+
+/** The reports no shown lane takes, as lines for the overview: the coordinator's own and those of lanes without a plan. */
+const unplacedOf = (sources: LaneSources, lanes: readonly SprintLane[], onlyLane: boolean): UnplannedTask[] => {
+  if (onlyLane) return []
+  const listed = new Set(lanes.map((lane) => lane.name))
+  const rest = sources.signals.filter(({ cwd }) => {
+    const lane = laneOfDirectory(cwd, sources.worktrees)
+    return lane === null || !listed.has(lane)
+  })
+  return assignSignals([], rest).unplanned
+}
+
 /** The terminal's agents, or none with the reason when it cannot be asked, so the screen says why lanes show "no agent". */
 const readAgents = (terminal: LaneStatusSource): { agents: LaneAgent[]; errors: string[] } => {
   try {
@@ -232,6 +321,53 @@ const readAgents = (terminal: LaneStatusSource): { agents: LaneAgent[]; errors:
   }
 }
 
+/** What subagents of the coordinator do in the worktrees; nothing when their logs cannot be read. */
+const readSubagents = ({ root, readSubagents: read }: Source, worktrees: string): Map<string, SubagentActivity> => {
+  try {
+    return (
+      read ??
+      ((main, directory) =>
+        readSubagentActivity({
+          projects: defaultProjectsDirectory(),
+          root: main,
+          approvalsRoot: main,
+          worktreeDirectory: directory,
+        }))
+    )(root, worktrees)
+  } catch {
+    return new Map()
+  }
+}
+
+/**
+ * The open items that wait on the user, from the checkout's board file (the coordinator edits it before any commit),
+ * else from the text read at the base ref.
+ */
+const waitingOf = (
+  { sprintFile, settings }: Source,
+  markdown: string,
+  sends: readonly SentFileRecord[],
+  now: number,
+): WaitingItem[] => {
+  const board = (() => {
+    try {
+      return openWaitingItems(
+        existsSync(sprintFile) ? readFileSync(sprintFile, 'utf8') : markdown,
+        settings.planLanguage,
+      )
+    } catch {
+      return openWaitingItems(markdown, settings.planLanguage)
+    }
+  })()
+  return [...board, ...sentWaitingItems(sends, now)]
+}
+
+/** The view with the files its session sent to the user, only when there are any, so it otherwise stays as it was. */
+const withSentFiles = (view: LaneView, chips: ReadonlyMap<string | null, SentChip[]>): LaneView => {
+  const found = chips.get(view.progress.lane.name)
+  return found ? { ...view, sentFiles: found } : view
+}
+
 /** Up to two names, then how many more: `a, b and 3 more`. */
 const namedWithMore = (names: readonly string[]): string => {
   const more = names.length - SHOWN_NAMES
@@ -291,6 +427,92 @@ const forgetLanes = (memories: Map<string, LaneMemory> | undefined, lanes: reado
   for (const name of [...(memories?.keys() ?? [])]) if (!names.has(name)) memories?.delete(name)
 }
 
+const laneSetOf = (
+  source: Source,
+  context: { base: BaseReader; board: BoardLanes; sprintDirectory: string; worktrees: string },
+  pullRequests: PullRequestState,
+  now: number,
+): LaneSet => {
+  const { base, board, sprintDirectory, worktrees } = context
+  const { agents, errors } = readAgents(source.terminal)
+  const isWanted = ({ name }: { name: string }) => !source.options.lane || name === source.options.lane
+  const subagents = readSubagents(source, worktrees)
+  const listed = new Set(board.lanes.map((lane) => lane.name))
+  return {
+    lanes: board.lanes.filter(isWanted),
+    unlisted: unlistedLanes(agents, listed, worktrees, new Set(subagents.keys())).filter(isWanted),
+    sources: {
+      source,
+      base,
+      sprintDirectory,
+      agents,
+      subagents,
+      readLog: onceReader(source.readAgentLog ?? agentLog),
+      pullRequests,
+      signals: readSignals(source, worktrees, now),
+      worktrees,
+    },
+    errors,
+  }
+}
+
+/** The views of the listed lanes, then of the unlisted ones; the lanes' memories are cleaned of lanes the board dropped. */
+const laneResultsOf = async (
+  { lanes, unlisted, sources }: LaneSet,
+  fallbacks: Fallbacks,
+  now: number,
+  memories: Map<string, LaneMemory> | undefined,
+): Promise<LaneResult[]> => {
+  const results = [
+    ...(await Promise.all(lanes.map((lane) => laneView(sources, lane, fallbacks, now, memories)))),
+    ...(await Promise.all(unlisted.map((lane) => unlistedView(sources, lane)))),
+  ]
+  forgetLanes(memories, lanes)
+  return results
+}
+
+/** Each lane's view with its tickets, the watcher's badges, its phases' models and the files sent from it. */
+const decoratedViews = (
+  results: readonly LaneResult[],
+  { reading, phaseModels, sprintDirectory, sentChips }: Decorations,
+): LaneView[] =>
+  results.map((result) =>
+    withSentFiles(
+      withModels(
+        withBadges(withTickets(result, reading?.tickets ?? []), reading?.badges ?? {}),
+        phaseModels,
+        sprintDirectory,
+      ),
+      sentChips,
+    ),
+  )
+
+/** The files sent to the user, read once: the records, and their badges by lane. */
+const sendsOf = (
+  root: string,
+  worktrees: string,
+  now: number,
+): { records: SentFileRecord[]; chips: Map<string | null, SentChip[]> } => {
+  const records = readSentRecords(root)
+  return { records, chips: sentChipsByLane(records, worktrees, now) }
+}
+
+/** The open phases no lane with an agent leads; none while the view shows one lane. */
+const plannedOf = (
+  source: Source,
+  plans: Record<string, string>,
+  results: readonly LaneResult[],
+  sprintDirectory: string,
+): PlannedPlan[] =>
+  source.options.lane
+    ? []
+    : plannedPlans({
+        plans,
+        lanes: results.map(({ view }) => ({ lane: view.progress.lane, agent: view.status.agent })),
+        sprintDirectory,
+        language: source.settings.planLanguage,
+      })
+
 /**
  * Reads the board, its plans and the lanes' state. `memories` holds, per lane, what the herd saw at the last read; it
  * is how the current phase becomes the one whose boxes moved since, and it is cleaned of lanes the board dropped.
@@ -300,74 +522,48 @@ export const loadSnapshot = async (
   pullRequests: PullRequestState,
   memories?: Map<string, LaneMemory>,
 ): Promise<Snapshot> => {
-  const { root, sprintFile, options, settings, terminal } = source
+  const { root, sprintFile, options, settings } = source
   const fallbacks: Fallbacks = []
-  const base = baseReaderOf(root, baseRefOf(settings))
+  const baseRef = baseRefOf(settings)
+  const base = baseReaderOf(root, baseRef)
   const boardPath = boardRepoPathOf(root, settings, sprintFile)
   const board = await readBoardLanes(source, base, boardPath, fallbacks)
   const { markdown } = board
   const sprintDirectory = dirname(boardPath)
-  const { agents, errors } = readAgents(terminal)
-  const isWanted = ({ name }: { name: string }) => !options.lane || name === options.lane
-  const lanes = board.lanes.filter(isWanted)
-  const unlisted = unlistedLanes(
-    agents,
-    new Set(board.lanes.map((lane) => lane.name)),
-    join(root, settings.worktreeDirectory),
-  ).filter(isWanted)
-  const sources = {
-    source,
-    base,
-    sprintDirectory,
-    agents,
-    pullRequests,
-  }
+  const worktrees = join(root, settings.worktreeDirectory)
   const now = Date.now()
-  const results = [
-    ...(await Promise.all(lanes.map((lane) => laneView(sources, lane, fallbacks, now, memories)))),
-    ...(await Promise.all(unlisted.map((lane) => unlistedView(sources, lane)))),
-  ]
-  forgetLanes(memories, lanes)
+  const laneSet = laneSetOf(source, { base, board, sprintDirectory, worktrees }, pullRequests, now)
+  const results = await laneResultsOf(laneSet, fallbacks, now, memories)
   const listedPlans = await readListedPlans(source, base, sprintDirectory, markdown, fallbacks)
   const documentsPlans = Object.assign({}, listedPlans, ...results.map((result) => result.texts))
-  const planned = options.lane
-    ? []
-    : plannedPlans({
-        plans: documentsPlans,
-        lanes: results.map(({ view }) => ({ lane: view.progress.lane, agent: view.status.agent })),
-        sprintDirectory,
-        language: settings.planLanguage,
-      })
   const { ticketSources } = settings
   const watched = ticketSources.length > 0 || results.some(({ view }) => view.pullRequests.length > 0)
   const reading = watched ? readWatchReading(root, now, ticketSources) : null
-  const phaseModels = readPhaseModels(root)
-  const baseRef = baseRefOf(settings)
+  const sends = sendsOf(root, worktrees, now)
   const notice = fallbacks.length > 0 ? fallbackNotice(fallbacks, baseRef, refExists(root, baseRef)) : null
   const unknownLaneTitle =
     options.lane && results.length === 0 ? boardTexts(settings.board.term).laneNotListed(options.lane) : null
   return {
     title: unknownLaneTitle ?? sprintTitleOf(markdown, sprintDirectory),
-    views: sortByUrgency(
-      results.map((result) =>
-        withModels(
-          withBadges(withTickets(result, reading?.tickets ?? []), reading?.badges ?? {}),
-          phaseModels,
-          sprintDirectory,
-        ),
-      ),
-    ),
+    views: decoratedViews(results, {
+      reading,
+      phaseModels: readPhaseModels(root),
+      sprintDirectory,
+      sentChips: sends.chips,
+    }),
     documents: {
       sprint: markdown,
       plans: documentsPlans,
-      laneOrder: [...lanes, ...unlisted].map((lane) => lane.name),
+      laneOrder: [...laneSet.lanes, ...laneSet.unlisted].map((lane) => lane.name),
       lanes: board.lanes,
     },
-    planned,
+    planned: plannedOf(source, documentsPlans, results, sprintDirectory),
     files: [sprintFile, ...results.flatMap((result) => result.files)],
     titles: new Map(results.flatMap(({ view, pane }) => (pane ? [[pane, shortTitle(view.progress)]] : []))),
-    errors: [...errors, ...pullRequests.errors, ...(notice ? [notice] : [])],
+    errors: [...laneSet.errors, ...pullRequests.errors, ...(notice ? [notice] : [])],
     watch: reading?.health,
+    waiting: waitingOf(source, markdown, sends.records, now),
+    unplaced: unplacedOf(laneSet.sources, laneSet.lanes, Boolean(options.lane)),
     ...(ticketSources.length > 0 ? { watchesTickets: true } : {}),
   }
 }

package/src/plans/subagents-read.ts

@@ -0,0 +1,82 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { projectDirectoryOf, readTailLines } from '../context/session-log'
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { readApprovalRequests } from '../watch/approvals'
+import {
+  runningSubagents,
+  SUBAGENT_STALE_MINUTES,
+  type SubagentActivity,
+  type SubagentLog,
+  subagentsByLane,
+} from './subagents'
+
+export type SubagentSource = {
+  projects: string
+  /** The main checkout whose sessions are read. */
+  root: string
+  /** The main checkout whose `.jackherd/approvals/` holds the gate's requests. */
+  approvalsRoot: string
+  /** The absolute worktree directory. */
+  worktreeDirectory: string
+}
+
+/** 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$/
+/** A request the gate holds is reported for this long, as by the watcher. */
+const OPEN_REQUEST_MINUTES = 30
+
+const directoriesOf = (path: string): string[] => {
+  try {
+    return readdirSync(path, { withFileTypes: true }).flatMap((entry) => (entry.isDirectory() ? [entry.name] : []))
+  } catch {
+    return []
+  }
+}
+
+const logOf = (directory: string, name: string, id: string, now: number): SubagentLog[] => {
+  try {
+    const logPath = join(directory, `agent-${id}.jsonl`)
+    const modifiedAt = statSync(logPath).mtimeMs
+    if (now - modifiedAt > SUBAGENT_STALE_MINUTES * MS_PER_MINUTE) return []
+    const meta: unknown = JSON.parse(readFileSync(join(directory, name), 'utf8'))
+    return [{ id, meta, modifiedAt, tail: readTailLines(logPath, TAIL_BYTES) }]
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 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) => {
+    const directory = join(project, session, 'subagents')
+    if (!existsSync(directory)) return []
+    return readdirSync(directory).flatMap((name) => {
+      const id = META_FILE.exec(name)?.[1]
+      return id ? logOf(directory, name, id, 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(
+    readApprovalRequests(root)
+      .filter((request) => request.usedAt === null && now - request.createdAt <= OPEN_REQUEST_MINUTES * MS_PER_MINUTE)
+      .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,
+  now: number = Date.now(),
+): Map<string, SubagentActivity> =>
+  subagentsByLane(
+    runningSubagents(readSubagentLogs(projects, root, now), heldNames(approvalsRoot, now), now, worktreeDirectory),
+    worktreeDirectory,
+  )

package/src/plans/subagents.ts

@@ -0,0 +1,132 @@
+import { parseLogEntry } from '../context/session-log'
+import { MS_PER_MINUTE } from '../plan-format/clock'
+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 { 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. */
+export type SubagentLog = { id: string; meta: unknown; modifiedAt: number; tail: readonly string[] }
+
+/** A subagent of the coordinator that is at work now. */
+export type RunningSubagent = {
+  label: string
+  cwd: string | null
+  description: string | null
+  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
+}
+
+/** What a worktree shows of the subagents working in it. */
+export type SubagentActivity = Pick<RunningSubagent, 'status' | 'description' | 'activity'>
+
+/**
+ * A log untouched this long is not at work: Claude Code marks a finished subagent with `finished: true` in its
+ * `meta.json` only in its newer versions, so a subagent that was killed or ended before that has no mark.
+ */
+export const SUBAGENT_STALE_MINUTES = 15
+const AGENT_ID = /^[0-9a-f]{8,64}$/
+const AGENT_TYPE = /^[a-z0-9][a-z0-9-]{0,31}$/
+const ID_LENGTH = 8
+const ACTIVITY_ENTRIES = 40
+const DESCRIPTION_LENGTH = 80
+
+/** The name the approval gate holds a subagent under (`kit/hooks/hooks/approval-gate/subagent.ts`, contract test). */
+export const subagentLabelOf = (id: string, type: string | null): string | null =>
+  AGENT_ID.test(id)
+    ? `subagent-${type !== null && AGENT_TYPE.test(type) ? type : 'agent'}-${id.slice(0, ID_LENGTH)}`
+    : null
+
+const textOrNull = (value: unknown): string | null => (typeof value === 'string' && value !== '' ? value : null)
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** The strings a tool call of a log entry carries as paths: `file_path`, `path` and the `command` of a shell call. */
+const toolCallTexts = (entry: Record<string, unknown>): string[] => {
+  const content = isRecord(entry.message) && Array.isArray(entry.message.content) ? entry.message.content : []
+  return content.flatMap((block) => {
+    if (!isRecord(block) || block.type !== 'tool_use' || !isRecord(block.input)) return []
+    return [block.input.file_path, block.input.path, block.input.command].filter(
+      (value): value is string => typeof value === 'string',
+    )
+  })
+}
+
+/** The last worktree below `worktreeDirectory` that a text names, as its directory; null when it names none. */
+const lastWorktreeIn = (text: string, worktreeDirectory: string): string | null => {
+  const pattern = new RegExp(`${escapeRegExp(worktreeDirectory)}/([A-Za-z0-9._-]+)`, 'g')
+  const name = [...text.matchAll(pattern)].at(-1)?.[1]
+  return name === undefined ? null : `${worktreeDirectory}/${name}`
+}
+
+/**
+ * Where the subagent works: the worktree its most recent tool call names (a path, or a path in a shell command), since
+ * a coordinator's subagent starts in the main directory and changes directory per command, so its entries carry that
+ * directory; else the directory of the last entry that names one. Lines that are no JSON (the cut-off first one) are
+ * skipped.
+ */
+const workingDirectory = (tail: readonly string[], worktreeDirectory: string): string | null => {
+  const entries = [...tail].reverse().flatMap((line): Record<string, unknown>[] => {
+    const entry = parseLogEntry(line)
+    return entry === null ? [] : [entry]
+  })
+  for (const entry of entries) {
+    for (const text of toolCallTexts(entry).reverse()) {
+      const named = lastWorktreeIn(text, worktreeDirectory)
+      if (named !== null) return named
+    }
+  }
+  const directory = entries.find((entry) => typeof entry.cwd === 'string')?.cwd
+  return typeof directory === 'string' ? directory : null
+}
+
+/**
+ * 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.
+ */
+export const runningSubagents = (
+  logs: readonly SubagentLog[],
+  openRequests: ReadonlySet<string>,
+  now: number,
+  worktreeDirectory: 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))
+    if (label === null) return []
+    const description = textOrNull(typeof meta.description === 'string' ? terminalSafe(meta.description) : null)
+    const shortDescription = description?.slice(0, DESCRIPTION_LENGTH) ?? null
+    return [
+      {
+        label,
+        cwd: workingDirectory(tail, worktreeDirectory),
+        description: shortDescription,
+        status: openRequests.has(label) ? AGENT_STATUS.blocked : AGENT_STATUS.working,
+        activity: activityTextOf(tail, ACTIVITY_ENTRIES),
+      },
+    ]
+  })
+
+/** 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) {
+    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 })
+    else
+      lanes.set(lane, {
+        ...(status === AGENT_STATUS.blocked && known.status !== AGENT_STATUS.blocked ? { status, description } : known),
+        activity: `${known.activity} ${activity}`,
+      })
+  }
+  return lanes
+}