jackherd 1.8.0 → 1.9.0

package/src/preview/page.ts

@@ -0,0 +1,89 @@
+export type PreviewPage = { title: string; html: string }
+
+const escapeHtml = (text: string): string =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+const PREVIEW_STYLE = {
+  github: {
+    name: 'GitHub',
+    font: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
+    size: '16px',
+    line: '1.5',
+  },
+  npm: { name: 'npm', font: '"Source Sans Pro", "Source Sans 3", sans-serif', size: '18px', line: '29.7px' },
+} as const
+
+const FONT_LINK = 'https://fonts.googleapis.com/css2?family=Source+Sans+3:wght@400;600;700&display=swap'
+
+const STYLE = `
+:root { color-scheme: light dark; }
+body { margin: 0; font: 14px system-ui, sans-serif; background: #6e7781; }
+header { display: flex; gap: 16px; align-items: center; padding: 8px 16px; background: #24292f; color: #fff; }
+header label { display: flex; gap: 4px; align-items: center; }
+main { display: flex; gap: 16px; align-items: flex-start; padding: 16px; }
+section.pane { flex: 1 1 0; min-width: 0; border-radius: 6px; overflow: hidden; }
+body.phone section.pane { flex: 0 0 390px; }
+.pane-bar { display: flex; justify-content: space-between; padding: 4px 12px; background: #d0d7de; color: #1f2328; }
+.pane[data-theme="dark"] .pane-bar { background: #30363d; color: #e6edf3; }
+.doc { padding: 32px; --fg: #1f2328; --bg: #fff; --muted: #656d76; --line: #d0d7de; --code: #f6f8fa; --link: #0969da; color: var(--fg); background: var(--bg); }
+.pane[data-theme="dark"] .doc { --fg: #e6edf3; --bg: #0d1117; --muted: #8d96a0; --line: #30363d; --code: #161b22; --link: #4493f8; }
+.pane[data-theme="light"] .only-dark, .pane[data-theme="dark"] .only-light { display: none; }
+.doc a { color: var(--link); }
+.doc h1, .doc h2 { padding-bottom: .3em; border-bottom: 1px solid var(--line); }
+.doc h1, .doc h2, .doc h3, .doc h4 { margin: 24px 0 16px; font-weight: 600; line-height: 1.25; }
+.doc p, .doc ul, .doc ol, .doc table, .doc pre, .doc details { margin: 0 0 16px; }
+.doc img { max-width: 100%; }
+.doc code { padding: .2em .4em; border-radius: 6px; background: var(--code); font-size: 85%; }
+.doc pre { padding: 16px; overflow: auto; border-radius: 6px; background: var(--code); }
+.doc pre code { padding: 0; background: none; }
+.doc table { border-collapse: collapse; display: block; overflow: auto; }
+.doc th, .doc td { padding: 6px 13px; border: 1px solid var(--line); }
+.doc tr:nth-child(2n) { background: var(--code); }
+.doc blockquote { margin: 0 0 16px; padding: 0 1em; color: var(--muted); border-left: .25em solid var(--line); }
+.doc hr { border: 0; height: 1px; background: var(--line); }
+.doc .anchor { display: none; }
+@media (max-width: 900px) { main { flex-direction: column; } }
+`
+
+const SCRIPT = `
+for (const button of document.querySelectorAll('[data-theme-for]')) {
+  button.addEventListener('click', () => {
+    const pane = document.getElementById(button.dataset.themeFor)
+    pane.dataset.theme = pane.dataset.theme === 'dark' ? 'light' : 'dark'
+    button.textContent = pane.dataset.theme
+  })
+}
+document.getElementById('phone').addEventListener('change', (event) => document.body.classList.toggle('phone', event.target.checked))
+`
+
+const paneOf = (id: keyof typeof PREVIEW_STYLE, html: string): string => {
+  const { name, font, size, line } = PREVIEW_STYLE[id]
+  return `<section class="pane" id="${id}" data-theme="light">
+<div class="pane-bar"><b>${name} style</b><button data-theme-for="${id}">light</button></div>
+<article class="doc" style="font: ${size}/${line} ${font}">${html}</article>
+</section>`
+}
+
+/**
+ * The preview page: the rendered README twice, in GitHub style (16 px system font) and in npm style (Source Sans
+ * 18 px, line height 29.7 px), each pane with its own light/dark switch, and a switch to phone width.
+ */
+export const previewPage = ({ title, html }: PreviewPage): string => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)} (preview)</title>
+<link rel="stylesheet" href="${FONT_LINK}">
+<style>${STYLE}</style>
+</head>
+<body>
+<header><b>${escapeHtml(title)}</b><label><input type="checkbox" id="phone"> phone width</label></header>
+<main>
+${paneOf('github', html)}
+${paneOf('npm', html)}
+</main>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`

package/src/preview/render.ts

@@ -0,0 +1,41 @@
+import type { GhAnswer, GhOptions } from '../watch/gh'
+
+export type GhRunner = (args: string[], cwd: string, options?: GhOptions) => Promise<GhAnswer>
+
+/** Names the `owner/repo` of a git remote address (ssh or https, `.git` optional); null for anything else. */
+export const repositorySlugOf = (remote: string): string | null =>
+  /^git@[^:]+:([^/]+\/[^/]+?)(?:\.git)?$/.exec(remote.trim())?.[1] ??
+  /^https?:\/\/[^/]+\/([^/]+\/[^/]+?)(?:\.git)?\/?$/.exec(remote.trim())?.[1] ??
+  null
+
+const MISSING_GH =
+  'the GitHub CLI `gh` is not installed: install it from https://cli.github.com, then run `gh auth login`'
+const NOT_SIGNED_IN = 'the GitHub CLI is not signed in: run `gh auth login`, then try again'
+
+/** The reason a `gh` call failed, with the step that fixes it when it is the missing CLI or the missing login. */
+export const ghFailure = (error: string): string => {
+  if (/ENOENT|not found|not installed|No such file/i.test(error)) return MISSING_GH
+  if (/gh auth login|HTTP 401|not logged|authentication/i.test(error)) return NOT_SIGNED_IN
+  return `GitHub's markdown API failed: ${error}`
+}
+
+/**
+ * The HTML GitHub renders for `markdown` (flavor `gfm`, with the repository as context when known). The request body
+ * goes in through standard input: a long document as an argument exceeds the operating system's limit (`E2BIG`).
+ * Throws with the missing step.
+ */
+export const renderMarkdown = async (
+  markdown: string,
+  repositorySlug: string | null,
+  cwd: string,
+  gh: GhRunner,
+): Promise<string> => {
+  const body = JSON.stringify({
+    text: markdown,
+    mode: 'gfm',
+    ...(repositorySlug === null ? {} : { context: repositorySlug }),
+  })
+  const answer = await gh(['api', '/markdown', '--input', '-'], cwd, { stdin: body })
+  if (!answer.ok) throw new Error(ghFailure(answer.error))
+  return answer.stdout
+}

package/src/settled/board-row.ts

@@ -1,3 +1,4 @@
+import { twoDigits } from '../plan-format/clock'
 import { sectionStart } from '../plan-format/markdown'
 import { terminalSafe } from '../plan-format/terminal-text'
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
@@ -50,8 +51,6 @@ export const isInSettledSection = (lines: readonly string[], index: number): boo
   return above !== undefined && headings.includes(above.trim())
 }
 
-const twoDigits = (value: number): string => String(value).padStart(2, '0')
-
 /** Local time as the board writes it: `DD.MM. hh:mm` in German, `YYYY-MM-DD hh:mm` in English. */
 export const settledTime = (time: Date, language: PlanLanguage): string =>
   BOARD_TEXTS[language].time({

package/src/shared/is-record.ts

@@ -0,0 +1,2 @@
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)

package/src/shared/private-records.ts

@@ -0,0 +1,48 @@
+import { chmodSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const RECORD_FILE = /^[0-9a-f]{12}\.json$/
+const MAX_RECORD_BYTES = 16 * 1024
+const PRIVATE_FILE = 0o600
+const PRIVATE_DIRECTORY = 0o700
+
+const recordAt = <T>(path: string, isRecordOfKind: (value: unknown) => value is T): T[] => {
+  try {
+    const entry = lstatSync(path)
+    if (!entry.isFile() || entry.size > MAX_RECORD_BYTES) return []
+    const record: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isRecordOfKind(record) ? [record] : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Every well-formed `<id>.json` record in `directory` (a symbolic link, an oversized file and one the guard refuses are
+ * skipped), ascending by `sortKey`; nothing when the directory is missing or unreadable.
+ */
+export const readRecords = <T>(
+  directory: string,
+  isRecordOfKind: (value: unknown) => value is T,
+  sortKey: (record: T) => number,
+): T[] => {
+  try {
+    return readdirSync(directory)
+      .filter((name) => RECORD_FILE.test(name))
+      .flatMap((name) => recordAt(join(directory, name), isRecordOfKind))
+      .sort((left, right) => sortKey(left) - sortKey(right))
+  } catch {
+    return []
+  }
+}
+
+/** Writes `<id>.json` through a temporary file, `0600` in a `0700` directory, so a reader never sees half of it. */
+export const writeRecordAtomically = <T extends { id: string }>(directory: string, record: T): void => {
+  mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
+  chmodSync(directory, PRIVATE_DIRECTORY)
+  const path = join(directory, `${record.id}.json`)
+  const temporary = `${path}.${process.pid}.tmp`
+  writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: PRIVATE_FILE })
+  chmodSync(temporary, PRIVATE_FILE)
+  renameSync(temporary, path)
+}

package/src/task-signals/agent.ts

@@ -0,0 +1,15 @@
+import { cleanAgentName } from './text'
+
+const WORKTREE = /[\\/]\.claude[\\/]worktrees[\\/]([^\\/]+)/
+
+const MAIN_AGENT = 'main'
+
+/**
+ * Who is reporting: the herdr pane when `HERDR_PANE_ID` is set (an agent has its own pane), else the worktree the
+ * directory lies in (`.claude/worktrees/<name>`), else `main`.
+ */
+export const agentIdentity = (environment: Record<string, string | undefined>, cwd: string): string => {
+  const pane = cleanAgentName(environment.HERDR_PANE_ID ?? '')
+  if (pane) return `pane ${pane}`
+  return WORKTREE.exec(cwd)?.[1] ?? MAIN_AGENT
+}

package/src/task-signals/claude-read.ts

@@ -0,0 +1,72 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { readTailLines } from '../context/session-log'
+import { isRecord } from '../shared/is-record'
+import { claudeSignalsOf } from './claude-signals'
+import { cleanAgentName } from './text'
+import type { TaskSignal } from './types'
+
+const SUBAGENT_LOG = /^(agent-[A-Za-z0-9]+)\.jsonl$/
+
+/** How much of the end of a log is read by default: sessions grow to hundreds of megabytes. */
+const SIGNAL_TAIL_BYTES = 8 * 1024 * 1024
+
+export type ReadOptions = {
+  /** How many bytes from the end of each log are read; a task created before that is unknown, so it gives no signal. */
+  tailBytes?: number
+  /** Subagent logs last written before this (epoch milliseconds) are left out. */
+  notOlderThan?: number
+}
+
+const linesOf = (path: string, tailBytes: number): string[] => {
+  try {
+    return readTailLines(path, tailBytes)
+  } catch {
+    return []
+  }
+}
+
+/** The subagent's own description when its `.meta.json` has one, else the log's name. */
+const agentNameOf = (directory: string, stem: string): string => {
+  try {
+    const meta: unknown = JSON.parse(readFileSync(join(directory, `${stem}.meta.json`), 'utf8'))
+    const description = isRecord(meta) ? meta.description : null
+    const name = typeof description === 'string' ? cleanAgentName(description) : ''
+    return name || stem
+  } catch {
+    return stem
+  }
+}
+
+const isRecent = (path: string, notOlderThan: number): boolean => {
+  try {
+    return statSync(path).mtimeMs >= notOlderThan
+  } catch {
+    return false
+  }
+}
+
+const subagentSignals = (directory: string, tailBytes: number, notOlderThan: number): TaskSignal[] => {
+  try {
+    return readdirSync(directory)
+      .sort()
+      .flatMap((name) => {
+        const stem = SUBAGENT_LOG.exec(name)?.[1]
+        const path = join(directory, name)
+        return stem && isRecent(path, notOlderThan)
+          ? claudeSignalsOf(linesOf(path, tailBytes), agentNameOf(directory, stem))
+          : []
+      })
+  } catch {
+    return []
+  }
+}
+
+/** The tasks in progress in a Claude Code session log and in every `<session>/subagents/agent-*.jsonl` beside it. */
+export const readClaudeSignals = (
+  sessionLogPath: string,
+  { tailBytes = SIGNAL_TAIL_BYTES, notOlderThan = 0 }: ReadOptions = {},
+): TaskSignal[] => [
+  ...claudeSignalsOf(linesOf(sessionLogPath, tailBytes), 'session'),
+  ...subagentSignals(join(sessionLogPath.replace(/\.jsonl$/, ''), 'subagents'), tailBytes, notOlderThan),
+]

package/src/task-signals/claude-signals.ts

@@ -0,0 +1,112 @@
+import { parseLogEntry } from '../context/session-log'
+import { isRecord } from '../shared/is-record'
+import { cleanTaskText } from './text'
+import type { TaskSignal } from './types'
+
+type Block = Record<string, unknown>
+
+type TaskDraft = { subject?: unknown; activeForm?: unknown; description?: unknown }
+
+type TrackedTask = { text: string; startedAt: number | null }
+
+type Tracker = {
+  pending: Map<string, TaskDraft>
+  tasks: Map<string, TrackedTask>
+  todos: Map<string, number>
+  cwd: string
+  time: number
+}
+
+const TASK_STATUS = {
+  pending: 'pending',
+  inProgress: 'in_progress',
+  completed: 'completed',
+  deleted: 'deleted',
+} as const
+
+const recordsIn = (values: unknown): Block[] => (Array.isArray(values) ? values.filter(isRecord) : [])
+
+const firstText = (...candidates: unknown[]): string =>
+  candidates.map((candidate) => (typeof candidate === 'string' ? cleanTaskText(candidate) : '')).find(Boolean) ?? ''
+
+const blocksOf = (entry: Record<string, unknown>): Block[] => {
+  return recordsIn(isRecord(entry.message) ? entry.message.content : undefined)
+}
+
+const createdIdOf = (entry: Record<string, unknown>, block: Block): string | null => {
+  const task = isRecord(entry.toolUseResult) ? entry.toolUseResult.task : undefined
+  const id = isRecord(task) ? task.id : undefined
+  if (typeof id === 'string' || typeof id === 'number') return String(id)
+  const match = typeof block.content === 'string' ? /^Task #(\S+) created/.exec(block.content) : null
+  return match ? match[1] : null
+}
+
+const onResult = (tracker: Tracker, entry: Record<string, unknown>, block: Block): void => {
+  const draft = typeof block.tool_use_id === 'string' ? tracker.pending.get(block.tool_use_id) : undefined
+  if (!draft) return
+  const id = createdIdOf(entry, block)
+  if (id === null) return
+  tracker.tasks.set(id, { text: firstText(draft.subject, draft.activeForm, draft.description), startedAt: null })
+}
+
+const onTaskUpdate = (tracker: Tracker, input: Record<string, unknown>): void => {
+  const id = typeof input.taskId === 'string' || typeof input.taskId === 'number' ? String(input.taskId) : null
+  const task = id === null ? undefined : tracker.tasks.get(id)
+  if (id === null || !task) return
+  if (input.status === TASK_STATUS.completed || input.status === TASK_STATUS.deleted) {
+    tracker.tasks.delete(id)
+    return
+  }
+  const renamed = firstText(input.subject)
+  if (renamed) task.text = renamed
+  if (input.status === TASK_STATUS.inProgress && task.startedAt === null) task.startedAt = tracker.time
+  if (input.status === TASK_STATUS.pending) task.startedAt = null
+}
+
+const onTodoWrite = (tracker: Tracker, input: Record<string, unknown>): void => {
+  const todos = recordsIn(input.todos)
+  const active = new Map<string, number>()
+  for (const todo of todos) {
+    const text = todo.status === TASK_STATUS.inProgress ? firstText(todo.content, todo.activeForm) : ''
+    if (text) active.set(text, tracker.todos.get(text) ?? tracker.time)
+  }
+  tracker.todos = active
+}
+
+const onToolUse = (tracker: Tracker, block: Block): void => {
+  const input = block.input
+  if (!isRecord(input)) return
+  if (block.name === 'TaskCreate' && typeof block.id === 'string') tracker.pending.set(block.id, input)
+  if (block.name === 'TaskUpdate') onTaskUpdate(tracker, input)
+  if (block.name === 'TodoWrite') onTodoWrite(tracker, input)
+}
+
+const visit = (tracker: Tracker, entry: Record<string, unknown>): void => {
+  const time = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
+  if (!Number.isNaN(time)) tracker.time = time
+  if (typeof entry.cwd === 'string') tracker.cwd = entry.cwd
+  for (const block of blocksOf(entry)) {
+    if (block.type === 'tool_use') onToolUse(tracker, block)
+    if (block.type === 'tool_result') onResult(tracker, entry, block)
+  }
+}
+
+/**
+ * The tasks one Claude Code session log (or subagent log), given as its lines, has in progress at its end: a
+ * `TaskCreate` whose `TaskUpdate` set `in_progress` and none completed or deleted, plus the `in_progress` entries of
+ * the last `TodoWrite`. A line that is no JSON is skipped. Oldest first.
+ */
+export const claudeSignalsOf = (lines: readonly string[], agent: string): TaskSignal[] => {
+  const tracker: Tracker = { pending: new Map(), tasks: new Map(), todos: new Map(), cwd: '', time: 0 }
+  for (const line of lines) {
+    const entry = parseLogEntry(line)
+    if (entry) visit(tracker, entry)
+  }
+  const started = [...tracker.tasks.values()].flatMap(({ text, startedAt }) =>
+    startedAt === null || !text ? [] : [{ text, startedAt }],
+  )
+  const todos = [...tracker.todos].map(([text, startedAt]) => ({ text, startedAt }))
+  return [...started, ...todos]
+    .sort((left, right) => left.startedAt - right.startedAt)
+    .map(({ text, startedAt }) => ({ agent, source: 'claude', text, startedAt, cwd: tracker.cwd }))
+}

package/src/task-signals/command.ts

@@ -0,0 +1,71 @@
+import { mainCheckout } from '../plans/git'
+import { CLI_NAME } from '../version/release'
+import { agentIdentity } from './agent'
+import type { TaskRecord } from './record'
+import { buildTaskId } from './record'
+import { finishTask, openTaskOf, startTask } from './record-store'
+import { cleanTaskText } from './text'
+
+export const USAGE = `usage: ${CLI_NAME} task start "<task text>"
+       ${CLI_NAME} task done ["<task text>"]
+
+start  report the task you begin; the herd shows it as the one being worked on
+done   report it finished; with text, only when it names the open task
+One task per agent: a new start replaces the previous one.`
+
+export type TaskCommand =
+  | { kind: 'start'; text: string }
+  | { kind: 'done'; text: string }
+  | { kind: 'help' }
+  | { kind: 'usage' }
+
+/** The command line as a command: the words after `start` or `done` are the task text, whether quoted or not. */
+export const parseTaskCommand = (args: readonly string[]): TaskCommand => {
+  const [name, ...words] = args
+  if (name === '--help' || name === '-h') return { kind: 'help' }
+  const text = cleanTaskText(words.join(' '))
+  if (name === 'start' && text !== '') return { kind: 'start', text }
+  if (name === 'done') return { kind: 'done', text }
+  return { kind: 'usage' }
+}
+
+export type DoneReport = { exitCode: number; message: string | null }
+
+/** What `jh task done` says: nothing without an open task (a second call is no error), else the closed task or why the text did not close it. */
+export const doneReport = (open: TaskRecord | null, closed: TaskRecord | null): DoneReport => {
+  if (open === null) return { exitCode: 0, message: null }
+  if (closed === null) return { exitCode: 1, message: `the open task is: ${open.text}` }
+  return { exitCode: 0, message: `done: ${closed.text}` }
+}
+
+const newId = (): string => buildTaskId(crypto.getRandomValues(new Uint8Array(6)))
+
+/**
+ * `jh task start "<text>"` reports the task the calling agent begins, `jh task done ["<text>"]` that it is finished.
+ * Exit 0; 1 on a wrong command line or when the text of `done` names another task than the open one. `done` without
+ * an open task is silent and exits 0.
+ */
+export const run = (args: string[]): number => {
+  const command = parseTaskCommand(args)
+  if (command.kind === 'help') {
+    console.log(USAGE)
+    return 0
+  }
+  if (command.kind === 'usage') {
+    console.error(USAGE)
+    return 1
+  }
+  const cwd = process.cwd()
+  const root = mainCheckout(cwd)
+  const agent = agentIdentity(process.env, cwd)
+  const now = Date.now()
+  if (command.kind === 'start') {
+    const record = startTask(root, { agent, text: command.text, cwd, newId }, now)
+    console.log(`started: ${record.text}`)
+    return 0
+  }
+  const open = openTaskOf(root, agent)
+  const { exitCode, message } = doneReport(open, finishTask(root, agent, command.text, now))
+  if (message !== null) (exitCode === 0 ? console.log : console.error)(message)
+  return exitCode
+}

package/src/task-signals/fixtures/session.jsonl

@@ -0,0 +1,7 @@
+{"type":"assistant","timestamp":"1999-04-03T10:00:00.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_use","id":"toolu_A","name":"TaskCreate","input":{"subject":"Write the parser","activeForm":"Writing the parser","description":"Parse the input"}}]}}
+{"type":"user","timestamp":"1999-04-03T10:00:01.000Z","cwd":"/work/project","toolUseResult":{"task":{"id":"1","subject":"Write the parser"}},"message":{"content":[{"type":"tool_result","tool_use_id":"toolu_A","content":"Task \u00231 created successfully: Write the parser"}]}}
+{"type":"assistant","timestamp":"1999-04-03T10:00:02.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_use","id":"toolu_B","name":"TaskCreate","input":{"subject":"Add the tests","activeForm":"Adding the tests"}}]}}
+{"type":"user","timestamp":"1999-04-03T10:00:03.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_result","tool_use_id":"toolu_B","content":"Task \u00232 created successfully: Add the tests"}]}}
+{"type":"assistant","timestamp":"1999-04-03T10:00:04.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_use","id":"toolu_C","name":"TaskUpdate","input":{"taskId":"1","status":"in_progress"}},{"type":"tool_use","id":"toolu_D","name":"TaskUpdate","input":{"taskId":"2","status":"in_progress"}}]}}
+{"type":"assistant","timestamp":"1999-04-03T10:00:09.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_use","id":"toolu_E","name":"TaskUpdate","input":{"taskId":"2","status":"completed"}}]}}
+not json

package/src/task-signals/matcher.ts

@@ -0,0 +1,96 @@
+import { MAX_TASK_TEXT } from './text'
+import type { TaskSignal } from './types'
+
+/** An open task of a plan: where it stands (`phaseId`, index among the phase's items) and its text. */
+export type OpenPlanTask = { phaseId: string; taskIndex: number; text: string }
+
+export type MatchedSignal = { signal: TaskSignal; task: OpenPlanTask | null }
+
+/** Shorter than this, a text names nothing: it would match any task. */
+const MIN_TEXT = 4
+/** A whole plan task found inside a longer signal must be this long, or "Tests" claims every signal about tests. */
+const MIN_TASK_INSIDE_SIGNAL = 12
+/** Shorter words (`PR`, `und`, `die`, numbers) carry no meaning for similar wording. */
+const MIN_WORD = 4
+/** Two forms of one word share at least this many letters from the start. */
+const MIN_STEM = 4
+/** And differ in at most this many letters at the end of the shorter one: German endings, `-en`, `-er`, `-e`. */
+const MAX_ENDING = 2
+/** Similar wording needs this many of the signal's words in the task, so two shared words claim nothing. */
+const MIN_SIMILAR_WORDS = 3
+/** And this share of them. */
+const MIN_SIMILAR_SHARE = 0.75
+
+const normalised = (text: string): string =>
+  text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim()
+
+const headOf = (task: OpenPlanTask): string => task.text.slice(0, MAX_TASK_TEXT)
+
+const isPrefix = (signalText: string, task: OpenPlanTask): boolean =>
+  signalText.length >= MIN_TEXT && headOf(task).startsWith(signalText)
+
+const isContained = (signalText: string, task: OpenPlanTask): boolean => {
+  const signal = normalised(signalText)
+  const head = normalised(headOf(task))
+  if (signal.length < MIN_TEXT) return false
+  return head.includes(signal) || (head.length >= MIN_TASK_INSIDE_SIGNAL && signal.includes(head))
+}
+
+const wordsOf = (text: string): string[] =>
+  normalised(text)
+    .split(' ')
+    .filter((word) => word.length >= MIN_WORD)
+
+const commonPrefix = (first: string, second: string): number => {
+  let length = 0
+  while (length < first.length && first[length] === second[length]) length += 1
+  return length
+}
+
+/** One word, two forms: equal, or the same stem with a short ending of its own (`roter`, `roten`; `kompakter`, `kompaktere`). */
+const sameWord = (first: string, second: string): boolean => {
+  const shared = commonPrefix(first, second)
+  return first === second || (shared >= MIN_STEM && shared >= Math.min(first.length, second.length) - MAX_ENDING)
+}
+
+/** How many of the signal's words the task's head holds, and their share of the signal's words. */
+const similarity = (signalWords: readonly string[], task: OpenPlanTask): { matched: number; share: number } => {
+  const taskWords = wordsOf(headOf(task))
+  const matched = signalWords.filter((word) => taskWords.some((each) => sameWord(word, each))).length
+  return { matched, share: signalWords.length === 0 ? 0 : matched / signalWords.length }
+}
+
+/**
+ * The task whose head holds most of the signal's words, each in any inflected form, when at least `MIN_SIMILAR_WORDS`
+ * and `MIN_SIMILAR_SHARE` of them; null otherwise. For an agent that names a task in its own words.
+ */
+const similarTask = (tasks: readonly OpenPlanTask[], signalText: string): OpenPlanTask | null => {
+  const signalWords = [...new Set(wordsOf(signalText))]
+  const scored = tasks
+    .map((task) => ({ task, ...similarity(signalWords, task) }))
+    .filter(({ matched, share }) => matched >= MIN_SIMILAR_WORDS && share >= MIN_SIMILAR_SHARE)
+  return (
+    scored.reduce<(typeof scored)[number] | null>(
+      (best, each) => (best === null || each.share > best.share ? each : best),
+      null,
+    )?.task ?? null
+  )
+}
+
+/**
+ * The plan task each signal belongs to, else null (an unplanned task). An exact prefix of a task's text wins over text
+ * containment (case, punctuation and spacing ignored, in either direction, on the first 200 characters of the task),
+ * and containment over similar wording (`similarTask`). Several signals may match several tasks of several phases,
+ * and several signals the same task.
+ */
+export const matchSignals = (tasks: readonly OpenPlanTask[], signals: readonly TaskSignal[]): MatchedSignal[] =>
+  signals.map((signal) => ({
+    signal,
+    task:
+      tasks.find((task) => isPrefix(signal.text, task)) ??
+      tasks.find((task) => isContained(signal.text, task)) ??
+      similarTask(tasks, signal.text),
+  }))

package/src/task-signals/record-store.ts

@@ -0,0 +1,40 @@
+import { join } from 'node:path'
+import { readRecords, writeRecordAtomically } from '../shared/private-records'
+import { isTaskRecord, namesTask, openRecord, type TaskRecord } from './record'
+import { cleanAgentName } from './text'
+
+const directoryOf = (root: string): string => join(root, '.jackherd', 'tasks')
+
+/** Every well-formed record in the main checkout's `.jackherd/tasks/`, oldest first; nothing when the directory is missing. */
+export const readTaskRecords = (root: string): TaskRecord[] =>
+  readRecords(directoryOf(root), isTaskRecord, ({ startedAt }) => startedAt)
+
+/** The agent's open record, null when it has none. */
+export const openTaskOf = (root: string, agent: string): TaskRecord | null => {
+  const wanted = cleanAgentName(agent)
+  return readTaskRecords(root).find((record) => record.agent === wanted && record.closedAt === null) ?? null
+}
+
+/** Starts a task for `agent`. The agent's one record is reused (its id kept) and reopened with the new task. */
+export const startTask = (
+  root: string,
+  fields: { agent: string; text: string; cwd: string; newId: () => string },
+  now: number,
+): TaskRecord => {
+  const previous = readTaskRecords(root).find(({ agent }) => agent === cleanAgentName(fields.agent))
+  const record = openRecord({ ...fields, id: previous?.id ?? fields.newId() }, now)
+  writeRecordAtomically(directoryOf(root), record)
+  return record
+}
+
+/**
+ * Closes the agent's open task; with `text`, only when it names that task. Returns the closed record, or null when
+ * the agent has no open task or the text names another.
+ */
+export const finishTask = (root: string, agent: string, text: string, now: number): TaskRecord | null => {
+  const open = openTaskOf(root, agent)
+  if (!open || !namesTask(open, text)) return null
+  const closed = { ...open, closedAt: now }
+  writeRecordAtomically(directoryOf(root), closed)
+  return closed
+}