jackherd 1.8.0 → 1.9.0

package/src/watch/failed-tests.ts

@@ -1,4 +1,5 @@
 import { terminalSafe } from '../plan-format/terminal-text'
+import { stripAnsi } from '../terminal/text'
 
 /** The most failed tests kept for one head commit. */
 export const FAILED_TEST_LIMIT = 50
@@ -29,24 +30,69 @@ const compiled = (pattern: string): RegExp | null => {
   }
 }
 
+/** `places` holds, by test name, the package or test file the log printed before the test; a test before any has none. */
+export type FailedTestScan = { tests: string[]; places: Record<string, string> }
+
+/** `##[group]`, which GitHub Actions folds a section behind, in front of a header line. */
+const GROUP_MARK = /^##\[group\]/
+
+/** The task header a monorepo runner (turbo) prints before a package's run: `@scope/name:test`, the package first. */
+const TASK_HEADER = /^(@[\w.-]+\/[\w.-]+|[\w.-]+):[\w:-]*test[\w:-]*$/
+
+/** The header Bun prints before the results of one test file: its path and a colon. */
+const FILE_HEADER = /^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/
+
+/** Where the scan stands in the log: the package of the current task and the test file of the current run. */
+type ScanPlace = { task: string | null; file: string | null }
+
+/** The place after `line`: a task header starts a new package, a file header a new file. */
+const placeAfter = (place: ScanPlace, line: string): ScanPlace => {
+  const header = stripAnsi(line).replace(GROUP_MARK, '')
+  const task = TASK_HEADER.exec(header)?.[1]
+  if (task) return { task: nameOf(task), file: null }
+  const file = FILE_HEADER.exec(header)?.[1]
+  return file ? { ...place, file: nameOf(file) } : place
+}
+
+const cleanLine = (raw: string): string => raw.replace(/\r$/, '').replace(LOG_PREFIX, '')
+
 /**
- * The names of the failed tests in the log `gh run view <id> --log-failed` printed, in the order first seen. Each line
- * loses its job, step and timestamp prefix, then `pattern` (a regular expression) is matched against it: the first
- * group is the name, else the whole match. A test the log names twice (Bun lists it in the run and in the summary) is
- * listed once. Names are made terminal-safe and cut; at most `FAILED_TEST_LIMIT` are kept. A pattern that is no
- * regular expression finds nothing.
+ * The failed tests in the log `gh run view <id> --log-failed` printed, in the order first seen, with the place each
+ * was first seen in. Each line loses its job, step and timestamp prefix, then `pattern` (a regular expression) is
+ * matched against it: the first group is the name, else the whole match. The place is the package of the task header
+ * before it (`@scope/name:test`), else the test file Bun printed before it. A test the log names twice (Bun lists it
+ * in the run and in the summary) is listed once, at its first place. Names and places are made terminal-safe and cut;
+ * at most `FAILED_TEST_LIMIT` are kept. A pattern that is no regular expression finds nothing.
  */
-export const extractFailedTests = (log: string, pattern: string): string[] => {
+export const scanFailedTests = (log: string, pattern: string): FailedTestScan => {
   const expression = compiled(pattern)
-  if (!expression) return []
+  const places: Record<string, string> = {}
+  if (!expression) return { tests: [], places }
   const names = new Set<string>()
+  let place: ScanPlace = { task: null, file: null }
   for (const raw of log.split('\n')) {
     if (names.size >= FAILED_TEST_LIMIT) break
-    const line = raw.replace(/\r$/, '').replace(LOG_PREFIX, '')
+    const line = cleanLine(raw)
     if (line.length > MAX_LINE_LENGTH) continue
+    place = placeAfter(place, line)
     const match = expression.exec(line)
     const name = nameOf(match?.[1] ?? match?.[0] ?? '')
-    if (name !== '') names.add(name)
+    if (name === '' || names.has(name)) continue
+    names.add(name)
+    const where = place.task ?? place.file
+    if (where) places[name] = where
   }
-  return [...names]
+  return { tests: [...names], places }
 }
+
+/** `places` read back from the state file, for the names in `names` only, made terminal-safe and cut like the names. */
+export const sanitisedFailedTestPlaces = (
+  places: Readonly<Record<string, string>>,
+  names: readonly string[],
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(places).flatMap(([name, place]) => {
+      const shown = nameOf(name)
+      return names.includes(shown) && nameOf(place) !== '' ? [[shown, nameOf(place)]] : []
+    }),
+  )

package/src/watch/failure-read.ts

@@ -1,6 +1,6 @@
-import { extractFailedTests, FAILED_TEST_LIMIT } from './failed-tests'
+import { isRecord } from '../shared/is-record'
+import { FAILED_TEST_LIMIT, scanFailedTests } from './failed-tests'
 import { type GhAnswer, runGh } from './gh'
-import { isRecord } from './json-guards'
 
 /** How long `gh run view --log-failed` may take before the call is given up; a read that timed out is tried again. */
 export const LOG_TIMEOUT_MS = 30_000
@@ -8,8 +8,13 @@ export const LOG_TIMEOUT_MS = 30_000
 /** Of a longer log only this many characters from the end are kept; Bun repeats its failures in the summary there. */
 export const LOG_TAIL_CHARS = 2_000_000
 
-/** `running` is true when a run was still going, which is no failure of the read and is not counted as an attempt. */
-export type FailedTestsRead = { ok: true; tests: string[] } | { ok: false; running: boolean }
+/**
+ * `running` is true when a run was still going, which is no failure of the read and is not counted as an attempt.
+ * `places` names, by test, the package or test file the logs printed before it; absent when they named none.
+ */
+export type FailedTestsRead =
+  | { ok: true; tests: string[]; places?: Record<string, string> }
+  | { ok: false; running: boolean }
 
 type RunGh = (args: string[]) => Promise<GhAnswer>
 
@@ -51,6 +56,13 @@ export const readFailedTests = async (
   const answers = await Promise.all(runIds.map((runId) => run(logArgs(runId))))
   const logs = answers.flatMap((answer) => (answer.ok ? [answer.stdout] : []))
   if (logs.length < answers.length) return { ok: false, running: false }
-  const tests = new Set(logs.flatMap((text) => extractFailedTests(text, pattern)))
-  return { ok: true, tests: [...tests].slice(0, FAILED_TEST_LIMIT) }
+  const scans = logs.map((text) => scanFailedTests(text, pattern))
+  const tests = [...new Set(scans.flatMap((scan) => scan.tests))].slice(0, FAILED_TEST_LIMIT)
+  const places = Object.fromEntries(
+    tests.flatMap((name) => {
+      const place = scans.find((scan) => scan.places[name] !== undefined)?.places[name]
+      return place === undefined ? [] : [[name, place]]
+    }),
+  )
+  return { ok: true, tests, ...(Object.keys(places).length > 0 && { places }) }
 }

package/src/watch/failures.ts

@@ -1,14 +1,21 @@
 import { CHECKS } from '../plans/pull-requests'
+import { isRecord } from '../shared/is-record'
 import type { FailedTestsRead } from './failure-read'
-import { isRecord } from './json-guards'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 
 /**
  * What the watcher read of a red pull request's logs: the tests that failed on `headCommit`. `read` is true once the
  * logs answered (with no test among them, too), `attempts` counts the reads tried, so a run that was still going when
- * it was asked is asked again, a few times, and no head commit is read more than once it has answered.
+ * it was asked is asked again, a few times, and no head commit is read more than once it has answered. `places` names,
+ * by test, the package or test file the log printed before it; absent in a state written before it was read.
  */
-export type FailureRecord = { headCommit: string; tests: string[]; read: boolean; attempts: number }
+export type FailureRecord = {
+  headCommit: string
+  tests: string[]
+  read: boolean
+  attempts: number
+  places?: Record<string, string>
+}
 
 /** Pull request number → what was read for it; kept for the open pull requests only. */
 export type FailureState = Record<string, FailureRecord>
@@ -27,13 +34,17 @@ export const FAILURE_RUN_LIMIT = 3
 
 export const emptyFailureState = (): FailureState => ({})
 
+const isPlaces = (value: unknown): boolean =>
+  value === undefined || (isRecord(value) && Object.values(value).every((place) => typeof place === 'string'))
+
 const isFailureRecord = (value: unknown): boolean =>
   isRecord(value) &&
   typeof value.headCommit === 'string' &&
   Array.isArray(value.tests) &&
   value.tests.every((test) => typeof test === 'string') &&
   typeof value.read === 'boolean' &&
-  typeof value.attempts === 'number'
+  typeof value.attempts === 'number' &&
+  isPlaces(value.places)
 
 export const isFailureState = (value: unknown): value is FailureState =>
   isRecord(value) && Object.values(value).every(isFailureRecord)
@@ -78,7 +89,14 @@ export const failureReadingOf = (
   result: FailedTestsRead,
 ): FailureReading =>
   result.ok
-    ? { number, headCommit, tests: result.tests, read: true, attempts: attempts + 1 }
+    ? {
+        number,
+        headCommit,
+        tests: result.tests,
+        read: true,
+        attempts: attempts + 1,
+        ...(result.places && { places: result.places }),
+      }
     : { number, headCommit, tests: [], read: false, attempts: result.running ? attempts : attempts + 1 }
 
 /**
@@ -105,3 +123,9 @@ export const failedTestsOf = (state: FailureState, number: number, headCommit: s
   const record = state[String(number)]
   return record?.headCommit === headCommit ? record.tests : []
 }
+
+/** The places of the failed tests read for `headCommit` of the pull request; none for any other head commit. */
+export const failedTestPlacesOf = (state: FailureState, number: number, headCommit: string): Record<string, string> => {
+  const record = state[String(number)]
+  return record?.headCommit === headCommit ? (record.places ?? {}) : {}
+}

package/src/watch/feedback.ts

@@ -1,5 +1,5 @@
+import { isRecord } from '../shared/is-record'
 import { FEEDBACK_FORM, type FeedbackForm, type FeedbackItem } from './feedback-item'
-import { isRecord } from './json-guards'
 import { isNoFindingComment, ROUND_WINDOW_MS } from './no-finding'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 

package/src/watch/gh-process.ts

@@ -7,9 +7,10 @@ export type GhAnswer = { ok: true; stdout: string } | { ok: false; error: string
  * `timeoutMs` ends a call that has not finished by then; without it the call waits as long as `gh` does.
  * `tailChars` keeps only that many characters from the end of the output: stdout is read as a stream and never held
  * whole, so memory stays near twice `tailChars` however much `gh` prints. `executable` replaces the `gh` that is run,
- * for a test that stands in for it.
+ * for a test that stands in for it. `stdin` is written to the process's standard input, for a request body too large for
+ * the command line.
  */
-export type GhOptions = { timeoutMs?: number; tailChars?: number; executable?: string }
+export type GhOptions = { timeoutMs?: number; tailChars?: number; executable?: string; stdin?: string }
 
 const readTail = async (stream: ReadableStream<Uint8Array>, tailChars: number): Promise<string> => {
   const decoder = new TextDecoder()
@@ -30,7 +31,12 @@ export const runGh = async (args: string[], cwd: string, options: GhOptions = {}
   let timedOut = false
   let timer: ReturnType<typeof setTimeout> | undefined
   try {
-    const child = Bun.spawn([options.executable ?? 'gh', ...args], { cwd, stdout: 'pipe', stderr: 'pipe' })
+    const child = Bun.spawn([options.executable ?? 'gh', ...args], {
+      cwd,
+      stdin: options.stdin === undefined ? 'ignore' : new Blob([options.stdin]),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
     if (options.timeoutMs !== undefined)
       timer = setTimeout(() => {
         timedOut = true

package/src/watch/json-guards.ts

@@ -1,6 +1,3 @@
-export const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
 /** The entries of a JSON array when every one passes `isValid`; throws `<source>: unexpected answer` otherwise. */
 export const parseArray = <T>(json: string, isValid: (entry: unknown) => entry is T, source: string): T[] => {
   const answer: unknown = JSON.parse(json)

package/src/watch/lane-fill.ts

@@ -1,6 +1,6 @@
 import type { ContextLevel, ContextReading } from '../context'
+import { isRecord } from '../shared/is-record'
 import { isContextLevel, levelStep } from './coordinator-fill'
-import { isRecord } from './json-guards'
 
 export const LANE_FILL_EVENT = 'lane'
 

package/src/watch/lane-model.ts

@@ -1,5 +1,5 @@
 import { differsFromColumn } from '../plan-format'
-import { isRecord } from './json-guards'
+import { isRecord } from '../shared/is-record'
 
 export const LANE_MODEL_EVENT = 'model'
 

package/src/watch/lane-parallel.ts

@@ -1,4 +1,4 @@
-import { isRecord } from './json-guards'
+import { isRecord } from '../shared/is-record'
 
 export const LANE_PARALLEL_EVENT = 'parallel'
 

package/src/watch/lane-progress.ts

@@ -32,23 +32,35 @@ export const watchedLaneProgress = async (
 }
 
 /**
- * The phases of a lane's plan (the plan of its newest row, as the lane's worktree has it, else as the base ref has
- * it) that can run together, by the plan's dependency table and ticks; empty without a plan, without a table or
- * without two such phases.
+ * The text of a lane's plan, the plan of its newest row, as the lane's worktree has it, else as the base ref has it;
+ * null without a row that links a plan or when neither has the file.
  */
-export const watchedLaneParallel = (
+export const watchedLanePlanText = (
   root: string,
   settings: PlansSettings,
   boardFile: string,
   lane: SprintLane,
-): string[] => {
+): string | null => {
   const href = lane.steps.filter((step) => step.planHref !== null).at(-1)?.planHref
-  if (!href) return []
+  if (!href) return null
   const path = resolvePlanPath(dirname(boardRepoPathOf(root, settings, boardFile)), href)
   const worktreeFile = join(worktreeOf(root, settings, lane.name), path)
-  const text = existsSync(worktreeFile)
+  return existsSync(worktreeFile)
     ? readFileSync(worktreeFile, 'utf8')
     : textAtBase(baseReaderOf(root, baseRefOf(settings)), path)
+}
+
+/**
+ * The phases of a lane's plan that can run together, by the plan's dependency table and ticks; empty without a plan,
+ * without a table or without two such phases.
+ */
+export const watchedLaneParallel = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  lane: SprintLane,
+): string[] => {
+  const text = watchedLanePlanText(root, settings, boardFile, lane)
   const groups = text === null ? null : parallelGroupsOfPlan(text, settings.planLanguage)
   return groups === null ? [] : parallelBatchOf(groups)
 }

package/src/watch/lane-report.ts

@@ -33,6 +33,8 @@ export type LaneReport = {
   progress: LaneProgress | null
   /** The context level last read for the lane's agent; null without a value. */
   context: ContextLevel | null
+  /** What a resting lane waits on, from its report (`restNote`); absent or null while it works or asks nothing. */
+  rest?: string | null
 }
 
 /** The board as the coordinator line reminds of it: its term and the rows only the checkout's board file has. */
@@ -75,13 +77,14 @@ const contextSegment = (level: ContextLevel | null): string[] =>
   level === null || level === CONTEXT_LEVEL.ok ? [] : [`context ${level}`]
 
 /**
- * One line per lane, in the words of `texts`: `<lane> <status> [· context warn|alert] · <branch>|no branch ·
+ * One line per lane, in the words of `texts`: `<lane> <status> [· context warn|alert] [· waits on: <question>, <n> open questions] · <branch>|no branch ·
  * PR #<n> <checks>|no PR · open phase …|phase … ticked, not merged|plan finished|no plan`.
  */
 export const laneReportLine = (report: LaneReport, texts: WatchTexts): string =>
   [
     `${terminalSafe(report.lane)} ${terminalSafe(report.status)}`,
     ...contextSegment(report.context),
+    ...(report.rest ? [terminalSafe(report.rest)] : []),
     report.branch ? terminalSafe(report.branch) : texts.noBranch,
     pullRequestSegment(report.pullRequest, texts),
     phaseSegment(report.progress, texts),
@@ -150,6 +153,7 @@ export const watchEventLine = (event: WatchEvent, target: string | null): string
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${terminalSafe(event.model)} · board ${terminalSafe(event.column)}`
   if (event.kind === WATCH_EVENT.laneParallel)
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${phasesText(event.phases)}`
+  if (event.kind === WATCH_EVENT.taskParallel) return `=== ${terminalSafe(event.line)}`
   if (event.kind === WATCH_EVENT.approval)
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${event.id} ${terminalSafe(event.tool)} · ${terminalSafe(event.summary)}`
   if (event.kind === WATCH_EVENT.coordinator) return `=== ${event.kind} ${event.level} ${contextLabel(event.share)}`

package/src/watch/lane-rest.ts

@@ -0,0 +1,28 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+import { questionCount, questionSections } from './report-questions'
+
+const LIST_MARKER = /^(?:\d+[.)]|[-*])\s*/
+const QUESTION_LENGTH = 60
+
+/** The first question as one line: list marker and bold out, made safe, cut. */
+const firstQuestion = (lines: readonly string[], start: number, end: number): string => {
+  const body = lines
+    .slice(start + 1, end)
+    .map((line) => line.trim().replace(LIST_MARKER, '').replaceAll('**', '').trim())
+    .find((line) => line !== '')
+  return ellipsize(terminalSafe(body ?? ''), QUESTION_LENGTH)
+}
+
+/**
+ * What a resting lane (idle or done) is waiting for, from its report: `waits on: <first question>, <n> open
+ * questions`; null without a report or without an open question, so a lane that has nothing to ask stays `idle`.
+ */
+export const restNote = (reportText: string | null): string | null => {
+  if (reportText === null) return null
+  const lines = reportText.split('\n')
+  const sections = questionSections(lines)
+  const [first] = sections
+  if (!first) return null
+  const count = questionCount(lines, sections)
+  return `waits on: ${firstQuestion(lines, first.start, first.end)}, ${count} open ${count === 1 ? 'question' : 'questions'}`
+}

package/src/watch/plan-badges.ts

@@ -1,6 +1,6 @@
 import { CHECKS } from '../plans/pull-requests'
-import { sanitisedFailedTests } from './failed-tests'
-import { failedTestsOf } from './failures'
+import { sanitisedFailedTestPlaces, sanitisedFailedTests } from './failed-tests'
+import { failedTestPlacesOf, failedTestsOf } from './failures'
 import { previewUrlOf } from './previews'
 import { PULL_REQUEST_STATE } from './pull-requests'
 import { lineText, type TicketRecord } from './sources'
@@ -16,6 +16,8 @@ export type PullRequestBadges = {
   changesRequested: boolean
   /** The tests a red run failed on this head commit, as the watcher read them from the run's log; absent reads as none. */
   failedTests?: string[]
+  /** By failed test, the package or test file the log printed before it; a test without an entry has no known place. */
+  failedTestPlaces?: Record<string, string>
 }
 
 /** The badges of a pull request the watcher shows nothing for. */
@@ -82,11 +84,16 @@ export const watchBadgesOf = (state: WatchState, now: number): WatchBadges => {
       const preview = state.previews.pullRequests[number]
       const feedback = state.feedback.pullRequests[number]
       const failedTests = checks === CHECKS.failed ? shownFailedTestsOf(state, number, headCommit) : []
+      const places = sanitisedFailedTestPlaces(
+        failedTestPlacesOf(state.failures, Number(number), headCommit),
+        failedTests,
+      )
       const badges = {
         preview: preview?.reportedHead === headCommit ? (preview.url ?? null) : null,
         feedback: feedback?.headCommit === headCommit ? feedback.count : 0,
         changesRequested: feedback?.changesRequested === true,
         ...(failedTests.length > 0 && { failedTests }),
+        ...(Object.keys(places).length > 0 && { failedTestPlaces: places }),
       }
       const shown = badges.preview !== null || badges.feedback > 0 || badges.changesRequested || failedTests.length > 0
       return shown ? [[number, badges]] : []

package/src/watch/previews.ts

@@ -1,6 +1,6 @@
+import { isRecord } from '../shared/is-record'
 import { type FeedbackTarget, isReadTime } from './feedback'
 import { FEEDBACK_FORM, type FeedbackItem } from './feedback-item'
-import { isRecord } from './json-guards'
 
 export const PREVIEW_EVENT = 'preview'
 

package/src/watch/pull-requests.ts

@@ -7,7 +7,8 @@ import {
   type GhPullRequest,
   isGhPullRequest,
 } from '../plans/pull-requests'
-import { isRecord, parseArray } from './json-guards'
+import { isRecord } from '../shared/is-record'
+import { parseArray } from './json-guards'
 
 /** The states of a pull request in `gh pr list --json state`. */
 export const PULL_REQUEST_STATE = { open: 'OPEN', merged: 'MERGED', closed: 'CLOSED' } as const

package/src/watch/source-path.ts

@@ -1,4 +1,4 @@
-import { isRecord } from './json-guards'
+import { isRecord } from '../shared/is-record'
 
 /**
  * Where a field sits in a source's JSON output: `.` is the whole output, else a chain of `.key`, `[n]` and `[-n]`

package/src/watch/sources.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto'
 import { terminalSafe } from '../plan-format/terminal-text'
-import { isRecord } from './json-guards'
+import { isRecord } from '../shared/is-record'
 import { previewUrlOf } from './previews'
 import { CONTENT_FIELDS, SOURCE_FIELD } from './source-fields'
 import { ROOT_PATH, type SourcePath, selectPath } from './source-path'

package/src/watch/stream-output.ts

@@ -5,11 +5,12 @@ import { type LaneSnapshot, NO_AGENT } from './lane-watch'
 import { WATCH_EVENT } from './watch-events'
 
 const SEPARATOR = ' · '
+const RESTING: ReadonlySet<string> = new Set([AGENT_STATUS.idle, AGENT_STATUS.done])
 
-/** `lane status`, a working lane with its note: `lane working: P12 7/12`. */
-const laneState = (lane: string, current: LaneSnapshot, notes: LaneNotes): string => {
+/** `lane status`, a working lane with its progress, a resting one with what it waits on: `lane idle: waits on: …`. */
+const laneState = (lane: string, current: LaneSnapshot, notes: LaneNotes, rests: LaneNotes): string => {
   const status = current[lane]?.status ?? NO_AGENT
-  const note = status === AGENT_STATUS.working ? notes[lane] : undefined
+  const note = status === AGENT_STATUS.working ? notes[lane] : RESTING.has(status) ? rests[lane] : undefined
   const head = `${terminalSafe(lane)} ${terminalSafe(status)}`
   return note === undefined ? head : `${head}: ${terminalSafe(note).replaceAll(SEPARATOR, ' / ')}`
 }
@@ -23,9 +24,13 @@ export const streamHeartbeatLine = (
   lanes: readonly string[],
   current: LaneSnapshot,
   notes: LaneNotes,
+  rests: LaneNotes = {},
+  waiting: string | null = null,
 ): string => {
-  const states = lanes.map((lane) => laneState(lane, current, notes))
-  return [`=== ${WATCH_EVENT.heartbeat} ${terminalSafe(time)}`, ...(states.length > 0 ? states : ['no lanes'])].join(
-    SEPARATOR,
-  )
+  const states = lanes.map((lane) => laneState(lane, current, notes, rests))
+  return [
+    `=== ${WATCH_EVENT.heartbeat} ${terminalSafe(time)}`,
+    ...(states.length > 0 ? states : ['no lanes']),
+    ...(waiting === null ? [] : [terminalSafe(waiting).replaceAll(SEPARATOR, ' / ')]),
+  ].join(SEPARATOR)
 }

package/src/watch/task-parallel-input.ts

@@ -0,0 +1,118 @@
+import { isPhaseFinished, isPhaseOpen, type PlanLanguage, type PlanPhase, parsePlanPhases } from '../plan-format'
+import { type PhaseDependency, parseDependencyTable } from '../plan-format/dependencies'
+import { matchSignals, type OpenPlanTask } from '../task-signals/matcher'
+import type { TaskSignal } from '../task-signals/types'
+import type { ActiveWork, OpenTask, TaskParallelInput } from './task-parallel'
+
+/** The tasks a lane could start from its plan: open items of the phases that are ready, with the writes of the table. */
+export type PlanTaskView = {
+  open: OpenPlanTask[]
+  doneCount: number
+  /** Phase id → the paths its row writes, `wie N` cells resolved; a phase whose set cannot be resolved has none. */
+  phaseWrites: Record<string, string[]>
+}
+
+const writeSetOf = (
+  row: PhaseDependency,
+  byId: ReadonlyMap<string, PhaseDependency>,
+  chain: readonly string[],
+): string[] | null => {
+  if (chain.includes(row.id)) return null
+  const like = row.writesLike.map((id) => {
+    const target = byId.get(id)
+    return target ? writeSetOf(target, byId, [...chain, row.id]) : null
+  })
+  return like.some((set) => set === null) ? null : [...row.writes, ...like.flatMap((set) => set ?? [])]
+}
+
+const phaseWritesOf = (rows: readonly PhaseDependency[]): Record<string, string[]> => {
+  const byId = new Map(rows.map((row) => [row.id, row]))
+  return Object.fromEntries(
+    rows.flatMap((row) => {
+      const writes = writeSetOf(row, byId, [])
+      return writes === null ? [] : [[row.id, writes]]
+    }),
+  )
+}
+
+const isReady = (row: PhaseDependency, doneIds: ReadonlySet<string>): boolean =>
+  !doneIds.has(row.id) && row.external.length === 0 && row.after.every((id) => doneIds.has(id))
+
+/** The phases whose tasks may start: ready by the dependency table, else the first open phase of a plan without one. */
+const readyPhaseIds = (phases: readonly PlanPhase[], table: readonly PhaseDependency[] | null): ReadonlySet<string> => {
+  const doneIds = new Set(phases.filter(isPhaseFinished).map(({ id }) => id))
+  if (table === null)
+    return new Set(
+      phases
+        .filter(isPhaseOpen)
+        .slice(0, 1)
+        .map(({ id }) => id),
+    )
+  return new Set(table.filter((row) => isReady(row, doneIds)).map(({ id }) => id))
+}
+
+const openTasksOf = (phase: PlanPhase): OpenPlanTask[] =>
+  phase.items.flatMap((item, taskIndex) =>
+    item.done || item.gate ? [] : [{ phaseId: phase.id, taskIndex, text: item.text }],
+  )
+
+/** The open tasks a lane could start from `markdown`, its ticked count and the writes of its phases. */
+export const planTaskViewOf = (markdown: string, language: PlanLanguage): PlanTaskView => {
+  const phases = parsePlanPhases(markdown, language)
+  const table = parseDependencyTable(markdown, language)
+  const ready = readyPhaseIds(phases, table)
+  return {
+    open: phases.filter(({ id }) => ready.has(id)).flatMap(openTasksOf),
+    doneCount: phases.reduce((count, phase) => count + phase.items.filter((item) => item.done).length, 0),
+    phaseWrites: table === null ? {} : phaseWritesOf(table),
+  }
+}
+
+export type TaskParallelFacts = {
+  lane: string
+  plan: PlanTaskView
+  /** What agents in the lane's worktree report they work on, the coordinator's subagents included. */
+  signals: readonly TaskSignal[]
+  /** Files the work in the lane's worktree wrote lately, relative to it. */
+  touchedFiles: readonly string[]
+  /** The lane's own agent is working, with or without a task report. */
+  laneWorking: boolean
+  baselineTokens: number
+  thresholdTokens: number
+}
+
+const activeWorkOf = (facts: TaskParallelFacts): ActiveWork[] => {
+  const matched = matchSignals(facts.plan.open, facts.signals)
+  const work: ActiveWork[] = matched.map(({ signal, task }) => ({
+    name: signal.agent,
+    files: [],
+    taskText: signal.text,
+    ...(task ? { phase: task.phaseId } : {}),
+  }))
+  if (work.length === 0 && facts.laneWorking) work.push({ name: facts.lane, files: [] })
+  const [first, ...rest] = work
+  return first ? [{ ...first, files: [...facts.touchedFiles] }, ...rest] : []
+}
+
+/** The tasks a running signal already works on are not open any more. */
+const openTasksWithout = (facts: TaskParallelFacts): OpenTask[] => {
+  const taken = new Set(
+    matchSignals(facts.plan.open, facts.signals).flatMap(({ task }) =>
+      task ? [`${task.phaseId}:${task.taskIndex}`] : [],
+    ),
+  )
+  return facts.plan.open
+    .filter((task) => !taken.has(`${task.phaseId}:${task.taskIndex}`))
+    .map(({ phaseId, text }) => ({ phase: phaseId, text }))
+}
+
+/** The input of the pure core from what the watcher read. */
+export const taskParallelInputOf = (facts: TaskParallelFacts): TaskParallelInput => ({
+  lane: facts.lane,
+  open: openTasksWithout(facts),
+  active: activeWorkOf(facts),
+  phaseWrites: facts.plan.phaseWrites,
+  doneCount: facts.plan.doneCount,
+  baselineTokens: facts.baselineTokens,
+  thresholdTokens: facts.thresholdTokens,
+})