jackherd 1.8.1 → 1.10.0

package/src/check/skill-budgets.ts

@@ -0,0 +1,185 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { CLAUDE_DIRECTORY, claudePath, SKILLS_DIRECTORY } from '../claude/paths'
+import { projectLockCandidates } from '../config/legacy-names'
+import { parseManifest } from '../sync/manifest'
+import { matchesGlob } from './glob'
+import { CHECK_STATUS, type CheckResult, type CheckStatus } from './result'
+import type { SkillBudgets } from './schema'
+import {
+  KIT_FILE_FALLBACK_BUDGET,
+  KIT_SKILL_BUDGETS,
+  OWN_SKILL_BUDGET,
+  SUPPLEMENT_BUDGET,
+} from './skill-budget-defaults'
+
+/** Words per path or glob from the project root; a key joining paths with ` + ` budgets them together. */
+export type BudgetTable = Readonly<SkillBudgets>
+
+/** A file with the budget it falls back on when neither the project nor the kit names one. */
+export type FileWords = { path: string; words: number; fallback: number }
+
+export type Measurement = { label: string; words: number; budget: number }
+
+type Overrun = typeof CHECK_STATUS.warn | typeof CHECK_STATUS.fail
+
+type MeasuredOverrun = { entry: Measurement; overrun: Overrun }
+
+const SUPPLEMENTS_DIRECTORY = 'project'
+const KIT_DOCUMENT = /^(skills\/.+\.md|agents\/[^/]+\.md|rules\/kit\/[^/]+\.md)$/
+const KIT_RULE = /^rules\//
+const PATHS_IN_FRONTMATTER = /^---\r?\n(?:(?!---)[^\n]*\n)*?paths:/
+const SUM_SEPARATOR = ' + '
+const FAIL_FACTOR = 1.1
+
+const OVERRUN_LABEL: Record<Overrun, string> = { warn: 'warning', fail: 'error' }
+
+const isGlob = (key: string): boolean => /[*?]/.test(key)
+
+/**
+ * The words of a file as `wc -w` counts them: runs of non-whitespace, over the whole file. The frontmatter counts,
+ * because an agent reads it with the rest, and the skill's description in it is loaded before the body is.
+ */
+export const countWords = (text: string): number => text.split(/\s+/).filter(Boolean).length
+
+/** The paths a budget key names: one, or several joined with ` + ` for what loads together. */
+export const budgetKeyPaths = (key: string): string[] => key.split(SUM_SEPARATOR)
+
+/**
+ * Whether a kit file, by its path in the kit (`skills/…`, `agents/…`, `rules/kit/…`), is text an agent loads as it
+ * is and so counts against a budget: a skill file, an agent, or a kit rule without a `paths:` glob in its
+ * frontmatter; a rule with one loads only on demand. The one choice `jh check` and the kit's own test share.
+ */
+export const isBudgetedKitDocument = (kitPath: string, text: string): boolean =>
+  KIT_DOCUMENT.test(kitPath) && !(KIT_RULE.test(kitPath) && PATHS_IN_FRONTMATTER.test(text))
+
+/** A file warns above its budget and fails above the budget plus 10 %. */
+export const overrunOf = (words: number, budget: number): Overrun | null => {
+  if (words > budget * FAIL_FACTOR) return CHECK_STATUS.fail
+  return words > budget ? CHECK_STATUS.warn : null
+}
+
+/** The project's entry for the exact path, else its first glob that matches, else the kit's default, else `fallback`. */
+export const budgetOf = (path: string, project: BudgetTable, defaults: BudgetTable, fallback: number): number => {
+  const glob = Object.keys(project).find((key) => isGlob(key) && matchesGlob(path, key))
+  return project[path] ?? (glob === undefined ? undefined : project[glob]) ?? defaults[path] ?? fallback
+}
+
+const sumEntry = (key: string, files: readonly FileWords[]): number | null => {
+  const parts = budgetKeyPaths(key).map((part) => files.find((file) => file.path === part))
+  return parts.every((part) => part !== undefined) ? parts.reduce((total, part) => total + part.words, 0) : null
+}
+
+/** Every file against its budget, then every sum entry of the project and the kit whose files all exist. */
+export const measureFiles = (
+  files: readonly FileWords[],
+  project: BudgetTable,
+  defaults: BudgetTable,
+): Measurement[] => {
+  const single = files.map(({ path, words, fallback }) => ({
+    label: path,
+    words,
+    budget: budgetOf(path, project, defaults, fallback),
+  }))
+  const sums = [...new Set([...Object.keys(project), ...Object.keys(defaults)])]
+    .filter((key) => key.includes(SUM_SEPARATOR))
+    .flatMap((key) => {
+      const words = sumEntry(key, files)
+      return words === null ? [] : [{ label: key, words, budget: budgetOf(key, project, defaults, 0) }]
+    })
+  return [...single, ...sums]
+}
+
+const overrunLine = ({ entry: { label, words, budget }, overrun }: MeasuredOverrun): string =>
+  `${OVERRUN_LABEL[overrun]}: ${label} has ${words} words, budget ${budget}`
+
+const withinLine = (count: number): string =>
+  count === 1 ? '1 file within its word budget' : `${count} files within their word budget`
+
+const statusOf = (overruns: readonly MeasuredOverrun[]): CheckStatus => {
+  if (overruns.some(({ overrun }) => overrun === CHECK_STATUS.fail)) return CHECK_STATUS.fail
+  return overruns.length > 0 ? CHECK_STATUS.warn : CHECK_STATUS.pass
+}
+
+/** One line per overrun; one line in total when none is over. Warns above a budget, fails above the budget plus 10 %. */
+export const budgetResult = (measured: readonly Measurement[], durationMs: number): CheckResult => {
+  const overruns = measured.flatMap((entry) => {
+    const overrun = overrunOf(entry.words, entry.budget)
+    return overrun === null ? [] : [{ entry, overrun }]
+  })
+  return {
+    name: 'Skill budgets',
+    command: `${measured.length} measured, words per budget`,
+    status: statusOf(overruns),
+    detail: overruns.map(overrunLine).join('\n') || withinLine(measured.length),
+    durationMs,
+  }
+}
+
+const readText = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const parseJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+/** The kit documents the first valid lock file lists, the lock under its old name counting while sync has not moved it. */
+const kitPathsOf = (root: string): string[] => {
+  for (const candidate of projectLockCandidates(root)) {
+    const text = readText(candidate)
+    const parsed = text === null ? null : parseManifest(parseJson(text))
+    if (parsed?.ok) return Object.keys(parsed.manifest.files).filter((key) => KIT_DOCUMENT.test(key))
+  }
+  return []
+}
+
+const listDirectory = (path: string): string[] => (existsSync(path) ? readdirSync(path) : [])
+
+const fileWordsOf = (root: string, path: string, fallback: number): FileWords[] => {
+  const text = readText(join(root, path))
+  return text === null ? [] : [{ path, words: countWords(text), fallback }]
+}
+
+const kitFileWordsOf = (root: string, kitPath: string): FileWords[] => {
+  const path = claudePath(kitPath)
+  const text = readText(join(root, path))
+  return text === null || !isBudgetedKitDocument(kitPath, text)
+    ? []
+    : [{ path, words: countWords(text), fallback: KIT_FILE_FALLBACK_BUDGET }]
+}
+
+const ownSkillPaths = (root: string, kit: ReadonlySet<string>): string[] =>
+  listDirectory(join(root, CLAUDE_DIRECTORY, SKILLS_DIRECTORY))
+    .map((name) => claudePath(SKILLS_DIRECTORY, name, 'SKILL.md'))
+    .filter((path) => !kit.has(path))
+
+const supplementPaths = (root: string): string[] =>
+  listDirectory(join(root, CLAUDE_DIRECTORY, SUPPLEMENTS_DIRECTORY))
+    .filter((name) => name.endsWith('.md'))
+    .map((name) => claudePath(SUPPLEMENTS_DIRECTORY, name))
+
+/**
+ * The installed kit skills with their references, kit agents and kit rules that load every session (the lock file
+ * says which files the kit installed), the project's supplements and its own skills, measured against the budgets.
+ * Null when there is nothing to measure.
+ */
+export const skillBudgetCheck = (root: string, project: BudgetTable = {}): CheckResult | null => {
+  const started = Date.now()
+  const kitPaths = kitPathsOf(root)
+  const kit = new Set(kitPaths.map((key) => claudePath(key)))
+  const files = [
+    ...kitPaths.flatMap((key) => kitFileWordsOf(root, key)),
+    ...supplementPaths(root).flatMap((path) => fileWordsOf(root, path, SUPPLEMENT_BUDGET)),
+    ...ownSkillPaths(root, kit).flatMap((path) => fileWordsOf(root, path, OWN_SKILL_BUDGET)),
+  ]
+  return files.length === 0 ? null : budgetResult(measureFiles(files, project, KIT_SKILL_BUDGETS), Date.now() - started)
+}

package/src/cli.ts

@@ -24,9 +24,13 @@ export const COMMANDS: CommandTable = {
   [HERD_COMMAND.name]: () => import('./plans/command'),
   init: () => import('./sync/init-command'),
   [HERD_COMMAND.alias]: () => import('./plans/command'),
+  lane: () => import('./lane/command'),
+  preview: () => import('./preview/command'),
   settled: () => import('./settled/command'),
   sync: () => import('./sync/command'),
+  task: () => import('./task-signals/command'),
   update: () => import('./update/command'),
+  waiting: () => import('./waiting/command'),
   watch: () => import('./watch/command'),
 }
 

package/src/config/auto-window.ts

@@ -0,0 +1,8 @@
+import { DAY_MS } from '../plan-format/clock'
+
+/** The longest window `watch.parallelTasks.auto` may span: a forgotten switch ends within a week. */
+export const MAX_AUTO_WINDOW_DAYS = 7
+
+/** The days from `since` to `until`, two `YYYY-MM-DD` dates; read as UTC midnights, so no clock change shifts them. */
+export const windowDays = (since: string, until: string): number =>
+  Math.round((Date.parse(`${until}T00:00:00Z`) - Date.parse(`${since}T00:00:00Z`)) / DAY_MS)

package/src/config/link-kinds.ts

@@ -8,11 +8,17 @@ export type LinkKind = {
   icon: string
 }
 
+export const ARTIFACT_LINK_KIND: LinkKind = {
+  pattern: '^https://claude\\.ai/(code/)?artifact/',
+  label: 'Artifact',
+  icon: '✦',
+}
+
 /** The kinds known without configuration: plain URL patterns, no service is called. */
 export const DEFAULT_LINK_KINDS: readonly LinkKind[] = [
   { pattern: '^https://github\\.com/[^/]+/[^/]+/(pull|issues)/\\d+', label: 'GitHub', icon: '⑂' },
   { pattern: '^https://(www\\.)?figma\\.com/', label: 'Figma', icon: '◈' },
-  { pattern: '^https://claude\\.ai/(code/)?artifact/', label: 'Artifact', icon: '✦' },
+  ARTIFACT_LINK_KIND,
 ]
 
 export const isRegularExpression = (source: string): boolean => {

package/src/config/schema.ts

@@ -5,6 +5,7 @@ import { PLAN_LANGUAGE, RESPONSE_ADDRESS } from '../vocabulary'
 import { CONTENT_FIELDS, SOURCE_FIELD } from '../watch/source-fields'
 import { isSourcePath } from '../watch/source-path'
 import { BUN_FAILED_TEST_PATTERN, CLEAN_REVIEW_TEXT } from '../watch/watch-defaults'
+import { MAX_AUTO_WINDOW_DAYS, windowDays } from './auto-window'
 import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
 import { hasNestedQuantifier } from './nested-quantifier'
@@ -118,6 +119,31 @@ const feedbackSchema = z.strictObject({
   noFindingTemplates: z.array(z.string().min(1)).default([CLEAN_REVIEW_TEXT]),
 })
 
+const DEFAULT_PARALLEL_TASKS_MAX_TOKENS = 100_000
+
+const parallelTasksSchema = z.strictObject({
+  /**
+   * The most the extra agents of a parallel proposal may cost before they do anything: the token baseline of a fresh
+   * agent times the agents to add. Above it the watcher does not propose parallel tasks. The baseline is the context
+   * the first answer of a lane's session carried.
+   */
+  maxTokens: z.number().int().positive().default(DEFAULT_PARALLEL_TASKS_MAX_TOKENS),
+  /**
+   * The days, both included, on which a proposal that keeps every limit is marked `auto` and the coordinator starts it
+   * without asking: subagents beside running work in a lane, at most two extra agents, no path that always asks.
+   * `since` is the day it was switched on, `until` at most seven days later; outside the window it is off. Unset by
+   * default, so every proposal asks.
+   */
+  auto: z
+    .strictObject({ since: z.iso.date(), until: z.iso.date() })
+    .refine(({ since, until }) => until >= since, 'until must not be before since')
+    .refine(
+      ({ since, until }) => windowDays(since, until) <= MAX_AUTO_WINDOW_DAYS,
+      `until must be at most ${MAX_AUTO_WINDOW_DAYS} days after since`,
+    )
+    .optional(),
+})
+
 const checksSchema = z.strictObject({
   /**
    * Finds a failed test in a line of a red run's log (`gh run view --log-failed`) after its job, step and timestamp
@@ -228,9 +254,9 @@ const hasUniqueNames = (sources: readonly { name: string }[]): boolean =>
 const coordinatorSchema = z
   .strictObject({
     /** Tokens in the coordinator's context from which the watcher reports `coordinator warn`. */
-    warnTokens: tokenCount.default(200_000),
+    warnTokens: tokenCount.default(350_000),
     /** Tokens in the coordinator's context from which the watcher reports `coordinator alert`. */
-    alertTokens: tokenCount.default(300_000),
+    alertTokens: tokenCount.default(500_000),
   })
   .refine(warnBelowAlert, WARN_BELOW_ALERT)
 
@@ -258,7 +284,7 @@ const checkFreePattern = z
   )
 
 /**
- * A path pattern that always asks before a merge under a plan approval: plain path words with wildcards, relative, no
+ * A path pattern that always asks (`guard.alwaysAsk`): plain path words with wildcards, relative, no
  * empty, `.` or `..` segment (GitHub lists no file with one, so such a pattern would never ask). Broad on purpose (`.github/**`, `**`), since a pattern here only ever adds a question; braces,
  * classes and negation stay out, so the hook, which has no schema library, reads exactly what this accepts.
  */
@@ -293,13 +319,13 @@ const mergeSchema = z.strictObject({
   withoutChecks: z.array(checkFreePattern).default([]),
 })
 
-const guardSchema = z.strictObject({
+const guardFields = z.strictObject({
   /**
-   * The commands the merge guard hook asks the user about before they run, also behind options before the verb, a chain,
-   * a wrapper or `sh -c`. `gh api` asks only for a write to a merge, a file, a dispatch, a rerun or a ref. An empty list switches the
-   * guard off.
+   * The commands the merge guard hook asks the user about before they run, where they stand at a program position, also
+   * behind options before the verb, a chain, a wrapper or `sh -c`. `gh api`, when listed, asks only for a write to a
+   * merge, a file, a dispatch, a rerun or a ref. An empty list switches the guard off.
    */
-  commands: z.array(guardedCommand).default(['gh pr merge', 'gh workflow run', 'gh run rerun', 'gh api']),
+  commands: z.array(guardedCommand).default(['gh pr merge', 'gh workflow run']),
   selfMerge: z
     .strictObject({
       /** Whether `/orchestrate` offers "merge it yourself after green checks" in the pull request question; off also stops the hook honouring such an answer. */
@@ -314,32 +340,49 @@ const guardSchema = z.strictObject({
       waitMinutes: z.number().int().min(1).max(9).default(8),
     })
     .prefault({}),
+  /**
+   * Paths that always ask, on top of the ones jackherd brings (`.github/**`, `**\/migrations/**`, `**\/.env*`,
+   * `.claude/**`, `.jackherd/**`, `bunfig.toml`, `**\/CLAUDE.md`, `**\/AGENTS.md`, `.agents/**`, `.mcp.json`,
+   * `.husky/**`, `lefthook.yml`, the lockfiles of bun, npm, pnpm and yarn, `**\/.npmrc`, `**\/CODEOWNERS`): a
+   * `merge.withoutChecks` pattern never opens them, and the watcher never starts parallel work on them by itself. They
+   * add to that list, never replace it. A standing approval covers them; only workflows, migrations and env files ask.
+   */
+  alwaysAsk: z.array(alwaysAskPattern).default([]),
+  /**
+   * Checks that must be among the head commit's and green before a standing approval lets a merge pass, by their names
+   * on GitHub. Unset, the merge needs at least one check and every one green; set, also each of these. Either way
+   * GitHub must be able to merge it.
+   */
+  requiredChecks: z.array(checkName).optional(),
+  /** Read until 2.0.0 as `alwaysAsk` (`exceptPaths`) and `requiredChecks`; the plan approval it was for is gone. */
   planApproval: z
-    .strictObject({
-      /**
-       * Paths that always ask, on top of the ones jackherd brings (`.github/**`, `**\/migrations/**`, `**\/.env*`,
-       * `.claude/**`, `.jackherd/**`, `bunfig.toml`, `**\/CLAUDE.md`, `**\/AGENTS.md`, `.agents/**`, `.mcp.json`,
-       * `.husky/**`, `lefthook.yml`, the lockfiles of bun, npm, pnpm and yarn, `**\/.npmrc`, `**\/CODEOWNERS`, every
-       * package.json, and the CHANGELOG.md of every package without `"private": true`):
-       * a pull request that changes one is never merged on a plan approval alone. They add to that list, never replace
-       * it; an invalid entry turns plan approval off, so every merge asks.
-       */
-      exceptPaths: z.array(alwaysAskPattern).default([]),
-      /**
-       * Checks that must be among the head commit's and green before a plan approval lets a merge pass, by their names
-       * on GitHub. Unset, the merge needs at least one check and every one green; set, also each of these. Either way
-       * GitHub must be able to merge it and the head must contain the base branch.
-       */
-      requiredChecks: z.array(checkName).optional(),
-    })
-    .prefault({}),
+    .strictObject({ exceptPaths: z.array(alwaysAskPattern).optional(), requiredChecks: z.array(checkName).optional() })
+    .optional()
+    .meta({ deprecated: true }),
 })
 
+/** A config from before 1.10.0 kept the paths that always ask and the required checks under `planApproval`. */
+const guardWithoutPlanApproval = ({ planApproval, ...guard }: z.output<typeof guardFields>) => {
+  const requiredChecks = guard.requiredChecks ?? planApproval?.requiredChecks
+  return {
+    ...guard,
+    alwaysAsk: [...guard.alwaysAsk, ...(planApproval?.exceptPaths ?? [])],
+    ...(requiredChecks === undefined ? {} : { requiredChecks }),
+  }
+}
+
+const guardSchema = guardFields.transform(guardWithoutPlanApproval)
+
 const hintsSchema = z.strictObject({
   /** Whether the `ask-hint` hook points out a last message that ends in a question while the turn used no `AskUserQuestion`; a lane session is never hinted. */
   askUserQuestion: z.boolean().default(true),
+  /** Whether the `task-hint` hook points a lane that edits a file without an open task signal to `jh task start`, once per task. */
+  taskSignal: z.boolean().default(true),
 })
 
+/** Minutes a lane works without a task signal before the watcher reports `no task signal`. */
+const DEFAULT_TASK_SIGNAL_MINUTES = 10
+
 const contextSchema = z
   .strictObject({
     /** Tokens in a lane's context from which its fill shows yellow and `/implement` offers a new chat. */
@@ -410,6 +453,13 @@ export const jackherdConfigSchema = z.strictObject({
   terminal: z
     .strictObject({ adapter: z.enum(Object.values(TERMINAL_ADAPTER)).default(TERMINAL_ADAPTER.none) })
     .prefault({}),
+  /** How the coordinator shows a draft for review (`orchestrate` § 4). */
+  preview: z
+    .strictObject({
+      /** Publish the draft as a private Artifact when the session has the tool; `false` sends a file card or `jh preview --open` instead. */
+      publish: z.boolean().default(true),
+    })
+    .prefault({}),
   plans: z
     .strictObject({
       /** Minutes between background fetches of the base branch while `jh herd` runs; 0 turns them off. */
@@ -430,6 +480,8 @@ export const jackherdConfigSchema = z.strictObject({
   /**
    * Read by `jh watch`; without `deploy` it reports no deploy runs. `feedback` is on unless set to `false`:
    * it reports new feedback on the lanes' pull requests except from the account the watcher runs as and `ignore`.
+   * `parallelTasks.maxTokens` caps the cost of the extra agents in a proposal of parallel tasks at the heartbeat.
+   * `taskSignalMinutes` is how long a lane works without a task signal before it reports `no task signal`, once per phase.
    * `checks` reads the failed tests of a red lane pull request (`failedTestPattern`), also with `feedback` off.
    * Without `previews` it reads no deploy preview; with it, one `preview` per new head commit. Each of `sources` is a
    * command whose JSON output reports `source` for a new or changed entry.
@@ -439,6 +491,8 @@ export const jackherdConfigSchema = z.strictObject({
       deploy: deploySchema.optional(),
       feedback: z.union([z.literal(false), feedbackSchema]).prefault({}),
       checks: checksSchema.prefault({}),
+      parallelTasks: parallelTasksSchema.prefault({}),
+      taskSignalMinutes: z.number().int().positive().default(DEFAULT_TASK_SIGNAL_MINUTES),
       previews: previewsSchema.optional(),
       sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
     })

package/src/context/fill.ts

@@ -67,3 +67,15 @@ export const contextFill = (lines: readonly string[], windows: ContextWindows):
   const window = windowFor(last.model, highest, windows)
   return { tokens: last.tokens, window, share: Math.min(last.tokens / window, 1), model: last.model }
 }
+
+/**
+ * What a fresh agent carries before it has worked: the input of the first main-chain answer in the lines, which holds
+ * the system prompt, the project instructions and the first request. Null when no line is a usable answer.
+ */
+export const firstAnswerTokens = (lines: readonly string[]): number | null => {
+  for (const line of lines) {
+    const answer = answerOf(line)
+    if (answer) return answer.tokens
+  }
+  return null
+}

package/src/context/session-log.ts

@@ -2,6 +2,7 @@ import { closeSync, existsSync, fstatSync, openSync, readdirSync, readSync, stat
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { CLAUDE_DIRECTORY, SESSION_LOGS_DIRECTORY } from '../claude/paths'
+import { isRecord } from '../shared/is-record'
 
 /** How much of the end of a log is read: logs grow to hundreds of megabytes, and the last answers are at the end. */
 export const TAIL_BYTES = 2 * 1024 * 1024
@@ -40,6 +41,20 @@ export const readTailLines = (path: string, bytes: number): string[] => {
   }
 }
 
+/** The complete lines of the first `bytes` of a file: a cut-off last line is dropped, a file read to its end keeps its last one. */
+export const readHeadLines = (path: string, bytes: number): string[] => {
+  const descriptor = openSync(path, 'r')
+  try {
+    const { size } = fstatSync(descriptor)
+    const buffer = Buffer.alloc(Math.min(size, bytes))
+    readSync(descriptor, buffer, 0, buffer.length, 0)
+    const lines = buffer.toString('utf8').split('\n')
+    return size > bytes ? lines.slice(0, -1) : lines
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
 /** The tail of a session's log, read only; null when the session has no log or it cannot be read. */
 export const sessionLog = (
   sessionId: string,
@@ -59,7 +74,7 @@ export type AgentSession = { session: string | null; cwd: string | null }
 const hasAnswer = (lines: readonly string[]): boolean => lines.some((line) => line.includes('"type":"assistant"'))
 
 /** Claude Code names a project directory after the working directory, `/` and `.` turned into `-`. */
-const projectDirectoryOf = (cwd: string): string => cwd.replace(/[/.]/g, '-')
+export const projectDirectoryOf = (cwd: string): string => cwd.replace(/[/.]/g, '-')
 
 const newestLogOf = (cwd: string, projectsDirectory: string): string | null => {
   const directory = join(projectsDirectory, projectDirectoryOf(cwd))
@@ -89,3 +104,30 @@ export const agentLog = (
     return reported
   }
 }
+
+/**
+ * The path of the log `agentLog` would read: the reported session's log when it holds an answer, else the newest log
+ * of the agent's working directory, else the reported one; null when there is none.
+ */
+export const agentLogPath = (
+  { session, cwd }: AgentSession,
+  projectsDirectory: string = defaultProjectsDirectory(),
+): string | null => {
+  const reported = session ? sessionLogPath(session, projectsDirectory) : null
+  try {
+    if (reported && hasAnswer(readTailLines(reported, TAIL_BYTES))) return reported
+    return (cwd ? newestLogOf(cwd, projectsDirectory) : null) ?? reported
+  } catch {
+    return reported
+  }
+}
+
+/** One line of a session log as an object; null for a line that is no JSON or not an object. */
+export const parseLogEntry = (line: string): Record<string, unknown> | null => {
+  try {
+    const entry: unknown = JSON.parse(line)
+    return isRecord(entry) ? entry : null
+  } catch {
+    return null
+  }
+}

package/src/lane/close-board.ts

@@ -0,0 +1,106 @@
+import { twoDigits } from '../plan-format/clock'
+import { laneNameOf, parseSprintLanes } from '../plan-format/lanes'
+import { firstTableRows, sectionLines, sectionStart } from '../plan-format/markdown'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { PLAN_LANGUAGE, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { BOARD_LANE, type BoardLane } from './close-check'
+
+const CONTINUATION = '↳'
+const FIRST_CELL = /^\|((?:[^|\\]|\\.)*)\|/
+
+const HISTORY_HEADER: Record<PlanLanguage, readonly [string, string]> = {
+  [PLAN_LANGUAGE.de]: ['Datum', 'Ereignis'],
+  [PLAN_LANGUAGE.en]: ['Date', 'Event'],
+}
+
+const isoDate = (time: Date): string =>
+  `${time.getFullYear()}-${twoDigits(time.getMonth() + 1)}-${twoDigits(time.getDate())}`
+
+/** The word for a cleaned-up lane and the day, as a name cell carries it: `abgeräumt DD.MM.`, `cleaned up YYYY-MM-DD`. */
+export const closedMark = (time: Date, language: PlanLanguage): string => {
+  const day =
+    language === PLAN_LANGUAGE.de ? `${twoDigits(time.getDate())}.${twoDigits(time.getMonth() + 1)}.` : isoDate(time)
+  return `${PLAN_VOCABULARY[language].laneClosed} ${day}`
+}
+
+/** The date cell of a history row, `YYYY-MM-DD` in every plan language. */
+export const historyDate = (time: Date): string => isoDate(time)
+
+/** How the lanes table names `lane`, read as the herd reads it. */
+export const boardLaneOf = (board: string, lane: string, language: PlanLanguage): BoardLane => {
+  const found = parseSprintLanes(board, language).find(({ name }) => name === lane)
+  if (found === undefined) return BOARD_LANE.missing
+  return found.closed ? BOARD_LANE.closed : BOARD_LANE.open
+}
+
+/**
+ * The line indexes of the lane's current rows: the rows since it was last cleaned up, as `parseSprintLanes` keeps them,
+ * a row that names the lane again without the mark starting it anew. Empty when the lane is closed or missing.
+ */
+const currentRowIndexes = (board: string, lane: string, language: PlanLanguage): number[] => {
+  const { sections, laneClosed } = PLAN_VOCABULARY[language]
+  const start = sectionStart(board, sections.lanes)
+  if (start === -1) return []
+  let previous: string | null = null
+  let closed = false
+  let indexes: number[] = []
+  for (const { index, cells } of firstTableRows(sectionLines(board, sections.lanes))) {
+    const first = cells[0] ?? ''
+    const name = laneNameOf(first, previous)
+    previous = name ?? previous
+    if (name !== lane) continue
+    const marked = first.includes(laneClosed)
+    if (closed && !marked && !first.startsWith(CONTINUATION)) {
+      closed = false
+      indexes = []
+    }
+    closed ||= marked
+    indexes.push(start + index)
+  }
+  return closed ? [] : indexes
+}
+
+const withMarkedNameCell = (line: string, mark: string): string =>
+  line.replace(FIRST_CELL, (_cell, name: string) => `| ${name.trim()}, ${mark} |`)
+
+/** The board with `, <mark>` appended to the name cell of each current row of the lane; unchanged without one. */
+export const withLaneClosed = (board: string, lane: string, mark: string, language: PlanLanguage): string => {
+  const marked = new Set(currentRowIndexes(board, lane, language))
+  return board
+    .split('\n')
+    .map((line, index) => (marked.has(index) ? withMarkedNameCell(line, mark) : line))
+    .join('\n')
+}
+
+/** Text that stays inside one table cell: on one line, with its pipes escaped. */
+const cell = (text: string): string => terminalSafe(text.replace(/\s+/g, ' ')).trim().replaceAll('|', '\\|')
+
+const historyTableHead = (language: PlanLanguage): string[] => {
+  const header = HISTORY_HEADER[language]
+  return [`| ${header.join(' | ')} |`, `|${header.map((name) => '-'.repeat(name.length + 2)).join('|')}|`]
+}
+
+const withoutTrailingBlanks = (lines: readonly string[]): string[] => {
+  let end = lines.length
+  while (end > 0 && lines[end - 1].trim() === '') end -= 1
+  return lines.slice(0, end)
+}
+
+/**
+ * The board with a row on top of its history table, newest first as the coordinator writes them. A history section
+ * without a table gets one right under its heading; a board without the section gets it at its end.
+ */
+export const withHistoryRow = (board: string, date: string, text: string, language: PlanLanguage): string => {
+  const heading = PLAN_VOCABULARY[language].sections.history
+  const row = `| ${date} | ${cell(text)} |`
+  const lines = board.split('\n')
+  const start = sectionStart(board, heading)
+  if (start === -1)
+    return [...withoutTrailingBlanks(lines), '', `## ${heading}`, '', ...historyTableHead(language), row, ''].join('\n')
+  const tableAt = sectionLines(board, heading).findIndex((line) => line.startsWith('|'))
+  const firstRow = start + tableAt + 2
+  if (tableAt !== -1) return [...lines.slice(0, firstRow), row, ...lines.slice(firstRow)].join('\n')
+  const at = lines[start]?.trim() === '' ? start + 1 : start
+  const table = [...historyTableHead(language), row, ...(lines[start]?.trim() === '' ? [''] : [])]
+  return [...lines.slice(0, at), ...table, ...lines.slice(at)].join('\n')
+}