jackherd 1.8.1 → 1.10.0

package/src/watch/task-parallel.ts

@@ -0,0 +1,235 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+
+export const TASK_PARALLEL_EVENT = 'parallel tasks'
+
+/**
+ * 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>
+
+export const isTaskParallelFingerprints = (value: unknown): value is TaskParallelFingerprints =>
+  typeof value === 'object' &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.values(value).every((entry) => typeof entry === 'string')
+
+export type OpenTask = { text: string; phase: string }
+
+/** One agent's recent work: the files it touched, its active task text and phase when the signal names them. */
+export type ActiveWork = { name: string; files: string[]; taskText?: string; phase?: string }
+
+export type TaskParallelInput = {
+  lane: string
+  open: OpenTask[]
+  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
+  /** A proposal is made only when the estimate stays below this. */
+  thresholdTokens: number
+}
+
+export type TaskParallelResult =
+  | { proposed: false; reason: string }
+  | {
+      proposed: true
+      tasks: OpenTask[]
+      waiting: number
+      extraAgents: number
+      estimateTokens: number
+      reason: string
+    }
+
+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
+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')
+const BACKTICKED = /`([^`]+)`/g
+const FILE_LIKE = new RegExp(`/|\\.(?:${PATH_EXTENSIONS})$|^\\.[\\w-]+`)
+
+const normalise = (entry: string): string | null => {
+  const trimmed = entry.trim()
+  if (trimmed === '' || /\s/.test(trimmed)) return null
+  const path = trimmed.replace(LINE_SUFFIX, '').replace(/^\.\//, '').replace(/\/+$/, '')
+  return FILE_LIKE.test(path) && path !== '' ? path : null
+}
+
+/**
+ * The paths a task line names: backticked entries that look like a path or file name and bare file names with a known
+ * extension. `:line` suffixes and `./` are cut, globs stay globs, duplicates drop. A task naming none is unknown, and
+ * unknown is never proposed.
+ */
+export const pathsOfTask = (text: string): string[] => {
+  const backticked = [...text.matchAll(BACKTICKED)].map((match) => match[1] ?? '')
+  const bare = text.replace(BACKTICKED, ' ').match(BARE_FILE) ?? []
+  return [...new Set([...backticked, ...bare].map(normalise).filter((path): path is string => path !== null))]
+}
+
+const literalPrefix = (path: string): string => {
+  const glob = path.search(GLOB_CHARACTER)
+  return glob === -1 ? path : path.slice(0, Math.max(path.lastIndexOf('/', glob), 0))
+}
+
+const isInside = (inner: string, outer: string): boolean =>
+  outer === '' || inner === outer || inner.startsWith(`${outer}/`)
+
+const holdsName = (name: string, path: string): boolean => `/${path}/`.includes(`/${name}/`) || path === name
+
+/**
+ * Whether two paths may touch the same files. Directories contain what lies below them, a glob stands for the
+ * directory its literal part ends in, `''` is the whole repository, and a bare name matches that name in any directory.
+ * When unsure the answer is yes.
+ */
+export const pathsOverlap = (left: string, right: string): boolean => {
+  const [a, b] = [literalPrefix(left), literalPrefix(right)]
+  const bareLeft = !left.includes('/') && !GLOB_CHARACTER.test(left) && left !== ''
+  const bareRight = !right.includes('/') && !GLOB_CHARACTER.test(right) && right !== ''
+  if (bareLeft || bareRight) {
+    const [name, other] = bareLeft ? [left, right] : [right, left]
+    return GLOB_CHARACTER.test(other) ? true : other === '' || holdsName(name, other)
+  }
+  return isInside(a, b) || isInside(b, a)
+}
+
+const clash = (left: readonly string[], right: readonly string[]): boolean =>
+  left.some((a) => right.some((b) => pathsOverlap(a, b)))
+
+const activeFootprint = (input: TaskParallelInput): string[] =>
+  input.active.flatMap((work) => [
+    ...work.files,
+    ...pathsOfTask(work.taskText ?? ''),
+    ...(work.phase === undefined ? [] : (input.phaseWrites[work.phase] ?? [])),
+  ])
+
+const estimateTokens = (input: TaskParallelInput, taskCount: number): { extraAgents: number; tokens: number } => {
+  const extraAgents = input.active.length > 0 ? taskCount : taskCount - 1
+  return { extraAgents, tokens: input.baselineTokens * extraAgents }
+}
+
+const kilo = (tokens: number): string => `${Math.round(tokens / TOKENS_PER_K)}k`
+
+/** The first group of open tasks, in plan order, whose paths clash neither with the running work nor with each other. */
+const parallelGroup = (input: TaskParallelInput): OpenTask[] => {
+  const running = activeFootprint(input)
+  const chosen: { task: OpenTask; paths: string[] }[] = []
+  for (const task of input.open) {
+    const paths = pathsOfTask(task.text)
+    const free = paths.length > 0 && !clash(paths, running) && chosen.every((other) => !clash(paths, other.paths))
+    if (free) chosen.push({ task, paths })
+  }
+  return chosen.map(({ task }) => task)
+}
+
+/**
+ * Open tasks that could start now beside the running work: no path overlap with it or with each other, none without a
+ * named path. Proposed for one task beside running work or two tasks without, and when the baseline cost of the extra agents stays below the
+ * threshold; the reason says in plain words which way it went.
+ */
+export const proposeTaskParallel = (input: TaskParallelInput): TaskParallelResult => {
+  const tasks = parallelGroup(input)
+  const needed = input.active.length > 0 ? MIN_TASKS_BESIDE_AGENT : MIN_TASKS_WITHOUT_AGENT
+  if (tasks.length < needed) return { proposed: false, reason: 'no task can run beside another' }
+  const { extraAgents, tokens } = estimateTokens(input, tasks.length)
+  if (tokens >= input.thresholdTokens)
+    return {
+      proposed: false,
+      reason: `~${kilo(tokens)} tokens for ${extraAgents} extra agents is not below the ${kilo(input.thresholdTokens)} limit`,
+    }
+  return {
+    proposed: true,
+    tasks,
+    waiting: input.open.length,
+    extraAgents,
+    estimateTokens: tokens,
+    reason: `${tasks.length} of ${input.open.length} waiting tasks name disjoint paths that the running work does not touch; ~${kilo(tokens)} tokens for ${extraAgents} extra ${extraAgents === 1 ? 'agent' : 'agents'}`,
+  }
+}
+
+const FNV_OFFSET = 0x811c9dc5
+const FNV_PRIME = 0x01000193
+
+const hash = (text: string): string => {
+  let value = FNV_OFFSET
+  for (const character of text) {
+    value = Math.imul(value ^ (character.codePointAt(0) ?? 0), FNV_PRIME) >>> 0
+  }
+  return value.toString(16).padStart(8, '0')
+}
+
+/**
+ * A stable fingerprint of what decides a proposal: ticks, active tasks and open tasks, order-independent. Files an
+ * agent touches are left out, they move on every keystroke and would repeat the report.
+ */
+export const taskParallelFingerprint = (input: TaskParallelInput): string =>
+  hash(
+    JSON.stringify([
+      input.lane,
+      input.doneCount,
+      input.active.map((work) => `${work.phase ?? ''}|${work.taskText ?? ''}`).sort(),
+      input.open.map((task) => `${task.phase}|${task.text}`).sort(),
+    ]),
+  )
+
+/**
+ * The proposal to report this heartbeat, if any: only when the fingerprint moved since `previous`, and only a real
+ * proposal. The returned fingerprint is what the caller keeps for the next heartbeat, proposal or not.
+ */
+export const taskParallelReport = (
+  previous: string | undefined,
+  input: TaskParallelInput,
+): { fingerprint: string; proposal: TaskParallelProposal | null } => {
+  const fingerprint = taskParallelFingerprint(input)
+  if (fingerprint === previous) return { fingerprint, proposal: null }
+  const result = proposeTaskParallel(input)
+  return { fingerprint, proposal: result.proposed ? result : null }
+}
+
+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('"', "'").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; 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}${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/waiting-line.ts

@@ -0,0 +1,19 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+import type { WaitingItem } from '../plan-format/waiting'
+import { shownWithMore } from '../plans/shown-with-more'
+
+const SHOWN_ITEMS = 3
+const ITEM_LENGTH = 40
+
+const itemText = ({ item }: WaitingItem): string => ellipsize(terminalSafe(item).replace(/\s+/g, ' '), ITEM_LENGTH)
+
+/**
+ * The line that brings back what waits on the user's answer, in every heartbeat and status until the item is closed:
+ * `for you (<n>): <item>; …`, three items and `+<n>` for the rest. Null when no item is open.
+ */
+export const waitingLine = (items: readonly WaitingItem[]): string | null => {
+  const open = items.filter(({ open: isOpen }) => isOpen)
+  if (open.length === 0) return null
+  const { shown, more } = shownWithMore(open, SHOWN_ITEMS)
+  return `for you (${open.length}): ${[...shown.map(itemText), ...(more > 0 ? [`+${more}`] : [])].join('; ')}`
+}

package/src/watch/watch-events.ts

@@ -1,4 +1,5 @@
 import { CHECKS, type ChecksState } from '../plans/pull-requests'
+import { isRecord } from '../shared/is-record'
 import {
   APPOINTMENT_EVENT,
   type AppointmentEvent,
@@ -10,7 +11,6 @@ import { APPROVAL_EVENT, type ApprovalEvent } from './approvals'
 import { type CoordinatorLevel, type CoordinatorReading, isContextLevel, levelStep } from './coordinator-fill'
 import { emptyFailureState, type FailureState, failedTestsOf, isFailureState } from './failures'
 import { emptyFeedbackState, FEEDBACK_EVENT, type FeedbackEvent, type FeedbackState, isFeedbackState } from './feedback'
-import { isRecord } from './json-guards'
 import { isLaneLevels, LANE_FILL_EVENT, type LaneFillEvent, type LaneLevels } from './lane-fill'
 import { isLaneModels, LANE_MODEL_EVENT, type LaneModelEvent, type LaneModels } from './lane-model'
 import { isLaneParallels, LANE_PARALLEL_EVENT, type LaneParallelEvent, type LaneParallels } from './lane-parallel'
@@ -18,8 +18,23 @@ import { type LaneSnapshot, type SeenSeqs, seenSeqsOf } from './lane-watch'
 import { emptyPreviewState, isPreviewState, PREVIEW_EVENT, type PreviewEvent, type PreviewState } from './previews'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 import { emptySourceState, isSourceState, SOURCE_EVENT, type SourceEvent, type SourceState } from './sources'
+import {
+  isTaskParallelFingerprints,
+  TASK_PARALLEL_EVENT,
+  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',
@@ -34,6 +49,8 @@ export const WATCH_EVENT = {
   laneFill: LANE_FILL_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,
@@ -86,12 +103,20 @@ export type WatchState = {
   laneModels: LaneModels
   /** The phases last reported as able to run together for each watched lane; a lane without two has none. */
   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`). */
@@ -139,6 +164,8 @@ export type WatchEvent =
   | LaneFillEvent
   | LaneModelEvent
   | LaneParallelEvent
+  | TaskParallelEvent
+  | NoTaskSignalEvent
   | ApprovalEvent
   | SourceEvent
   | AppointmentEvent
@@ -173,9 +200,13 @@ export const emptyWatchState = (): WatchState => ({
   laneLevels: {},
   laneModels: {},
   laneParallels: {},
+  taskParallels: {},
+  parallelAutoEnded: null,
+  noTaskSignals: {},
   approvals: [],
   sources: emptySourceState(),
   reportMtimes: {},
+  reportQuestions: {},
   statusLines: null,
   appointments: emptyAppointmentState(),
 })
@@ -218,10 +249,14 @@ const isWatchState = (value: Record<string, unknown>): value is WatchState =>
   isLaneLevels(value.laneLevels) &&
   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)

package/src/watch/watcher-lock.ts

@@ -1,7 +1,15 @@
 import { createHash } from 'node:crypto'
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { basename, join } from 'node:path'
+import { rmSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import {
+  ensurePrivateLevels,
+  type LocationSystem,
+  readPrivateText,
+  runtimeBaseOf,
+  systemLocation,
+  userDirectoryOf,
+} from '../shared/private-location'
 import { CLI_NAME, PACKAGE_NAME } from '../version/release'
 
 /** Looks up the command line of a process; null when there is no such process. */
@@ -17,8 +25,6 @@ const RUNTIME = 'bun'
 const DIRECTORY_PREFIX = 'jackherd-watch'
 const KEY_HASH_LENGTH = 12
 const NOT_A_SEGMENT = /[^A-Za-z0-9._-]+/g
-const PRIVATE_DIRECTORY = 0o700
-const PRIVATE_FILE = 0o600
 const STOP_WAIT_MS = 5_000
 const STOP_POLL_MS = 50
 
@@ -73,14 +79,6 @@ export const repositoryKey = (root: string): string => {
   return `${name}-${hash}`
 }
 
-const readText = (file: string): string | null => {
-  try {
-    return readFileSync(file, 'utf8')
-  } catch {
-    return null
-  }
-}
-
 const commandLineOf: CommandLineOf = (pid) => {
   const result = Bun.spawnSync(['ps', '-o', 'command=', '-p', String(pid)], { stdout: 'pipe', stderr: 'ignore' })
   return result.exitCode === 0 ? result.stdout.toString().trim() || null : null
@@ -96,36 +94,34 @@ const isAlive = (pid: number): boolean => {
 }
 
 /** Where `ensureWatcherDirectory` puts the watcher's files, without creating anything: for readers such as the herd. */
-export const watcherDirectoryOf = (root: string): string =>
-  join(tmpdir(), `${DIRECTORY_PREFIX}-${process.getuid?.() ?? 'user'}`, repositoryKey(root))
+export const watcherDirectoryOf = (root: string, system: LocationSystem = systemLocation()): string =>
+  join(userDirectoryOf(runtimeBaseOf(system), DIRECTORY_PREFIX, system.uid), repositoryKey(root))
 
 /**
  * The directory for the lock and state of the watcher of the repository at `root`, one per user and repository,
- * readable by that user only: with `TMPDIR` unset, `tmpdir()` is the shared `/tmp`, where another account could
- * plant the files. A watcher in another repository has its own lock and does not supersede this one.
+ * readable by that user only: without a private runtime directory the base is the temporary directory, which may be
+ * the shared `/tmp`, where another account could plant the files, so both levels are verified (`ensurePrivateLevels`)
+ * and this throws for a level that is a link or someone else's. A watcher in another repository has its own lock and
+ * does not supersede this one.
  */
-export const ensureWatcherDirectory = (root: string): string => {
-  const directory = watcherDirectoryOf(root)
-  mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
-  return directory
+export const ensureWatcherDirectory = (root: string, system: LocationSystem = systemLocation()): string => {
+  const directory = watcherDirectoryOf(root, system)
+  return ensurePrivateLevels(dirname(directory), directory)
 }
 
 /** Whether the lock names a live process that is a watcher, so its saved state is being kept up to date. */
 export const isWatcherRunning = (lockFile: string, lookUp: CommandLineOf = commandLineOf): boolean => {
-  const pid = lockedPid(readText(lockFile))
+  const pid = lockedPid(readPrivateText(lockFile))
   return pid !== null && isAlive(pid) && isWatcherCommand(lookUp(pid) ?? '')
 }
 
-/** Writes a file only the user can read. */
-export const writePrivate = (file: string, content: string) => writeFileSync(file, content, { mode: PRIVATE_FILE })
-
 /**
  * Takes the lock for this process. A watcher that held it gets SIGTERM and is waited for, so the state
  * file it writes on the way out is complete before this one reads it.
  */
 export const takeOverLock = async (lockFile: string): Promise<TakeOver> => {
-  const previous = supersedeTarget(readText(lockFile), process.pid, commandLineOf)
-  writePrivate(lockFile, String(process.pid))
+  const previous = supersedeTarget(readPrivateText(lockFile), process.pid, commandLineOf)
+  writePrivateFile(lockFile, String(process.pid))
   if (previous === null || !isAlive(previous)) return { replaced: null, stillRunning: null }
   try {
     process.kill(previous, 'SIGTERM')
@@ -137,9 +133,9 @@ export const takeOverLock = async (lockFile: string): Promise<TakeOver> => {
   return isAlive(previous) ? { replaced: null, stillRunning: previous } : { replaced: previous, stillRunning: null }
 }
 
-export const stopNoticeOf = (lockFile: string): string => stopNotice(readText(lockFile), process.pid)
+export const stopNoticeOf = (lockFile: string): string => stopNotice(readPrivateText(lockFile), process.pid)
 
 /** Removes the lock only while it still names this process; a successor's lock stays. */
 export const releaseLock = (lockFile: string) => {
-  if (lockedPid(readText(lockFile)) === process.pid) rmSync(lockFile, { force: true })
+  if (lockedPid(readPrivateText(lockFile)) === process.pid) rmSync(lockFile, { force: true })
 }

package/src/watch/workflow-runs.ts

@@ -1,7 +1,8 @@
 import type { JackherdConfig } from '../config'
 import { GITHUB_HOST } from '../plans/github'
 import { runIdOfLink } from '../plans/pull-requests'
-import { isRecord, parseArray } from './json-guards'
+import { isRecord } from '../shared/is-record'
+import { parseArray } from './json-guards'
 
 /** Which workflow's runs are deploys, and which environments count as their target (`watch.deploy`). */
 export type DeployConfig = NonNullable<JackherdConfig['watch']['deploy']>

package/kit/hooks/hooks/merge-guard/plan-approval-record.ts

@@ -1,23 +0,0 @@
-// PostToolUse hook for AskUserQuestion, shipped by jackherd. When the call asked about a plan (``Plan `<path>` ``) and
-// offered the label that approves it or the one that revokes it, it leaves a pointer to that dialog in the main
-// checkout's `.jackherd/approvals/plans/`, so the merge guard finds the answer again after the session ended. It writes
-// only the pointer; the merge guard reads the answer from the transcript itself. argv[2] and argv[3] are the two labels,
-// rendered into the hook entry by `sync`. It never blocks and prints nothing: a pointer it fails to write costs a question.
-// The other way round it costs a revocation: when no pointer is written for a "revoke" answer, the merge guard never
-// sees that answer, and an older approval keeps holding until the next plan question that is recorded.
-import { mainCheckoutOf } from '../shared/checkout'
-import { planPointersDirectory, pointerOf, writePointer } from './plan-pointers'
-
-const record = async (): Promise<void> => {
-  const pointer = pointerOf(JSON.parse(await Bun.stdin.text()), process.argv.slice(2, 4), Date.now())
-  if (pointer === undefined) return
-  const projectDirectory = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
-  writePointer(planPointersDirectory(mainCheckoutOf(projectDirectory)), pointer)
-}
-
-try {
-  await record()
-} catch {
-  // Nothing to do: without a pointer the merge asks.
-}
-process.exit(0)