jackherd 1.9.0 → 1.10.0

package/src/plans/selection.ts

@@ -1,6 +1,7 @@
 import { currentPhase, type LaneProgress } from '../plan-format'
 import { AGENT_STATUS } from '../terminal/types'
 import { chipUrlOf, isChipKey, planUrlOf } from './link-chips'
+import { TEXTS } from './texts'
 
 /**
  * Whether a lane is drawn open. It is decided once, when the lane first appears (`autoOpen`, by its status then), and
@@ -8,6 +9,10 @@ import { chipUrlOf, isChipKey, planUrlOf } from './link-chips'
  */
 export type LaneFold = { open: boolean }
 
+/** The blocks on top of the herd, by the name their fold is remembered under. */
+export const TOP_BLOCK = { waiting: 'waiting', appointments: 'appointments' } as const
+export type TopBlockId = (typeof TOP_BLOCK)[keyof typeof TOP_BLOCK]
+
 /**
  * The row under the cursor and the expanded phases, both as keys, whether ticked phases and items are
  * listed one by one or summed up in one line, whether the footer shows the symbol legend, and the
@@ -19,6 +24,8 @@ export type Selection = {
   showDone: boolean
   showLegend: boolean
   laneFolds: ReadonlyMap<string, LaneFold>
+  /** Per folded top block, the keys of its points seen when it was folded; a block that is open has no entry. */
+  blockFolds?: Readonly<Partial<Record<TopBlockId, ReadonlySet<string>>>>
 }
 
 /** A lane as the folds need it: its name and the status its agent reports, null without an agent. */
@@ -70,12 +77,25 @@ export const PLANNED_KEY = 'planned'
 
 export const phaseKey = (lane: string, stepIndex: number, phaseId: string): string => `${lane}:${stepIndex}:${phaseId}`
 
+const PHASE_KEY_SHAPE = '[^@>#]+:\\d+:[^:#>]+'
+
+const PHASE_KEY = new RegExp(`^${PHASE_KEY_SHAPE}$`)
+
+/** Whether a key names a phase: not a lane, row or task key, which carry `@`, `>` or `#`. */
+const isPhaseKey = (key: string): boolean => PHASE_KEY.test(key)
+
+/** The key of a lane's `next` row, which opens to the phases that wait. */
+export const nextKey = (lane: string): string => `next>${lane}`
+
+/** The key of a lane's `✓` row, which opens to the finished phases. */
+export const finishedKey = (lane: string): string => `done>${lane}`
+
 const TICKED_KEY_PREFIX = 'ticked>'
 
 /** The key of the "N ticked" line of an open phase; it is clicked only, and a click lands on the phase. */
 export const tickedKey = (phase: string): string => `${TICKED_KEY_PREFIX}${phase}`
 
-const ITEM_KEY = /^(.+:\d+:[^:#]+)#(\d+)$/
+const ITEM_KEY = new RegExp(`^(${PHASE_KEY_SHAPE})#(\\d+)$`)
 
 /**
  * The key of a task row: its phase's key and the task's index in `phase.items`; a click or Enter opens its text.
@@ -173,13 +193,10 @@ const foldLane = (selection: Selection, lane: string, next: (open: boolean) => b
   return { ...selection, laneFolds: new Map(selection.laneFolds).set(lane, { ...fold, open: next(fold.open) }) }
 }
 
-/** Opens a task and the phase it belongs to. */
-const openTaskWithPhase = (expanded: Set<string>, phase: string, task: string): void => {
-  expanded.add(phase)
-  expanded.add(task)
-}
-
-/** Selects a row and opens it, or closes it when it is already open: a phase shows its items, a lane its phases. */
+/**
+ * Selects the row under a click. A "N ticked" line flips `showDone` and selects its phase, a lane line flips the
+ * fold of its lane, any other row opens when closed and closes when open: a phase shows its items.
+ */
 export const applyClick = (selection: Selection, key: string): Selection => {
   const phase = tickedPhaseOfKey(key)
   if (phase !== null) return { ...selection, showDone: !selection.showDone, selected: phase }
@@ -187,7 +204,7 @@ export const applyClick = (selection: Selection, key: string): Selection => {
   if (lane !== null) return { ...foldLane(selection, lane, flipped), selected: key }
   const expanded = new Set(selection.expanded)
   const itemPhase = itemPhaseOfKey(key)
-  if (itemPhase !== null && !expanded.has(itemPhase)) openTaskWithPhase(expanded, itemPhase, key)
+  if (itemPhase !== null && !expanded.has(itemPhase)) addWithPhase(expanded, key)
   else toggleIn(expanded, key)
   return { ...selection, selected: key, expanded }
 }
@@ -197,17 +214,30 @@ const toggle = (selection: Selection, keys: readonly string[]): Selection => {
   return current ? applyClick(selection, current) : selection
 }
 
-const changeSelected = (selection: Selection, keys: readonly string[], next: (open: boolean) => boolean): Selection => {
+/** Adds a key to the expanded ones, with the phase of a task. */
+const addWithPhase = (expanded: Set<string>, key: string): void => {
+  expanded.add(key)
+  const itemPhase = itemPhaseOfKey(key)
+  if (itemPhase !== null) expanded.add(itemPhase)
+}
+
+const removeKey = (expanded: Set<string>, key: string): void => {
+  expanded.delete(key)
+}
+
+/** Applies a change to the selected row: `nextFold` to the fold of a lane, `change` to the expanded keys for any other row. */
+const changeSelected = (
+  selection: Selection,
+  keys: readonly string[],
+  nextFold: (open: boolean) => boolean,
+  change: (expanded: Set<string>, key: string) => void,
+): Selection => {
   const current = selectedKey(selection, keys)
   if (!current) return selection
   const lane = laneOfKey(current)
-  if (lane !== null) return { ...foldLane(selection, lane, next), selected: current }
+  if (lane !== null) return { ...foldLane(selection, lane, nextFold), selected: current }
   const expanded = new Set(selection.expanded)
-  if (next(expanded.has(current))) {
-    expanded.add(current)
-    const itemPhase = itemPhaseOfKey(current)
-    if (itemPhase !== null) expanded.add(itemPhase)
-  } else expanded.delete(current)
+  change(expanded, current)
   return { ...selection, selected: current, expanded }
 }
 
@@ -218,9 +248,59 @@ export const toggledExpansion = (selection: Selection, key: string): Selection =
   return { ...selection, expanded }
 }
 
-const expand = (selection: Selection, keys: readonly string[]): Selection => changeSelected(selection, keys, opened)
+/**
+ * Whether `block` is drawn folded: it was folded and every point now open was there then. A point that arrived since
+ * opens it again, so folding never hides something new. Each block remembers its own points.
+ */
+export const isBlockFolded = ({ blockFolds }: Selection, block: TopBlockId, keys: readonly string[]): boolean => {
+  const folded = blockFolds?.[block]
+  return folded !== undefined && keys.every((key) => folded.has(key))
+}
+
+/**
+ * The selection with the fold of each block forgotten that a new point opened, given the points each block holds now.
+ * Without it a block that opened for a new point would fold again by itself once that point is gone. The selection
+ * itself when no fold is forgotten.
+ */
+export const settledBlockFolds = (
+  selection: Selection,
+  keysOf: Readonly<Record<TopBlockId, readonly string[]>>,
+): Selection => {
+  const folds = selection.blockFolds ?? {}
+  const opened = Object.values(TOP_BLOCK).filter(
+    (block) => folds[block] !== undefined && !isBlockFolded(selection, block, keysOf[block]),
+  )
+  if (opened.length === 0) return selection
+  const kept = Object.fromEntries(Object.entries(folds).filter(([block]) => !opened.includes(block as TopBlockId)))
+  const { blockFolds: _forgotten, ...rest } = selection
+  return Object.keys(kept).length > 0 ? { ...rest, blockFolds: kept } : rest
+}
 
-const collapse = (selection: Selection, keys: readonly string[]): Selection => changeSelected(selection, keys, closed)
+/** The selection with `block` folded over the points `keys` when it was open, and open when it was folded. */
+export const toggledBlockFold = (selection: Selection, block: TopBlockId, keys: readonly string[]): Selection => {
+  if (!isBlockFolded(selection, block, keys)) {
+    return { ...selection, blockFolds: { ...selection.blockFolds, [block]: new Set(keys) } }
+  }
+  const { blockFolds, ...rest } = selection
+  const { [block]: _folded, ...otherFolds } = blockFolds ?? {}
+  return Object.keys(otherFolds).length > 0 ? { ...rest, blockFolds: otherFolds } : rest
+}
+
+const expand = (selection: Selection, keys: readonly string[]): Selection =>
+  changeSelected(selection, keys, opened, addWithPhase)
+
+const collapse = (selection: Selection, keys: readonly string[]): Selection =>
+  changeSelected(selection, keys, closed, removeKey)
+
+/**
+ * The line for a press of `a` that changes nothing on screen, null for any other input. The key lists the ticked
+ * tasks inside an expanded phase, so it needs one among the `keys` drawn.
+ */
+export const showDoneNotice = (selection: Selection, input: string, keys: readonly string[]): string | null => {
+  if (!isInput(INPUT.showDone, input)) return null
+  const phaseOpen = keys.some((key) => isPhaseKey(key) && selection.expanded.has(key))
+  return phaseOpen ? null : TEXTS.showDoneNeedsPhase
+}
 
 export const applyKey = (selection: Selection, input: string, keys: readonly string[]): Selection => {
   if (isInput(INPUT.up, input)) return move(selection, keys, -1)

package/src/plans/sent-files-read.ts

@@ -1,22 +1,13 @@
-import { join } from 'node:path'
-import { readRecords, writeRecordAtomically } from '../shared/private-records'
-import { isSentFileRecord, type SentFileRecord } from './sent-files'
+import { closableRecordLog } from './closable-records'
+import { isSentFileRecord } from './sent-files'
 
-const directoryOf = (root: string): string => join(root, '.jackherd', 'sent')
+const log = closableRecordLog('sent', isSentFileRecord, ({ sentAt }) => sentAt)
 
 /** Every record of the sent-file log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
-export const readSentRecords = (root: string): SentFileRecord[] =>
-  readRecords(directoryOf(root), isSentFileRecord, ({ sentAt }) => sentAt)
-
-const closeWhere = (root: string, isChosen: (record: SentFileRecord) => boolean, now: number): number => {
-  const open = readSentRecords(root).filter((record) => record.closedAt === null && isChosen(record))
-  for (const record of open) writeRecordAtomically(directoryOf(root), { ...record, closedAt: now })
-  return open.length
-}
+export const readSentRecords = log.read
 
 /** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
-export const closeSentRecords = (root: string, ids: readonly string[], now: number): number =>
-  closeWhere(root, (record) => ids.includes(record.id), now)
+export const closeSentRecords = log.close
 
 /** Marks every open record `closedAt` and returns how many it closed. */
-export const closeAllSentRecords = (root: string, now: number): number => closeWhere(root, () => true, now)
+export const closeAllSentRecords = log.closeAll

package/src/plans/sent-files.ts

@@ -1,8 +1,10 @@
 import { basename } from 'node:path'
-import { twoDigits } from '../plan-format/clock'
+import { clockText, DAY_MS } from '../plan-format/clock'
 import { terminalSafe } from '../plan-format/terminal-text'
-import type { WaitingItem } from '../plan-format/waiting'
+import { WAITING_KIND, type WaitingItem } from '../plan-format/waiting'
+import { isRecordId } from './record-id'
 import { laneDirectoryOf } from './unlisted-lanes'
+import { isStillWaiting } from './waiting-window'
 
 /** The record of a send of files to the user, as the kit hook `sent-file` writes it to `.jackherd/sent/`. */
 export type SentFileRecord = {
@@ -19,12 +21,8 @@ export type SentFileRecord = {
 /** A badge for a sent file: a `file:` address and the file's name. */
 export type SentChip = { url: string; label: string }
 
-const ID = /^[0-9a-f]{12}$/
 /** The address of a published artifact, as the hook reads it from the tool's answer, as a whole. */
 const ARTIFACT_ADDRESS = /^https:\/\/claude\.ai\/(?:code\/)?artifact\/[A-Za-z0-9_-]+$/
-const DAY_MS = 86_400_000
-/** A send waits on the user this long at most; the coordinator closes it earlier, with the answer. */
-const WAITING_DAYS = 3
 const SHOWN_PER_LANE = 5
 
 /** A published artifact is recorded by its address; a sent file by its path. */
@@ -49,7 +47,7 @@ export const isSentFileRecord = (value: unknown): value is SentFileRecord => {
   const record = value as Record<string, unknown>
   return (
     typeof record.id === 'string' &&
-    ID.test(record.id) &&
+    isRecordId(record.id) &&
     isStringArray(record.files) &&
     record.files.every(isRecordedFile) &&
     (record.caption === null || typeof record.caption === 'string') &&
@@ -96,18 +94,13 @@ export const sentChipsByLane = (
   return lanes
 }
 
-const clockText = (at: number): string => {
-  const date = new Date(at)
-  return `${twoDigits(date.getDate())}.${twoDigits(date.getMonth() + 1)}. ${twoDigits(date.getHours())}:${twoDigits(date.getMinutes())}`
-}
-
 const itemOf = (record: SentFileRecord): WaitingItem => {
   const [first] = record.files
   const more = record.files.length > 1 ? ` +${record.files.length - 1}` : ''
   return {
     since: clockText(record.sentAt),
     item: `${labelOf(first, record.caption)}${more}`,
-    kind: 'file',
+    kind: WAITING_KIND.file,
     id: record.id,
     open: true,
     url: addressOf(first),
@@ -117,5 +110,5 @@ const itemOf = (record: SentFileRecord): WaitingItem => {
 /** What the sends that no one closed wait on: one open item per record younger than three days, oldest first. */
 export const sentWaitingItems = (records: readonly SentFileRecord[], now: number): WaitingItem[] =>
   latestPerFile(records)
-    .filter(({ closedAt, sentAt }) => closedAt === null && now - sentAt <= WAITING_DAYS * DAY_MS)
+    .filter(({ closedAt, sentAt }) => isStillWaiting(closedAt, sentAt, now))
     .map(itemOf)

package/src/plans/settings.ts

@@ -9,7 +9,7 @@ export const CONFIG_PATH = PROJECT_CONFIG_PATH
 
 export type PlansSettings = Pick<
   JackherdConfig,
-  'planDirectory' | 'board' | 'worktreeDirectory' | 'baseBranch' | 'planLanguage' | 'responseLanguage'
+  'planDirectory' | 'board' | 'worktreeDirectory' | 'baseBranch' | 'planLanguage' | 'responseLanguage' | 'skillPrefix'
 > & {
   adapter: JackherdConfig['terminal']['adapter']
   fetchIntervalMinutes: number
@@ -30,6 +30,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   baseBranch: config.baseBranch,
   planLanguage: config.planLanguage,
   responseLanguage: config.responseLanguage,
+  skillPrefix: config.skillPrefix,
   adapter: config.terminal.adapter,
   fetchIntervalMinutes: config.plans.fetchIntervalMinutes,
   linkKinds: config.plans.linkKinds,

package/src/plans/signalled-phase.ts

@@ -0,0 +1,42 @@
+import { isPhaseOpen, type PhaseProgress, phaseLabel } from '../plan-format'
+import type { ActiveTask } from './active-tasks'
+
+/** `p24e` in a branch name, standing alone between separators: `feat/jackherd-p24e-task-signal`. */
+const BRANCH_PHASE = /(?:^|[^a-z0-9])p(\d+[a-z]?)(?![a-z0-9])/i
+
+/** The phase id a lane branch names (`feat/jackherd-p24e-task-signal` → `24e`); null for none. */
+export const branchPhaseId = (branch: string | null): string | null =>
+  branch?.match(BRANCH_PHASE)?.[1]?.toLowerCase() ?? null
+
+const newestStart = (tasks: readonly ActiveTask[]): number => Math.max(...tasks.map(({ startedAt }) => startedAt ?? 0))
+
+/** The open phase with the newest task an agent reported; null when no open phase has one. */
+const reportedPhase = (
+  phases: readonly PhaseProgress[],
+  reported: ReadonlyMap<string, readonly ActiveTask[]>,
+): PhaseProgress | null =>
+  phases
+    .filter((phase) => isPhaseOpen(phase) && (reported.get(phase.id)?.length ?? 0) > 0)
+    .reduce<PhaseProgress | null>(
+      (best, phase) =>
+        best && newestStart(reported.get(best.id) ?? []) >= newestStart(reported.get(phase.id) ?? []) ? best : phase,
+      null,
+    )
+
+/**
+ * The phase the lane says it works on (D112): the open phase with the newest reported task, else the open phase its
+ * branch names (`branchPhaseId`); null otherwise, and the ticks decide as before. A phase ticked to the end is never
+ * signalled, so a stale report or an old branch name cannot make finished work current.
+ */
+export const signalledPhase = (
+  phases: readonly PhaseProgress[],
+  reported: ReadonlyMap<string, readonly ActiveTask[]>,
+  branch: string | null,
+): PhaseProgress | null => {
+  const id = branchPhaseId(branch)
+  return reportedPhase(phases, reported) ?? phases.find((phase) => phase.id === id && isPhaseOpen(phase)) ?? null
+}
+
+/** The sidebar title of a lane: the signalled phase as `P24d · 1/5`, else `fromProgress` (`shortTitle`). */
+export const signalledTitle = (signalled: PhaseProgress | null, fromProgress: string | null): string | null =>
+  signalled ? `${phaseLabel(signalled.id)} · ${signalled.done}/${signalled.total}` : fromProgress

package/src/plans/signals-read.ts

@@ -2,7 +2,8 @@ import { readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { projectDirectoryOf } from '../context/session-log'
 import { MS_PER_MINUTE } from '../plan-format/clock'
-import { readClaudeSignals } from '../task-signals/claude-read'
+import { dropUnused, type StatCache } from '../shared/stat-cache'
+import { readClaudeSignals, type SignalCache } 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'
@@ -41,14 +42,21 @@ const recentSessionLogs = (project: string, notOlderThan: number): string[] => {
 /**
  * What agents report doing, as `TaskSignal`s: the tasks in progress in the recent Claude Code sessions of the main
  * checkout (the coordinator and its subagents) and of every worktree, and the open `jh task` records. Which lane a
- * signal belongs to is decided by its `cwd`, not by where it was read.
+ * signal belongs to is decided by its `cwd`, not by where it was read. A `cache` kept between calls spares parsing a
+ * log whose modification time and size did not change; logs this call did not look at are dropped from it.
  */
-export const readAllSignals = ({ projects, root, worktrees }: SignalSource, now: number): TaskSignal[] => {
+export const readAllSignals = (
+  { projects, root, worktrees }: SignalSource,
+  now: number,
+  cache: StatCache<TaskSignal[]> = new Map(),
+): TaskSignal[] => {
   const notOlderThan = now - STALE_ACTIVITY_MINUTES * MS_PER_MINUTE
+  const round: SignalCache = { entries: cache, used: new Set<string>() }
   const claude = [root, ...subdirectories(worktrees)].flatMap((directory) =>
     recentSessionLogs(join(projects, projectDirectoryOf(directory)), notOlderThan).flatMap((path) =>
-      readClaudeSignals(path, { notOlderThan }),
+      readClaudeSignals(path, { notOlderThan, cache: round }),
     ),
   )
+  dropUnused(round.entries, round.used)
   return [...claude, ...recordSignals(readTaskRecords(root))]
 }