jackherd 1.11.1 → 1.12.0

package/src/plans/status-pace.ts

@@ -0,0 +1,45 @@
+import type { LaneStatus } from './layout'
+
+/** What `git status` tells the herd about a worktree. */
+export type BranchStatus = Pick<LaneStatus, 'branch' | 'dirty'>
+
+/** The last `git status` of a worktree, with the stamp of the worktree it was asked at and when (epoch milliseconds). */
+export type KeptStatus = { stamp: string; at: number; status: BranchStatus }
+
+/** Where and when a status is asked: the worktree, its stamp (`worktreeStamp`) and the time. */
+export type StatusAsk = { worktree: string; stamp: string; now: number }
+
+/**
+ * How long a kept `git status` holds while its worktree's stamp stays the same: a change made by hand, which moves
+ * neither the index nor HEAD nor an agent's log, shows within this time.
+ */
+export const STATUS_PACE = { maxAgeMs: 60_000 } as const
+
+/** How much of an agent's last log line the stamp keeps: its end carries the entry's id and time. */
+const LOG_MARK_CHARS = 200
+
+const isFresh = (kept: KeptStatus | undefined, { stamp, now }: StatusAsk): kept is KeptStatus =>
+  kept !== undefined && kept.stamp === stamp && now - kept.at < STATUS_PACE.maxAgeMs
+
+/** What the agent's log (its last lines, as the herd read them) says of its latest entry; empty without a log. */
+export const logMark = (lines: readonly string[] | null): string => {
+  if (!lines) return ''
+  const last = lines.at(-1) ?? ''
+  return `${lines.length}:${last.length}:${last.slice(-LOG_MARK_CHARS)}`
+}
+
+/**
+ * The status of `ask.worktree`: the kept one while its stamp is unchanged and younger than `STATUS_PACE.maxAgeMs`,
+ * else `read` asked again and kept in `kept` with the stamp and time.
+ */
+export const pacedStatus = async (
+  kept: Map<string, KeptStatus>,
+  ask: StatusAsk,
+  read: () => Promise<BranchStatus>,
+): Promise<BranchStatus> => {
+  const previous = kept.get(ask.worktree)
+  if (isFresh(previous, ask)) return previous.status
+  const status = await read()
+  kept.set(ask.worktree, { stamp: ask.stamp, at: ask.now, status })
+  return status
+}

package/src/plans/subagent-tasks.ts

@@ -29,7 +29,7 @@ const startsWithName = (description: string, name: string): boolean =>
 
 /**
  * The open task each subagent works on, from the short name its description starts with (`/implement` Step 0b, case
- * ignored): it gets its `▶` like a reported task, one per task however many subagents share it. A ticked task and a
+ * ignored): it gets its `●` like a reported task, one per task however many subagents share it. A ticked task and a
  * review gate item take none; a subagent whose description starts with no name stays where it was.
  */
 export const subagentTaskPlacements = (

package/src/plans/subagents-read.ts

@@ -1,6 +1,6 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { defaultProjectsDirectory, projectDirectoryOf, readTailLines } from '../context/session-log'
+import { defaultProjectsDirectory, followTailLines, projectDirectoryOf } from '../context/session-log'
 import { MS_PER_MINUTE } from '../plan-format/clock'
 import { DEFAULT_SKILL_PREFIX } from '../sync/init'
 import { readApprovalRequests } from '../watch/approvals'
@@ -48,10 +48,24 @@ const directoriesOf = (path: string): string[] => {
   }
 }
 
-/** The entry names of `path`; none when it is missing or cannot be read. */
+/** How many directories keep their listing: one `subagents` directory per session, a few hundred in a busy project. */
+const LISTED_DIRECTORIES = 2048
+
+const listings = new Map<string, { modifiedAt: number; names: string[] }>()
+
+/**
+ * The entry names of `path`, listed again only when the directory changed since (a file added or removed moves its
+ * modification time, a write into a file does not); none when it is missing or cannot be read.
+ */
 const namesIn = (path: string): string[] => {
   try {
-    return readdirSync(path)
+    const modifiedAt = statSync(path).mtimeMs
+    const kept = listings.get(path)
+    if (kept?.modifiedAt === modifiedAt) return kept.names
+    const names = readdirSync(path)
+    if (listings.size >= LISTED_DIRECTORIES) listings.clear()
+    listings.set(path, { modifiedAt, names })
+    return names
   } catch {
     return []
   }
@@ -63,22 +77,23 @@ const logOf = (directory: string, name: string, id: string, now: number): Subage
     const modifiedAt = statSync(logPath).mtimeMs
     if (now - modifiedAt > SUBAGENT_STALE_MINUTES * MS_PER_MINUTE) return []
     const meta: unknown = JSON.parse(readFileSync(join(directory, name), 'utf8'))
-    return [{ id, meta, modifiedAt, tail: readTailLines(logPath, TAIL_BYTES) }]
+    return [{ id, meta, modifiedAt, tail: followTailLines(logPath, TAIL_BYTES) }]
   } catch {
     return []
   }
 }
 
-/** The subagent logs of every session in one project directory. */
-const sessionLogsOf = (project: string, now: number): SubagentLog[] =>
-  directoriesOf(project).flatMap((session) => {
-    const directory = join(project, session, 'subagents')
-    return namesIn(directory).flatMap((name) => {
-      const id = META_FILE.exec(name)?.[1]
-      return id ? logOf(directory, name, id, now) : []
-    })
+/** The subagent logs of one session's `subagents` directory. */
+const logsInSession = (directory: string, now: number): SubagentLog[] =>
+  namesIn(directory).flatMap((name) => {
+    const id = META_FILE.exec(name)?.[1]
+    return id ? logOf(directory, name, id, now) : []
   })
 
+/** The `subagents` directory of every session in one project directory. */
+const sessionDirectoriesOf = (project: string): string[] =>
+  directoriesOf(project).map((session) => join(project, session, 'subagents'))
+
 /**
  * The project directories Claude Code keeps for sessions started in the main checkout `root` and, when
  * `worktreeDirectory` is given, in a worktree below it: a lane's own subagents, its reviews among them, live there.
@@ -89,6 +104,10 @@ const projectDirectoriesOf = (projects: string, root: string, worktreeDirectory?
   return directoriesOf(projects).filter((name) => name === main || (lanes !== null && name.startsWith(lanes)))
 }
 
+/** The `subagents` directory of every session of the main checkout and its worktrees. */
+const allSessionDirectories = (projects: string, root: string, worktreeDirectory?: string): string[] =>
+  projectDirectoriesOf(projects, root, worktreeDirectory).flatMap((name) => sessionDirectoriesOf(join(projects, name)))
+
 /**
  * The subagents with a recently written log in the sessions started in the main checkout `root` and its worktrees,
  * from Claude Code's `<projects>/<project>/<session>/subagents/agent-<id>.{meta.json,jsonl}`; whatever cannot be read
@@ -100,7 +119,7 @@ export const readSubagentLogs = (
   now: number,
   worktreeDirectory?: string,
 ): SubagentLog[] =>
-  projectDirectoriesOf(projects, root, worktreeDirectory).flatMap((name) => sessionLogsOf(join(projects, name), now))
+  allSessionDirectories(projects, root, worktreeDirectory).flatMap((directory) => logsInSession(directory, now))
 
 /** The names the gate holds an open request under, as the watcher reads them. */
 const heldNames = (root: string, now: number): Set<string> =>
@@ -110,22 +129,40 @@ const heldNames = (root: string, now: number): Set<string> =>
       .map((request) => request.lane),
   )
 
-/**
- * The subagents at work in the sessions of the main checkout and its worktrees: their logs read, the finished and the
- * stale left out. The one chain the herd (`readSubagentActivity`) and the watcher's heartbeat share.
- */
-export const readRunningSubagents = (
-  { projects, root, approvalsRoot, worktreeDirectory, skillPrefix }: SubagentSource,
-  now: number = Date.now(),
+/** The running subagents among `logs`, the finished and the stale left out. */
+const runningOf = (
+  logs: readonly SubagentLog[],
+  { approvalsRoot, worktreeDirectory, skillPrefix }: SubagentSource,
+  now: number,
 ): RunningSubagent[] =>
   runningSubagents(
-    readSubagentLogs(projects, root, now, worktreeDirectory),
+    logs,
     heldNames(approvalsRoot, now),
     now,
     worktreeDirectory,
     skillPrefix === undefined ? [DEFAULT_SKILL_PREFIX] : [DEFAULT_SKILL_PREFIX, skillPrefix],
   )
 
-/** The state of every worktree a subagent of the main checkout's sessions works in. */
-export const readSubagentActivity = (source: SubagentSource, now: number = Date.now()): Map<string, SubagentActivity> =>
-  subagentsByLane(readRunningSubagents(source, now), source.worktreeDirectory)
+/**
+ * The subagents at work in the sessions of the main checkout and its worktrees: their logs read, the finished and the
+ * stale left out. The one chain the herd (`readSubagentActivitySliced`) and the watcher's heartbeat share.
+ */
+export const readRunningSubagents = (source: SubagentSource, now: number = Date.now()): RunningSubagent[] =>
+  runningOf(readSubagentLogs(source.projects, source.root, now, source.worktreeDirectory), source, now)
+
+/**
+ * The state of every worktree a subagent of the main checkout's sessions works in, with `pass` awaited before each
+ * session's subagents are read, so a gate (`createSliceGate`) can hand the event loop back between them.
+ */
+export const readSubagentActivitySliced = async (
+  source: SubagentSource,
+  pass: () => Promise<void>,
+  now: number = Date.now(),
+): Promise<Map<string, SubagentActivity>> => {
+  const logs: SubagentLog[] = []
+  for (const directory of allSessionDirectories(source.projects, source.root, source.worktreeDirectory)) {
+    await pass()
+    logs.push(...logsInSession(directory, now))
+  }
+  return subagentsByLane(runningOf(logs, source, now), source.worktreeDirectory)
+}

package/src/plans/subagents.ts

@@ -1,4 +1,4 @@
-import { parseLogEntry } from '../context/session-log'
+import { keptLogEntry } from '../context/session-log'
 import { MS_PER_MINUTE } from '../plan-format/clock'
 import { terminalSafe } from '../plan-format/terminal-text'
 import { isRecord } from '../shared/is-record'
@@ -86,7 +86,7 @@ const lastWorktreeIn = (text: string, worktreeDirectory: string): string | null
  */
 const workingDirectory = (tail: readonly string[], worktreeDirectory: string): string | null => {
   const entries = [...tail].reverse().flatMap((line): Record<string, unknown>[] => {
-    const entry = parseLogEntry(line)
+    const entry = keptLogEntry(line)
     return entry === null ? [] : [entry]
   })
   for (const entry of entries) {

package/src/plans/symbols.ts

@@ -18,7 +18,10 @@ export const statusSymbol = (agent: string | null): string => {
 
 export const statusWord = (agent: string | null): string => agent ?? NO_AGENT_WORD
 
-/** Before a row that opens and closes: lanes, the planned phases, the ticked items of a phase. */
+/** The marks of "Your turn": what waits on the answer, a file sent to look at, what is planned. */
+export const TURN_MARK = { now: '?', file: '📎', planned: '◷' } as const
+
+/** Before a row that opens and closes: lanes, the planned phases, the tasks of a phase. */
 export const CHEVRON = { closed: '▸', open: '▾' } as const
 
 /** Before the count under a block that shows all its rows; a click folds it back to five. */

package/src/plans/task-brief.ts

@@ -0,0 +1,143 @@
+import { paint, visibleLength } from '../terminal/text'
+import { textWidth } from '../terminal/width'
+
+/** An opened task as the herd sets it: the lines shown at once, and the lines `▸ n more lines` opens. */
+export type TaskBrief = { shown: string[]; rest: string[] }
+
+/** A word as its parts, code or not: a code span and the stop after it are one word. */
+type Word = { text: string; code: boolean }[]
+
+/**
+ * How an opened task is set: the order up to the first `dashMark`, each sentence on a new line, as many whole
+ * sentences as fit in `lines` lines, the origin included, no line wider than `lineWidth`; an origin in parentheses
+ * moves to the end of the last line, `originGap` from it. A first sentence longer than `lines` ends in `cut`.
+ */
+export const BRIEF = { lines: 5, lineWidth: 72, dashMark: ' — ', originGap: '   ', cut: '…' } as const
+
+const CODE_SPAN = /`([^`]+)`/g
+const BOLD = /\*\*/g
+/**
+ * A parenthesis that names a day and month with dots: where a task came from, not what it asks. No digit may follow
+ * the second dot, so a version (`1.10.0`) or an IP address is no date.
+ */
+const ORIGIN = /\s*\(([^()]*\b\d{1,2}\.\d{1,2}\.(?!\d)[^()]*)\)/g
+/**
+ * A sentence ends before a capital after a word of two letters or more, or after a unit behind a number (`5 s.`), so
+ * a dotted date and `z. B.` go on.
+ */
+const SENTENCE_END = /(?:(?<=[^\s\d][\p{L})"“”`'][.!?])|(?<=\d \p{L}[.!?]))\s+(?=[\p{Lu}„"`*(])/u
+const SOURCE_DIRECTORY = /^src\//
+
+/** The words of `text` at its spaces, code spans without backticks and a path's leading `src/` dropped. */
+const wordsOf = (text: string): Word[] => {
+  const words: Word[] = [[]]
+  text
+    .replace(BOLD, '')
+    .split(CODE_SPAN)
+    .forEach((segment, index) => {
+      const code = index % 2 === 1
+      const parts = (code ? segment.replace(SOURCE_DIRECTORY, '') : segment).split(' ')
+      parts.forEach((part, at) => {
+        if (at > 0) words.push([])
+        if (part) words.at(-1)?.push({ text: part, code })
+      })
+    })
+  return words.filter((word) => word.length > 0)
+}
+
+const lengthOf = (word: Word): number => word.reduce((sum, part) => sum + textWidth(part.text), 0)
+
+const drawn = (word: Word): string => word.map(({ text, code }) => (code ? paint.teal(text) : text)).join('')
+
+/** `text` broken at spaces into lines of at most `width` cells, code in teal; a word wider than a line stands alone. */
+const setLines = (text: string, width: number): string[] => {
+  const lines: Word[][] = []
+  let length = 0
+  for (const word of wordsOf(text)) {
+    const current = lines.at(-1)
+    if (current && length + 1 + lengthOf(word) <= width) {
+      current.push(word)
+      length += 1 + lengthOf(word)
+    } else {
+      lines.push([word])
+      length = lengthOf(word)
+    }
+  }
+  return lines.map((line) => line.map(drawn).join(' '))
+}
+
+const sentencesOf = (text: string): string[] =>
+  text
+    .split(SENTENCE_END)
+    .map((sentence) => sentence.trim())
+    .filter(Boolean)
+
+/**
+ * `lines` with the origins dim at the end of the last one, or below it on lines of their own, broken at `width`, where
+ * they do not fit beside it.
+ */
+const withOrigins = (lines: string[], origins: readonly string[], width: number): string[] => {
+  if (origins.length === 0) return lines
+  const origin = origins.join('; ')
+  const last = lines.at(-1)
+  if (last !== undefined && visibleLength(last) + BRIEF.originGap.length + textWidth(origin) <= width)
+    return [...lines.slice(0, -1), `${last}${BRIEF.originGap}${paint.dim(origin)}`]
+  return [...lines, ...setLines(origin, width).map((line) => paint.dim(line))]
+}
+
+const originsOf = (text: string): string[] => [...text.matchAll(ORIGIN)].map((match) => match[1]?.trim() ?? '')
+
+/** `text` in the form of the brief: one sentence per line, its origins dim at the end. */
+const setSentences = (text: string, width: number): string[] =>
+  withOrigins(
+    sentencesOf(text.replace(ORIGIN, '')).flatMap((sentence) => setLines(sentence, width)),
+    originsOf(text),
+    width,
+  )
+
+const fits = (lines: string[], origins: readonly string[], width: number): boolean =>
+  withOrigins(lines, origins, width).length <= BRIEF.lines
+
+/** How many of the leading sentences, each set as `lines`, fit whole into the brief together with the origins. */
+const wholeSentenceCount = (sentenceLines: string[][], origins: readonly string[], width: number): number => {
+  let count = 0
+  while (count < sentenceLines.length && fits(sentenceLines.slice(0, count + 1).flat(), origins, width)) count += 1
+  return count
+}
+
+/** A sentence too long for the brief: as many of its lines as fit beside the origins, the last ending in `BRIEF.cut`. */
+const cutSentence = (sentence: string, origins: readonly string[], width: number): TaskBrief => {
+  const lines = setLines(sentence, Math.max(width - textWidth(BRIEF.cut), 1))
+  const marked = (count: number): string[] =>
+    lines.slice(0, count).map((line, index) => (index === count - 1 ? `${line}${BRIEF.cut}` : line))
+  let count = BRIEF.lines
+  while (count > 1 && !fits(marked(count), origins, width)) count -= 1
+  return { shown: withOrigins(marked(count), origins, width), rest: lines.slice(count) }
+}
+
+/**
+ * An opened task's text (`body`, after its name) set for reading in `width` cells: the order up to the first ` — `,
+ * one sentence per line, as many whole sentences as fit into `BRIEF.lines` with their origins dim at the end; the rest
+ * (further sentences, then everything after the dash: protocol, measurements, findings) as `rest`. A first sentence
+ * that does not fit alone is cut instead. The plan text itself stays as written.
+ */
+export const taskBrief = (body: string, width: number): TaskBrief => {
+  const lineWidth = Math.max(Math.min(BRIEF.lineWidth, width), 1)
+  const dash = body.indexOf(BRIEF.dashMark)
+  const order = dash === -1 ? body : body.slice(0, dash)
+  const after = dash === -1 ? '' : body.slice(dash + BRIEF.dashMark.length).trim()
+  const origins = originsOf(order)
+  const sentences = sentencesOf(order.replace(ORIGIN, ''))
+  const sentenceLines = sentences.map((sentence) => setLines(sentence, lineWidth))
+  const afterLines = after ? setSentences(after, lineWidth) : []
+  const count = wholeSentenceCount(sentenceLines, origins, lineWidth)
+  const [first] = sentences
+  if (count === 0 && first !== undefined) {
+    const cut = cutSentence(first, origins, lineWidth)
+    return { shown: cut.shown, rest: [...cut.rest, ...sentenceLines.slice(1).flat(), ...afterLines] }
+  }
+  return {
+    shown: withOrigins(sentenceLines.slice(0, count).flat(), origins, lineWidth),
+    rest: [...sentenceLines.slice(count).flat(), ...afterLines],
+  }
+}