jackherd 1.8.1 → 1.10.0

package/src/watch/stream-output.ts

@@ -5,27 +5,33 @@ 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, ' / ')}`
 }
 
 /**
  * The heartbeat of a stream, as one line, since every line of a stream reaches the coordinator as a
- * message of its own: `=== heartbeat <time> · <lane> <status> · …`.
+ * message of its own: `=== heartbeat <time> · <lane> <status> · …`. `standing` are the lines that stay until
+ * their cause is gone (what waits on the user, the main checkout behind its base), each one entry at the end.
  */
 export const streamHeartbeatLine = (
   time: string,
   lanes: readonly string[],
   current: LaneSnapshot,
   notes: LaneNotes,
+  rests: LaneNotes = {},
+  standing: readonly string[] = [],
 ): 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']),
+    ...standing.map((line) => terminalSafe(line).replaceAll(SEPARATOR, ' / ')),
+  ].join(SEPARATOR)
 }

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

@@ -0,0 +1,208 @@
+import { ALWAYS_ASK_PATHS, ENV_PATHS, MIGRATION_PATHS } from '../../kit/hooks/hooks/merge-guard/always-ask'
+import { MAX_AUTO_WINDOW_DAYS, windowDays } from '../config/auto-window'
+import type { JackherdConfig } from '../config/schema'
+import { twoDigits } from '../plan-format/clock'
+import {
+  AUTO_VERDICT,
+  type AutoVerdict,
+  GLOB_CHARACTER,
+  pathsOfTask,
+  type TaskParallelInput,
+  type TaskParallelProposal,
+} from './task-parallel'
+
+/** The window of `watch.parallelTasks.auto`: two `YYYY-MM-DD` days, both included. */
+export type AutoWindow = NonNullable<JackherdConfig['watch']['parallelTasks']['auto']>
+
+/** The switch, unset when the project has none, and every path a task may not name to start without a question. */
+export type AutoSettings = {
+  auto?: AutoWindow
+  askPaths: readonly string[]
+  /** `watch.parallelTasks.maxTokens` of the same config as the switch. */
+  maxTokens: number
+  /** Whether the repository holds a path of `DATA_PATHS` at or below a directory, relative to its root. */
+  holdsDataPath: (directory: string) => boolean
+}
+
+export const MAX_AUTO_EXTRA_AGENTS = 2
+
+/**
+ * The paths that always ask whose work takes effect before the merge: a migration may be pushed and a secret written
+ * while the pull request is open, so the merge guard comes too late. A directory of a writes set that holds one asks.
+ */
+export const DATA_PATHS: readonly string[] = [...MIGRATION_PATHS, ...ENV_PATHS]
+
+/**
+ * The paths that always ask (`ALWAYS_ASK_PATHS`, plus every package.json and CHANGELOG.md, which the merge guard
+ * reads apart): work on them is tier C and never starts without a question. The project's `guard.alwaysAsk` come on top.
+ */
+export const AUTO_ASK_PATHS: readonly string[] = [...ALWAYS_ASK_PATHS, '**/package.json', '**/CHANGELOG.md']
+
+const PROBE = 'x'
+/** Shorter literal pieces of a pattern (`**`, `*`) say nothing about a task's text. */
+const MIN_FRAGMENT = 3
+/**
+ * A path that may leave the repository or hide where it lies: absolute, from home, a variable, a drive, a backslash, or
+ * a `.` or `..` segment.
+ */
+const OUTSIDE_REPOSITORY = /^[/~]|^[A-Za-z]:|[\\%$]|(?:^|\/)\.{1,2}(?:\/|$)/
+
+/** Whether a path may leave the repository or hide where it lies (`OUTSIDE_REPOSITORY`). */
+export const leavesRepository = (path: string): boolean => OUTSIDE_REPOSITORY.test(path)
+
+const hasFileName = (path: string): boolean => /\.[^/]*$/.test(path.slice(path.lastIndexOf('/') + 1))
+
+/** A path up to the directory its first wildcard lies in; a path without one is itself. */
+const literalPrefix = (path: string): string => {
+  const glob = path.search(GLOB_CHARACTER)
+  return glob === -1 ? path : path.slice(0, Math.max(path.lastIndexOf('/', glob), 0))
+}
+
+/** Whether one path lies inside the other or both are the same; `''` is the whole repository. */
+const nested = (left: string, right: string): boolean =>
+  left === '' || right === '' || left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)
+
+const matchesAnyPattern = (path: string, patterns: readonly string[]): boolean => {
+  const lower = path.toLowerCase()
+  const globs = patterns.map((pattern) => new Bun.Glob(pattern.toLowerCase()))
+  return globs.some((glob) => glob.match(lower) || glob.match(`${lower}/${PROBE}`))
+}
+
+/**
+ * Whether a path a task names may touch a path that always asks. Only a named file inside a directory of the
+ * repository is matched (in lower case, as the merge guard does): a path that may leave the repository, a directory,
+ * a glob or a bare file name could reach such a path somewhere, so it counts as one. A dotted name is also matched as
+ * a directory, so `.claude` counts like `.claude/**`.
+ */
+export const touchesAskPath = (path: string, patterns: readonly string[]): boolean => {
+  if (OUTSIDE_REPOSITORY.test(path) || !path.includes('/') || GLOB_CHARACTER.test(path) || !hasFileName(path))
+    return true
+  return matchesAnyPattern(path, patterns)
+}
+
+/** Whether a path relative to the repository root is, or lies in, one of `DATA_PATHS`. */
+export const isDataPath = (path: string): boolean => matchesAnyPattern(path, DATA_PATHS)
+
+/**
+ * Whether an entry of a phase's writes set may touch a path that always asks: the whole repository, a path that may
+ * leave it, an entry a pattern matches as written (`packages/*\/package.json`), a directory or glob that overlaps a
+ * pattern anchored at the root (`.claude/**`), or one under whose literal part the repository holds a migration or an
+ * env file (`holdsDataPath`). Other patterns that hold anywhere (`**\/package.json`) are not looked for below a
+ * directory: their work waits for the merge guard.
+ */
+export const writesTouchAskPath = (
+  entry: string,
+  patterns: readonly string[],
+  holdsDataPath: (directory: string) => boolean,
+): boolean => {
+  if (entry === '' || OUTSIDE_REPOSITORY.test(entry)) return true
+  if (matchesAnyPattern(entry, patterns)) return true
+  if (!GLOB_CHARACTER.test(entry) && hasFileName(entry)) return false
+  const literal = literalPrefix(entry.toLowerCase())
+  const rootAnchored = patterns.filter((pattern) => !pattern.startsWith('**'))
+  return (
+    rootAnchored.some((pattern) => nested(literal, literalPrefix(pattern.toLowerCase()))) ||
+    holdsDataPath(literalPrefix(entry))
+  )
+}
+
+/** The literal pieces of the patterns (`.claude`, `package.json`, `migrations`), in lower case. */
+const fragmentsOf = (patterns: readonly string[]): string[] => [
+  ...new Set(
+    patterns.flatMap((pattern) =>
+      pattern
+        .toLowerCase()
+        .split(/[/*?[\]{}]+/)
+        .filter((piece) => piece.length >= MIN_FRAGMENT),
+    ),
+  ),
+]
+
+/** The local calendar day of `at`, as `YYYY-MM-DD`. */
+export const localDay = (at: number): string => {
+  const date = new Date(at)
+  return `${date.getFullYear()}-${twoDigits(date.getMonth() + 1)}-${twoDigits(date.getDate())}`
+}
+
+const windowRefusal = (auto: AutoWindow, today: string): string | null => {
+  if (!(windowDays(auto.since, auto.until) <= MAX_AUTO_WINDOW_DAYS))
+    return `window longer than ${MAX_AUTO_WINDOW_DAYS} days`
+  if (today < auto.since) return `off until ${auto.since}`
+  if (today > auto.until) return `ended ${auto.until}`
+  return null
+}
+
+const extraAgentsAtOnce = (input: TaskParallelInput, proposal: TaskParallelProposal): number =>
+  Math.max(input.active.length - 1, 0) + proposal.extraAgents
+
+const taskPathRefusal = (proposal: TaskParallelProposal, patterns: readonly string[]): string | null => {
+  const path = proposal.tasks.flatMap((task) => pathsOfTask(task.text)).find((entry) => touchesAskPath(entry, patterns))
+  return path === undefined ? null : `a task names ${path}, which always asks`
+}
+
+/** A task's text may name such a path without backticks or extension (`.husky/pre-commit`, `CODEOWNERS`). */
+const taskTextRefusal = (proposal: TaskParallelProposal, patterns: readonly string[]): string | null => {
+  const fragments = fragmentsOf(patterns)
+  const fragment = proposal.tasks
+    .map((task) => task.text.toLowerCase())
+    .flatMap((text) => fragments.filter((piece) => text.includes(piece)))[0]
+  return fragment === undefined ? null : `a task mentions ${fragment}, which always asks`
+}
+
+/**
+ * The task's text does not bind the subagent; its phase's writes set is what it may write, read from the plan at the
+ * base branch, so the lane's own copy widens nothing. A phase the base branch does not have asks.
+ */
+const phaseWritesRefusal = (input: TaskParallelInput, proposal: TaskParallelProposal, settings: AutoSettings) => {
+  for (const task of proposal.tasks) {
+    const writes = input.baseWrites[task.phase]
+    if (writes === undefined || writes.length === 0) return `phase ${task.phase} has no writes set on the base branch`
+    const entry = writes.find((path) => writesTouchAskPath(path, settings.askPaths, settings.holdsDataPath))
+    if (entry !== undefined)
+      return `phase ${task.phase} writes ${entry === '' ? 'the whole repository' : entry}, which always asks`
+  }
+  return null
+}
+
+const limitRefusal = (input: TaskParallelInput, proposal: TaskParallelProposal, settings: AutoSettings) => {
+  const { askPaths: patterns, maxTokens } = settings
+  if (input.active.length === 0) return 'no running work in the lane'
+  const atOnce = extraAgentsAtOnce(input, proposal)
+  if (atOnce > MAX_AUTO_EXTRA_AGENTS) return `${atOnce} extra agents at once, at most ${MAX_AUTO_EXTRA_AGENTS}`
+  if (proposal.estimateTokens >= Math.min(input.thresholdTokens, maxTokens)) return 'over the token limit'
+  return (
+    taskPathRefusal(proposal, patterns) ??
+    taskTextRefusal(proposal, patterns) ??
+    phaseWritesRefusal(input, proposal, settings)
+  )
+}
+
+/**
+ * Whether the coordinator may start `proposal` without asking: the switch holds on `today`, the lane has running work
+ * (the extra agents are its subagents, never a new lane), at most two extra agents run at once with the subagents
+ * already running, the cost stays under the limit, and neither a task's paths, its text nor its phase's writes set
+ * reaches a path that always asks. Every doubt asks.
+ */
+export const autoVerdict = (
+  input: TaskParallelInput,
+  proposal: TaskParallelProposal,
+  settings: AutoSettings,
+  today: string,
+): AutoVerdict => {
+  if (settings.auto === undefined) return { kind: AUTO_VERDICT.off }
+  const reason = windowRefusal(settings.auto, today) ?? limitRefusal(input, proposal, settings)
+  return reason === null ? { kind: AUTO_VERDICT.auto, until: settings.auto.until } : { kind: AUTO_VERDICT.asks, reason }
+}
+
+/**
+ * The line that the switch ended, once per last day: `ended` is the last day already reported (null before any), the
+ * answer the one to keep. Nothing while the switch holds or is unset.
+ */
+export const autoEndedReport = (
+  ended: string | null,
+  auto: AutoWindow | undefined,
+  today: string,
+): { ended: string | null; line: string | null } =>
+  auto === undefined || today <= auto.until || ended === auto.until
+    ? { ended, line: null }
+    : { ended: auto.until, line: `parallel tasks auto ended ${auto.until}: every proposal asks again` }

package/src/watch/task-parallel-data-paths.ts

@@ -0,0 +1,46 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { isDataPath, leavesRepository } from './task-parallel-auto'
+
+type Child = { path: string; searched: boolean }
+
+/** Directories a search below a writes entry skips: installed packages and the repository's own store. */
+const SKIPPED = new Set(['node_modules', '.git'])
+/** How many entries one search reads before it gives up; a directory larger than this counts as holding one. */
+const MAX_ENTRIES = 20_000
+
+/** The children of a directory below the root, none when it cannot be read; `searched` marks a directory to descend. */
+const childrenOf = (root: string, directory: string): Child[] => {
+  try {
+    return readdirSync(join(root, directory), { withFileTypes: true }).map((entry) => ({
+      path: directory === '' ? entry.name : `${directory}/${entry.name}`,
+      searched: entry.isDirectory() && !SKIPPED.has(entry.name),
+    }))
+  } catch {
+    return []
+  }
+}
+
+/** Whether a path below `relative` is a data path; `true` once the search has read more than `limit` entries. */
+const searchBelow = (root: string, relative: string, limit: number): boolean => {
+  const pending = [relative]
+  let read = 0
+  while (pending.length > 0) {
+    for (const child of childrenOf(root, pending.pop() ?? '')) {
+      read += 1
+      if (read > limit || isDataPath(child.path)) return true
+      if (child.searched) pending.push(child.path)
+    }
+  }
+  return false
+}
+
+/**
+ * `holdsDataPath` for the repository at `root`: whether a migration or an env file lies at or below a directory,
+ * read from the file system at each call. A path that may leave the repository counts, a directory that does not exist
+ * holds nothing, and a search that reads more than `limit` entries counts as a hit, so a doubt asks.
+ */
+export const holdsDataPathIn =
+  (root: string, limit: number = MAX_ENTRIES) =>
+  (directory: string): boolean =>
+    leavesRepository(directory) || isDataPath(directory) || searchBelow(root, directory, limit)

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

@@ -0,0 +1,108 @@
+import { isPhaseFinished, isPhaseOpen, type PlanLanguage, type PlanPhase, parsePlanPhases } from '../plan-format'
+import { type PhaseDependency, parseDependencyTable, writeSetOf } 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 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
+  /** The writes sets of the plan at the base branch; empty when the base branch has no such plan. */
+  baseWrites: Record<string, string[]>
+  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,
+  baseWrites: facts.baseWrites,
+  doneCount: facts.plan.doneCount,
+  baselineTokens: facts.baselineTokens,
+  thresholdTokens: facts.thresholdTokens,
+})

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

@@ -0,0 +1,151 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { firstAnswerTokens } from '../context/fill'
+import { agentLogPath, readHeadLines, readTailLines, TAIL_BYTES } from '../context/session-log'
+import type { SprintLane } from '../plan-format'
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { STALE_ACTIVITY_MINUTES } from '../plans/lane-summary'
+import { type PlansSettings, worktreeOf } from '../plans/settings'
+import { readClaudeSignals } from '../task-signals/claude-read'
+import { recordSignals } from '../task-signals/record'
+import { readTaskRecords } from '../task-signals/record-store'
+import type { TaskSignal } from '../task-signals/types'
+import { AGENT_STATUS, type LaneAgent } from '../terminal/types'
+import { baseLanePlanText, watchedLanePlanText } from './lane-progress'
+import type { TaskParallelInput } from './task-parallel'
+import { planTaskViewOf, taskParallelInputOf } from './task-parallel-input'
+import { isWithinWorktree, touchedFilesOf } from './task-parallel-touched'
+
+const RECENT_WRITE_MS = 30 * 60_000
+const HEAD_BYTES = 256 * 1024
+const SUBAGENT_LOG = /^agent-[A-Za-z0-9]+\.jsonl$/
+/** How many subagent logs of one session have their writes read, the newest first. */
+const MAX_SUBAGENT_LOGS = 20
+
+/** One agent's session: its log, the signals in it and its subagents, and the tails of the logs the writes are read from. */
+type AgentRead = { agent: LaneAgent; logPath: string | null; signals: TaskSignal[]; tails: string[][] }
+
+const modifiedAt = (path: string): number => {
+  try {
+    return statSync(path).mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+/** The newest `MAX_SUBAGENT_LOGS` subagent logs of a session, by modification time, so a long session bounds the read. */
+const subagentLogPaths = (logPath: string): string[] => {
+  const directory = join(logPath.replace(/\.jsonl$/, ''), 'subagents')
+  try {
+    return existsSync(directory)
+      ? readdirSync(directory)
+          .filter((name) => SUBAGENT_LOG.test(name))
+          .map((name) => ({ path: join(directory, name), modified: modifiedAt(join(directory, name)) }))
+          .sort((left, right) => right.modified - left.modified)
+          .slice(0, MAX_SUBAGENT_LOGS)
+          .map(({ path }) => path)
+      : []
+  } catch {
+    return []
+  }
+}
+
+const tailOf = (path: string): string[] => {
+  try {
+    return readTailLines(path, TAIL_BYTES)
+  } catch {
+    return []
+  }
+}
+
+const readAgent = (agent: LaneAgent, projectsDirectory: string | undefined, now: number): AgentRead => {
+  const logPath = agentLogPath(agent, projectsDirectory)
+  const notOlderThan = now - STALE_ACTIVITY_MINUTES * MS_PER_MINUTE
+  return {
+    agent,
+    logPath,
+    signals: logPath ? readClaudeSignals(logPath, { notOlderThan }) : [],
+    tails: logPath ? [logPath, ...subagentLogPaths(logPath)].map(tailOf) : [],
+  }
+}
+
+const baselineCache = new Map<string, number | null>()
+
+/**
+ * What a fresh agent carries before it has worked, measured as `jh context` measures a fill: the input of the first
+ * answer in a session log (system prompt, project instructions and the first request). The smallest honest source on
+ * hand: a log of a started session, not a guess; cached per log, since the head of a log never changes.
+ */
+const baselineOf = (logPath: string): number | null => {
+  if (!baselineCache.has(logPath)) {
+    try {
+      baselineCache.set(logPath, firstAnswerTokens(readHeadLines(logPath, HEAD_BYTES)))
+    } catch {
+      baselineCache.set(logPath, null)
+    }
+  }
+  return baselineCache.get(logPath) ?? null
+}
+
+const baselineFor = (lane: string, reads: readonly AgentRead[]): number | null => {
+  const own = reads.find(({ agent }) => agent.name === lane)
+  const sources = [own, ...reads.filter((read) => read !== own)]
+  for (const read of sources) {
+    const tokens = read?.logPath ? baselineOf(read.logPath) : null
+    if (tokens !== null) return tokens
+  }
+  return null
+}
+
+const uniqueSignals = (signals: readonly TaskSignal[]): TaskSignal[] => [
+  ...new Map(signals.map((signal) => [`${signal.agent}|${signal.text}`, signal])).values(),
+]
+
+export type TaskParallelSources = {
+  root: string
+  settings: PlansSettings
+  boardFile: string
+  thresholdTokens: number
+  now: number
+  /** Where Claude Code keeps its session logs; the user's by default. */
+  projectsDirectory?: string
+}
+
+/**
+ * The input of the parallel-task check for each of `lanes`, read from the plan of the lane's newest row, the sessions
+ * of every listed agent (a lane's work, and the coordinator's subagents in the lane's worktree) and the records of
+ * `jh task`. A lane without a plan, without a token baseline, without a task left or without active work (a working
+ * agent, a running subagent or an open record in its worktree) is not in the answer.
+ */
+export const readTaskParallelInputs = (
+  lanes: readonly SprintLane[],
+  agents: readonly LaneAgent[],
+  sources: TaskParallelSources,
+): Record<string, TaskParallelInput> => {
+  const reads = agents.map((agent) => readAgent(agent, sources.projectsDirectory, sources.now))
+  const records = recordSignals(readTaskRecords(sources.root))
+  const since = sources.now - RECENT_WRITE_MS
+  return Object.fromEntries(
+    lanes.flatMap((lane) => {
+      const text = watchedLanePlanText(sources.root, sources.settings, sources.boardFile, lane)
+      const baselineTokens = baselineFor(lane.name, reads)
+      if (text === null || baselineTokens === null) return []
+      const worktree = worktreeOf(sources.root, sources.settings, lane.name)
+      const signals = uniqueSignals([...reads.flatMap((read) => read.signals), ...records]).filter((signal) =>
+        isWithinWorktree(signal.cwd, worktree),
+      )
+      const baseText = baseLanePlanText(sources.root, sources.settings, sources.boardFile, lane)
+      const input = taskParallelInputOf({
+        lane: lane.name,
+        plan: planTaskViewOf(text, sources.settings.planLanguage),
+        baseWrites: baseText === null ? {} : planTaskViewOf(baseText, sources.settings.planLanguage).phaseWrites,
+        signals,
+        touchedFiles: reads.flatMap((read) => read.tails.flatMap((tail) => touchedFilesOf(tail, worktree, since))),
+        laneWorking: agents.some((agent) => agent.name === lane.name && agent.status === AGENT_STATUS.working),
+        baselineTokens,
+        thresholdTokens: sources.thresholdTokens,
+      })
+      return input.open.length === 0 || input.active.length === 0 ? [] : [[lane.name, input]]
+    }),
+  )
+}

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

@@ -0,0 +1,39 @@
+import { isAbsolute, relative } from 'node:path'
+import { parseLogEntry } from '../context/session-log'
+import { isRecord } from '../shared/is-record'
+
+const WRITING_TOOLS: ReadonlySet<string> = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
+
+const writtenPathsOf = (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' || !WRITING_TOOLS.has(String(block.name))) return []
+    const input = isRecord(block.input) ? block.input : {}
+    const path = input.file_path ?? input.notebook_path
+    return typeof path === 'string' ? [path] : []
+  })
+}
+
+const insideWorktree = (path: string, worktree: string): string | null => {
+  const inside = relative(worktree, path)
+  return inside === '' || inside.startsWith('..') || isAbsolute(inside) ? null : inside
+}
+
+/** Whether `path` is the worktree or lies below it. */
+export const isWithinWorktree = (path: string, worktree: string): boolean =>
+  insideWorktree(path, worktree) !== null || path === worktree
+
+/**
+ * The files the log lines show written (`Edit`, `Write`, `MultiEdit`, `NotebookEdit`) at or after `sinceMs` inside
+ * `worktree`, relative to it and without repeats, in order of first write. A path outside the worktree, a line that is
+ * no JSON and a write without a time are left out.
+ */
+export const touchedFilesOf = (lines: readonly string[], worktree: string, sinceMs: number): string[] => {
+  const touched = lines.flatMap((line) => {
+    const entry = parseLogEntry(line)
+    const time = typeof entry?.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
+    if (!entry || Number.isNaN(time) || time < sinceMs) return []
+    return writtenPathsOf(entry).flatMap((path) => insideWorktree(path, worktree) ?? [])
+  })
+  return [...new Set(touched)]
+}