jackherd 1.9.0 → 1.11.0

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

@@ -1,5 +1,5 @@
 import { isPhaseFinished, isPhaseOpen, type PlanLanguage, type PlanPhase, parsePlanPhases } from '../plan-format'
-import { type PhaseDependency, parseDependencyTable } from '../plan-format/dependencies'
+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'
@@ -12,24 +12,11 @@ export type PlanTaskView = {
   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, [])
+      const writes = writeSetOf(row, byId)
       return writes === null ? [] : [[row.id, writes]]
     }),
   )
@@ -77,6 +64,8 @@ export type TaskParallelFacts = {
   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
 }
@@ -112,6 +101,7 @@ export const taskParallelInputOf = (facts: TaskParallelFacts): TaskParallelInput
   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

@@ -11,7 +11,7 @@ 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 { watchedLanePlanText } from './lane-progress'
+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'
@@ -134,9 +134,11 @@ export const readTaskParallelInputs = (
       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),

package/src/watch/task-parallel.ts

@@ -2,8 +2,11 @@ import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
 
 export const TASK_PARALLEL_EVENT = 'parallel tasks'
 
-/** A proposal for the non-stream watcher: the line `formatTaskParallelLine` made for `lane`. */
-export type TaskParallelEvent = { kind: typeof TASK_PARALLEL_EVENT; lane: string; line: string }
+/**
+ * A proposal: the line `formatTaskParallelLine` made for `lane`; with `lane` null, the line that the switch
+ * `watch.parallelTasks.auto` ended.
+ */
+export type TaskParallelEvent = { kind: typeof TASK_PARALLEL_EVENT; lane: string | null; line: string }
 
 /** Lane → the fingerprint last seen at a heartbeat; a lane without an entry has had none. */
 export type TaskParallelFingerprints = Record<string, string>
@@ -25,6 +28,8 @@ export type TaskParallelInput = {
   active: ActiveWork[]
   /** Phase id → the paths of its writes cell; `''` is the whole repository. Absent for a phase without one. */
   phaseWrites: Record<string, string[]>
+  /** The same from the plan at the base branch, which the lane cannot change; what an `auto` mark trusts. */
+  baseWrites: Record<string, string[]>
   doneCount: number
   /** Tokens a fresh agent costs before it does anything, measured by the caller. */
   baselineTokens: number
@@ -45,11 +50,22 @@ export type TaskParallelResult =
 
 export type TaskParallelProposal = Extract<TaskParallelResult, { proposed: true }>
 
+export const AUTO_VERDICT = { auto: 'auto', off: 'off', asks: 'asks' } as const
+
+/**
+ * Whether a proposal starts without a question (`task-parallel-auto.ts`): `auto` with the switch's last day, `off`
+ * without a switch, `asks` with the limit that held it back.
+ */
+export type AutoVerdict =
+  | { kind: typeof AUTO_VERDICT.auto; until: string }
+  | { kind: typeof AUTO_VERDICT.off }
+  | { kind: typeof AUTO_VERDICT.asks; reason: string }
+
 const MIN_TASKS_BESIDE_AGENT = 1
 const MIN_TASKS_WITHOUT_AGENT = 2
 const TEXT_LIMIT = 60
 const TOKENS_PER_K = 1000
-const GLOB_CHARACTER = /[*?[{]/
+export const GLOB_CHARACTER = /[*?[{]/
 const LINE_SUFFIX = /(?::\d+(?:[-:]\d+)*|#L\d+.*)$/
 const PATH_EXTENSIONS = 'ts|tsx|js|mjs|json|md|sh|yml|yaml|css|html|toml|sql'
 const BARE_FILE = new RegExp(`(?<![\\w./\`-])[\\w./-]+\\.(?:${PATH_EXTENSIONS})(?::\\d+(?:[-:]\\d+)*)?(?![\\w/])`, 'g')
@@ -194,13 +210,26 @@ export const taskParallelReport = (
 }
 
 const CHECKBOX = /^\s*(?:[-*]\s*)?\[[ xX]\]\s*/
+/** The separators of the line itself, so a task's text cannot fake a mark such as `· auto until`. */
+const SEPARATORS = /[·∥]/g
 
 const proposalTaskText = (text: string): string =>
-  ellipsize(terminalSafe(text.replace(/\s+/g, ' ')).replace(CHECKBOX, '').replaceAll('"', "'").trim(), TEXT_LIMIT)
+  ellipsize(
+    terminalSafe(text.replace(/\s+/g, ' ')).replace(CHECKBOX, '').replaceAll('"', "'").replace(SEPARATORS, '-').trim(),
+    TEXT_LIMIT,
+  )
+
+const autoSuffix = (verdict: AutoVerdict): string => {
+  if (verdict.kind === AUTO_VERDICT.auto) return ` · auto until ${verdict.until}`
+  return verdict.kind === AUTO_VERDICT.asks ? ` · asks: ${terminalSafe(verdict.reason)}` : ''
+}
 
-/** `parallel tasks <lane>: "<a>" ∥ "<b>" · ~<n>k tokens for 1 extra agent`, one line. */
-export const formatTaskParallelLine = (lane: string, proposal: TaskParallelProposal): string => {
+/**
+ * `parallel tasks <lane>: "<a>" ∥ "<b>" · ~<n>k tokens for 1 extra agent`, one line; under a set switch it ends in
+ * `· auto until <day>` or `· asks: <the limit that held>`.
+ */
+export const formatTaskParallelLine = (lane: string, proposal: TaskParallelProposal, verdict: AutoVerdict): string => {
   const tasks = proposal.tasks.map((task) => `"${proposalTaskText(task.text)}"`).join(' ∥ ')
   const agents = proposal.extraAgents === 1 ? 'agent' : 'agents'
-  return `parallel tasks ${proposalTaskText(lane)}: ${tasks} · ~${kilo(proposal.estimateTokens)} tokens for ${proposal.extraAgents} extra ${agents}`
+  return `parallel tasks ${proposalTaskText(lane)}: ${tasks} · ~${kilo(proposal.estimateTokens)} tokens for ${proposal.extraAgents} extra ${agents}${autoSuffix(verdict)}`
 }

package/src/watch/task-signal-missing.ts

@@ -0,0 +1,69 @@
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { isRecord } from '../shared/is-record'
+
+export const NO_TASK_SIGNAL_EVENT = 'no task signal'
+
+/** The key a lane without a current phase is reported under, so it too is reported once. */
+const NO_PHASE = ''
+
+/** What the heartbeat read of a lane: whether its agent works, whether a task signal is open, its current phase. */
+export type NoSignalReading = { working: boolean; signalled: boolean; phaseId: string | null }
+
+/**
+ * Per lane: since when it works without a signal (null while it does not), and the phase it was last reported for
+ * (`''` for a lane without a phase, null before any report).
+ */
+export type NoSignalState = Record<string, { since: number | null; reported: string | null }>
+
+export type NoTaskSignalEvent = { kind: typeof NO_TASK_SIGNAL_EVENT; lane: string; phaseId: string | null }
+
+type LaneEntry = NoSignalState[string]
+
+const nextEntry = (
+  previous: LaneEntry | undefined,
+  { working, signalled }: NoSignalReading,
+  now: number,
+): LaneEntry => ({
+  since: working && !signalled ? (previous?.since ?? now) : null,
+  reported: previous?.reported ?? null,
+})
+
+const isDue = (entry: LaneEntry, phaseKey: string, now: number, limitMinutes: number): boolean =>
+  entry.since !== null && now - entry.since >= limitMinutes * MS_PER_MINUTE && entry.reported !== phaseKey
+
+/**
+ * The lanes that worked `limitMinutes` or longer without a task signal (`jh task start` or an entry of their own task
+ * list), one event per lane and phase (D112): a signal or a lane that stops working starts the clock again, a phase
+ * already reported is not reported again, a new one is. A lane without a reading keeps what it had.
+ */
+export const noTaskSignalEvents = (
+  previous: NoSignalState,
+  readings: Readonly<Record<string, NoSignalReading>>,
+  now: number,
+  limitMinutes: number,
+): { events: NoTaskSignalEvent[]; state: NoSignalState } => {
+  const events: NoTaskSignalEvent[] = []
+  const state: NoSignalState = { ...previous }
+  for (const [lane, reading] of Object.entries(readings)) {
+    const entry = nextEntry(previous[lane], reading, now)
+    const phaseKey = reading.phaseId ?? NO_PHASE
+    if (isDue(entry, phaseKey, now, limitMinutes)) {
+      events.push({ kind: NO_TASK_SIGNAL_EVENT, lane, phaseId: reading.phaseId })
+      entry.reported = phaseKey
+    }
+    state[lane] = entry
+  }
+  return { events, state }
+}
+
+/** The line the coordinator reads: `lane <name> no task signal` with the phase when one is known. */
+export const noTaskSignalLine = ({ lane, phaseId }: NoTaskSignalEvent): string =>
+  `lane ${lane} ${NO_TASK_SIGNAL_EVENT}${phaseId === null ? '' : ` (P${phaseId})`}`
+
+const isEntry = (value: unknown): boolean =>
+  isRecord(value) &&
+  (value.since === null || typeof value.since === 'number') &&
+  (value.reported === null || typeof value.reported === 'string')
+
+export const isNoSignalState = (value: unknown): value is NoSignalState =>
+  isRecord(value) && Object.values(value).every(isEntry)

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

@@ -0,0 +1,29 @@
+import { join } from 'node:path'
+import { defaultProjectsDirectory } from '../context/session-log'
+import { laneOfDirectory } from '../plans/active-tasks'
+import { readAllSignals } from '../plans/signals-read'
+
+export type SignalSources = {
+  /** The main checkout, which holds `.jackherd/tasks/`. */
+  root: string
+  /** The lanes' worktree directory, relative to `root`. */
+  worktreeDirectory: string
+  now: number
+  /** Where Claude Code keeps its session logs; the user's by default. */
+  projectsDirectory?: string
+}
+
+/**
+ * The lanes with an open task signal, read as the herd reads them (`readAllSignals`, the lane by the signal's
+ * directory): a task in progress in a recent session of the lane's worktree, a subagent's among them, or an open
+ * `jh task` record whose directory lies in that worktree.
+ */
+export const signalledLanes = (lanes: readonly string[], sources: SignalSources): Set<string> => {
+  const worktrees = join(sources.root, sources.worktreeDirectory)
+  const signals = readAllSignals(
+    { projects: sources.projectsDirectory ?? defaultProjectsDirectory(), root: sources.root, worktrees },
+    sources.now,
+  )
+  const signalled = new Set(signals.flatMap(({ cwd }) => laneOfDirectory(cwd, worktrees) ?? []))
+  return new Set(lanes.filter((lane) => signalled.has(lane)))
+}

package/src/watch/texts.ts

@@ -26,8 +26,14 @@ export type WatchTexts = {
   laneModelDuty: string
   /** What phases of one lane that can run together ask of the coordinator, with the phases as `P19 ∥ P20`. */
   parallelDuty: (phases: string) => string
+  /** What a lane that works without a task signal asks of the coordinator. */
+  noTaskSignalDuty: string
   /** What a lane's call waiting for approval asks of the coordinator, with the mark (request id and call hash) the question must carry. */
   approvalDuty: (id: string, hash: string) => string
+  /** The standing duty while the main checkout is behind its base branch on the remote (`origin/main`), with the count of commits. */
+  mainCheckoutBehind: (remoteBase: string, count: number) => string
+  /** The standing duty while the main checkout has another branch than the base checked out (null for a detached head). */
+  mainCheckoutOffBase: (branch: string | null, baseBranch: string) => string
   /** The reminder after the coordinator line: `<term>: <count> rows only in the checkout`. */
   checkoutRows: (term: string, count: number) => string
   /** The head of the status line of the user's own open pull requests without a lane. */
@@ -63,8 +69,12 @@ export const watchTexts = (dialogLanguage: PlanLanguage): WatchTexts => ({
   laneAlertDuty: 'request the hand-over at the next phase boundary (§ 8)',
   parallelDuty: (phases) =>
     `${phases} can run in parallel: propose it to the user, check content and release files yourself (the table covers paths and markers only)`,
+  noTaskSignalDuty: 'remind the lane to report its task with jh task start; do not stop it',
   laneModelDuty:
     'switch it while idle: /exit, then claude --resume <session> --model <id> in the same pane (§ 2 step 6)',
+  mainCheckoutBehind: (remoteBase, count) =>
+    `main checkout behind ${remoteBase} by ${count} (git merge --ff-only ${remoteBase})`,
+  mainCheckoutOffBase: (branch, baseBranch) => `main checkout on ${branch ?? 'a detached head'}, not ${baseBranch}`,
   checkoutRows: (term, count) => `${term}: ${count} ${count === 1 ? 'row' : 'rows'} only in the checkout`,
   otherPullRequests: 'other PRs',
   approvalDuty: (id, hash) =>

package/src/watch/update-available.ts

@@ -1,26 +1,29 @@
 import { latestVersionIfDue, type UpdateCheck } from '../sync/if-changed'
 import { isNewerVersion } from '../version/release'
+import { UPDATE_AVAILABLE_EVENT } from './watch-events'
 
 /** The one line that wakes the coordinator when npm has a newer release; the orchestrate skill asks the user. */
 export const updateAvailableLine = (installed: string, latest: string): string =>
-  `=== update available ${installed} → ${latest}`
+  `=== ${UPDATE_AVAILABLE_EVENT} ${installed} → ${latest}`
 
 /**
  * The watcher's daily look at npm, on the hook's timestamp and check, so a day holds one registry question across
  * both. Prints a line only for a newer plain release it has not announced yet; otherwise nothing, so a quiet
- * day costs no tokens. Call it on every poll: the timestamp decides whether npm is asked at all.
+ * day costs no tokens. Call it on every poll: the timestamp decides whether npm is asked at all. `hint` is what the line
+ * carries after it, the path of the reference that holds the handling (`referenceHint`).
  */
 export const updateAnnouncer = (
   home: string,
   installed: string,
   check: UpdateCheck,
   log: (line: string) => void,
+  hint: () => string = () => '',
 ): (() => Promise<void>) => {
   let announced: string | null = null
   return async () => {
     const latest = await latestVersionIfDue(home, check)
     if (latest === null || latest === announced || !isNewerVersion(latest, installed)) return
     announced = latest
-    log(updateAvailableLine(installed, latest))
+    log(`${updateAvailableLine(installed, latest)}${hint()}`)
   }
 }

package/src/watch/watch-events.ts

@@ -24,8 +24,17 @@ import {
   type TaskParallelEvent,
   type TaskParallelFingerprints,
 } from './task-parallel'
+import {
+  isNoSignalState,
+  NO_TASK_SIGNAL_EVENT,
+  type NoSignalState,
+  type NoTaskSignalEvent,
+} from './task-signal-missing'
 import { RUN_EVENT, RUN_STATUS, type WorkflowRun } from './workflow-runs'
 
+/** The event `updateAvailableLine` prints; it is no `WatchEvent`, the announcer logs it on its own. */
+export const UPDATE_AVAILABLE_EVENT = 'update available'
+
 /** What the coordinator is told besides a lane that stopped. The values are the words of the report. */
 export const WATCH_EVENT = {
   merged: 'merged',
@@ -41,6 +50,7 @@ export const WATCH_EVENT = {
   laneModel: LANE_MODEL_EVENT,
   laneParallel: LANE_PARALLEL_EVENT,
   taskParallel: TASK_PARALLEL_EVENT,
+  noTaskSignal: NO_TASK_SIGNAL_EVENT,
   approval: APPROVAL_EVENT,
   source: SOURCE_EVENT,
   due: APPOINTMENT_EVENT.due,
@@ -95,12 +105,18 @@ export type WatchState = {
   laneParallels: LaneParallels
   /** The fingerprint of the parallel-task situation of each watched lane at the last heartbeat; a proposal is made only when it moved. */
   taskParallels: TaskParallelFingerprints
+  /** The last day of `watch.parallelTasks.auto` whose end was reported, so it is said once; null before any. */
+  parallelAutoEnded: string | null
+  /** Per watched lane: since when it works without a task signal and the phase last reported as `no task signal`. */
+  noTaskSignals: NoSignalState
   /** The ids of the approval requests on disk when they were last read, each reported once while it is open. */
   approvals: string[]
   /** Per configured source of `watch.sources`: the entries seen (`[id, fingerprint]`) and the start of a failure streak. */
   sources: SourceState
   /** Lane → change time of the report file last shown for it, null when it had none; a lane without an entry is unseen. */
   reportMtimes: Record<string, number | null>
+  /** Lane → the questions of its report last shown or seen (`questionsFingerprint`); a lane without an entry is unseen. */
+  reportQuestions: Record<string, string>
   /** The lane lines of the status block last printed; null before the first report. */
   statusLines: string[] | null
   /** The board's appointments reported as due and its unreadable appointment rows reported, each once (`appointments.ts`). */
@@ -149,6 +165,7 @@ export type WatchEvent =
   | LaneModelEvent
   | LaneParallelEvent
   | TaskParallelEvent
+  | NoTaskSignalEvent
   | ApprovalEvent
   | SourceEvent
   | AppointmentEvent
@@ -184,9 +201,12 @@ export const emptyWatchState = (): WatchState => ({
   laneModels: {},
   laneParallels: {},
   taskParallels: {},
+  parallelAutoEnded: null,
+  noTaskSignals: {},
   approvals: [],
   sources: emptySourceState(),
   reportMtimes: {},
+  reportQuestions: {},
   statusLines: null,
   appointments: emptyAppointmentState(),
 })
@@ -230,10 +250,13 @@ const isWatchState = (value: Record<string, unknown>): value is WatchState =>
   isLaneModels(value.laneModels) &&
   isLaneParallels(value.laneParallels) &&
   isTaskParallelFingerprints(value.taskParallels) &&
+  (value.parallelAutoEnded === null || typeof value.parallelAutoEnded === 'string') &&
+  isNoSignalState(value.noTaskSignals) &&
   Array.isArray(value.approvals) &&
   value.approvals.every((id) => typeof id === 'string') &&
   isSourceState(value.sources) &&
   everyValue(value.reportMtimes, isSeq) &&
+  everyValue(value.reportQuestions, (entry) => typeof entry === 'string') &&
   (value.statusLines === null ||
     (Array.isArray(value.statusLines) && value.statusLines.every((line) => typeof line === 'string'))) &&
   isAppointmentState(value.appointments)