jackherd 1.9.0 → 1.10.0

package/src/plans/snapshot.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import type { ContextReading } from '../context'
 import { type AgentLogReader, contextOfAgent } from '../context/report'
@@ -13,12 +13,14 @@ import {
   shortTitle,
   sprintTitleOf,
 } from '../plan-format'
-import { openWaitingItems, type WaitingItem } from '../plan-format/waiting'
+import type { WaitingItem } from '../plan-format/waiting'
+import { dropUnused } from '../shared/stat-cache'
 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 { type AppointmentBlock, appointmentBlock } from './appointment-rows'
 import { boardRowsOf } from './board-rows'
 import {
   type ActivityTimes,
@@ -33,7 +35,15 @@ 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 {
+  type Fallbacks,
+  laneWorkOf,
+  type PlanSources,
+  readAtBase,
+  readFallback,
+  readPlans,
+  textAtBase,
+} from './lane-plans'
 import { laneSummary } from './lane-summary'
 import { boardRowTexts, laneTicketsOf, withoutTicketLinks } from './lane-tickets'
 import type { LaneView } from './layout'
@@ -41,15 +51,19 @@ import { extractLinkChips } from './link-chips'
 import type { Options } from './options'
 import { laneModelsOf, type PhaseModelRecord } from './phase-models'
 import { readPhaseModels } from './phase-models-read'
+import { laneHeads, planPullRequests, readerOncePerRef } from './plan-heads'
 import { type PlannedPlan, plannedPlans } from './planned'
-import { type SentChip, type SentFileRecord, sentChipsByLane, sentWaitingItems } from './sent-files'
-import { readSentRecords } from './sent-files-read'
+import type { PullRequest } from './pull-requests'
+import type { ReadCache } from './read-cache'
+import { type SentChip, sentChipsByLane } from './sent-files'
 import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from './settings'
+import { signalledTitle } from './signalled-phase'
 import { readAllSignals } from './signals-read'
 import type { SubagentActivity } from './subagents'
-import { readSubagentActivity } from './subagents-read'
+import { readSubagentActivity, subagentSourceOf } from './subagents-read'
 import { boardTexts } from './texts'
 import { type UnlistedLane, unlistedLanes, unlistedSprintLane } from './unlisted-lanes'
+import { readWaitingRecords, waitingItemsOf } from './waiting-records'
 import { withWorkedPhases } from './worked-phases'
 
 /** Where the view reads from: the main checkout, the sprint document, the command line and the project settings. */
@@ -101,6 +115,8 @@ export type Snapshot = {
   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[]
+  /** The board's open appointments, read from the same board text as `waiting`, for the block under it. */
+  appointments?: AppointmentBlock
   /** What agents report doing that no lane takes: the coordinator's own, or a lane the board does not list. */
   unplaced?: UnplannedTask[]
 }
@@ -115,13 +131,19 @@ type LaneSources = {
   /** The agents' log reader, asking once per agent however often the read is used in one snapshot. */
   readLog: AgentLogReader
   pullRequests: PullRequestState
+  /** The open pull requests that change a plan, whose heads raise the ticks the base ref has. */
+  planPullRequests: PullRequest[]
+  /** The reader of a pull request head, resolved once per read whatever the number of lanes. */
+  headReaderOf: (ref: string) => BaseReader
   /** 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
+  parsed?: PlanSources['parsed']
 }
 
-type BoardLanes = { markdown: string; lanes: SprintLane[] }
+/** `liveMarkdown` is the checkout's board file (the coordinator edits it before any commit), else `markdown`. */
+type BoardLanes = { markdown: string; liveMarkdown: string; lanes: SprintLane[] }
 
 const SHOWN_NAMES = 2
 
@@ -219,12 +241,20 @@ const laneView = async (
     modified,
   } = await readPlans(
     lane,
-    { root, settings, base: sources.base, sprintDirectory: sources.sprintDirectory },
+    {
+      root,
+      settings,
+      base: sources.base,
+      sprintDirectory: sources.sprintDirectory,
+      heads: laneHeads(sources.planPullRequests, gitStatus.branch, sources.headReaderOf),
+      parsed: sources.parsed,
+    },
     laneWorkOf(worktree, gitStatus),
     fallbacks,
   )
   const shown = withWorkedPhases(lane, phasesByHref)
   const { progress, activity } = progressWithMemory(shown, phasesByHref, memories, { now, modified })
+  const laneSubagents = sources.subagents.get(lane.name)
   const view: LaneView = {
     progress,
     ...running,
@@ -238,6 +268,11 @@ const laneView = async (
         activity,
         guesses: taskSignalsOf(Object.values(phasesByHref).flat(), workText(sources, lane.name, agent), now),
         reported: sources.signals.filter(({ cwd }) => laneOfDirectory(cwd, sources.worktrees) === lane.name),
+        subagents: laneSubagents?.phaseRuns ?? [],
+        subagentTasks: laneSubagents?.taskDescriptions ?? [],
+        phaselessReviews: laneSubagents?.phaselessReviews ?? [],
+        describedSubagents: laneSubagents?.describedSubagents ?? [],
+        branch: gitStatus.branch,
       },
       now,
     ),
@@ -289,12 +324,17 @@ const withTickets = (result: LaneResult, tickets: readonly SourceTicket[]): Lane
 }
 
 /** What agents report doing; nothing when it cannot be read. */
-const readSignals = ({ root, readSignals: read }: Source, worktrees: string, now: number): TaskSignal[] => {
+const readSignals = (
+  { root, readSignals: read }: Source,
+  worktrees: string,
+  now: number,
+  cache?: ReadCache,
+): TaskSignal[] => {
   try {
     return (
       read ??
       ((main, directory, at) =>
-        readAllSignals({ projects: defaultProjectsDirectory(), root: main, worktrees: directory }, at))
+        readAllSignals({ projects: defaultProjectsDirectory(), root: main, worktrees: directory }, at, cache?.signals))
     )(root, worktrees, now)
   } catch {
     return []
@@ -322,46 +362,19 @@ 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> => {
+const readSubagents = (
+  { root, settings, readSubagents: read }: Source,
+  worktrees: string,
+): Map<string, SubagentActivity> => {
   try {
     return (
-      read ??
-      ((main, directory) =>
-        readSubagentActivity({
-          projects: defaultProjectsDirectory(),
-          root: main,
-          approvalsRoot: main,
-          worktreeDirectory: directory,
-        }))
+      read ?? ((main, directory) => readSubagentActivity(subagentSourceOf(main, directory, settings.skillPrefix)))
     )(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)
@@ -395,8 +408,8 @@ const readBoardLanes = async (
   const { sprintFile, settings } = source
   const atBase = textAtBase(base, boardPath)
   const markdown = atBase ?? (await readFallback(boardPath, sprintFile, fallbacks)) ?? ''
-  const checkoutText = atBase !== null && existsSync(sprintFile) ? await Bun.file(sprintFile).text() : markdown
-  return { markdown, lanes: boardRowsOf(markdown, checkoutText, settings.planLanguage).lanes }
+  const liveMarkdown = atBase !== null && existsSync(sprintFile) ? await Bun.file(sprintFile).text() : markdown
+  return { markdown, liveMarkdown, lanes: boardRowsOf(markdown, liveMarkdown, settings.planLanguage).lanes }
 }
 
 /** The plans the sprint's plans tables name, read at the base ref, by link; lanes read theirs themselves. */
@@ -429,11 +442,17 @@ const forgetLanes = (memories: Map<string, LaneMemory> | undefined, lanes: reado
 
 const laneSetOf = (
   source: Source,
-  context: { base: BaseReader; board: BoardLanes; sprintDirectory: string; worktrees: string },
+  context: {
+    base: BaseReader
+    board: BoardLanes
+    sprintDirectory: string
+    worktrees: string
+    cache?: ReadCache
+  },
   pullRequests: PullRequestState,
   now: number,
 ): LaneSet => {
-  const { base, board, sprintDirectory, worktrees } = context
+  const { base, board, sprintDirectory, worktrees, cache } = context
   const { agents, errors } = readAgents(source.terminal)
   const isWanted = ({ name }: { name: string }) => !source.options.lane || name === source.options.lane
   const subagents = readSubagents(source, worktrees)
@@ -449,8 +468,11 @@ const laneSetOf = (
       subagents,
       readLog: onceReader(source.readAgentLog ?? agentLog),
       pullRequests,
-      signals: readSignals(source, worktrees, now),
+      planPullRequests: planPullRequests([...pullRequests.byBranch.values()].flat(), source.settings.planDirectory),
+      headReaderOf: readerOncePerRef((ref) => baseReaderOf(source.root, ref)),
+      signals: readSignals(source, worktrees, now, cache),
       worktrees,
+      parsed: cache && { entries: cache.plans, used: new Set<string>() },
     },
     errors,
   }
@@ -487,16 +509,6 @@ const decoratedViews = (
     ),
   )
 
-/** 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,
@@ -516,11 +528,13 @@ const plannedOf = (
 /**
  * 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.
+ * `cache`, kept by the caller between reads, spares parsing the session logs and plans that did not change.
  */
 export const loadSnapshot = async (
   source: Source,
   pullRequests: PullRequestState,
   memories?: Map<string, LaneMemory>,
+  cache?: ReadCache,
 ): Promise<Snapshot> => {
   const { root, sprintFile, options, settings } = source
   const fallbacks: Fallbacks = []
@@ -532,14 +546,18 @@ export const loadSnapshot = async (
   const sprintDirectory = dirname(boardPath)
   const worktrees = join(root, settings.worktreeDirectory)
   const now = Date.now()
-  const laneSet = laneSetOf(source, { base, board, sprintDirectory, worktrees }, pullRequests, now)
+  const liveBoard = board.liveMarkdown
+  const laneSet = laneSetOf(source, { base, board, sprintDirectory, worktrees, cache }, pullRequests, now)
   const results = await laneResultsOf(laneSet, fallbacks, now, memories)
+  const { parsed } = laneSet.sources
+  if (parsed) dropUnused(parsed.entries, parsed.used)
   const listedPlans = await readListedPlans(source, base, sprintDirectory, markdown, fallbacks)
   const documentsPlans = Object.assign({}, listedPlans, ...results.map((result) => result.texts))
   const { ticketSources } = settings
   const watched = ticketSources.length > 0 || results.some(({ view }) => view.pullRequests.length > 0)
   const reading = watched ? readWatchReading(root, now, ticketSources) : null
-  const sends = sendsOf(root, worktrees, now)
+  const waitingRecords = readWaitingRecords(root)
+  const sentChips = sentChipsByLane(waitingRecords.sent, 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
@@ -549,7 +567,7 @@ export const loadSnapshot = async (
       reading,
       phaseModels: readPhaseModels(root),
       sprintDirectory,
-      sentChips: sends.chips,
+      sentChips,
     }),
     documents: {
       sprint: markdown,
@@ -559,10 +577,15 @@ export const loadSnapshot = async (
     },
     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)]] : []))),
+    titles: new Map(
+      results.flatMap(({ view, pane }) =>
+        pane ? [[pane, signalledTitle(view.summary?.signalled ?? null, shortTitle(view.progress))]] : [],
+      ),
+    ),
     errors: [...laneSet.errors, ...pullRequests.errors, ...(notice ? [notice] : [])],
     watch: reading?.health,
-    waiting: waitingOf(source, markdown, sends.records, now),
+    waiting: waitingItemsOf(liveBoard, settings.planLanguage, waitingRecords, now),
+    appointments: appointmentBlock(liveBoard, settings.planLanguage, new Date(now)),
     unplaced: unplacedOf(laneSet.sources, laneSet.lanes, Boolean(options.lane)),
     ...(ticketSources.length > 0 ? { watchesTickets: true } : {}),
   }

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 }
+}