jackherd 1.9.0 → 1.10.0

package/src/plans/subagents-read.ts

@@ -1,9 +1,11 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { projectDirectoryOf, readTailLines } from '../context/session-log'
+import { defaultProjectsDirectory, projectDirectoryOf, readTailLines } from '../context/session-log'
 import { MS_PER_MINUTE } from '../plan-format/clock'
+import { DEFAULT_SKILL_PREFIX } from '../sync/init'
 import { readApprovalRequests } from '../watch/approvals'
 import {
+  type RunningSubagent,
   runningSubagents,
   SUBAGENT_STALE_MINUTES,
   type SubagentActivity,
@@ -19,8 +21,19 @@ export type SubagentSource = {
   approvalsRoot: string
   /** The absolute worktree directory. */
   worktreeDirectory: string
+  /** The project's `skillPrefix`, which its copies of the review agents carry; without it only the default one counts. */
+  skillPrefix?: string
 }
 
+/** The source of the main checkout `root`: Claude Code's own session logs, the gate's requests in the checkout itself. */
+export const subagentSourceOf = (root: string, worktreeDirectory: string, skillPrefix?: string): SubagentSource => ({
+  projects: defaultProjectsDirectory(),
+  root,
+  approvalsRoot: root,
+  worktreeDirectory,
+  skillPrefix,
+})
+
 /** The end of a log that holds the directory of the last entries. */
 const TAIL_BYTES = 64 * 1024
 const META_FILE = /^agent-([0-9a-f]+)\.meta\.json$/
@@ -35,6 +48,15 @@ const directoriesOf = (path: string): string[] => {
   }
 }
 
+/** The entry names of `path`; none when it is missing or cannot be read. */
+const namesIn = (path: string): string[] => {
+  try {
+    return readdirSync(path)
+  } catch {
+    return []
+  }
+}
+
 const logOf = (directory: string, name: string, id: string, now: number): SubagentLog[] => {
   try {
     const logPath = join(directory, `agent-${id}.jsonl`)
@@ -47,22 +69,39 @@ const logOf = (directory: string, name: string, id: string, now: number): Subage
   }
 }
 
-/**
- * The subagents with a recently written log in the sessions started in the main checkout `root`, from Claude Code's
- * `<projects>/<project>/<session>/subagents/agent-<id>.{meta.json,jsonl}`; whatever cannot be read is left out.
- */
-export const readSubagentLogs = (projects: string, root: string, now: number): SubagentLog[] => {
-  const project = join(projects, projectDirectoryOf(root))
-  return directoriesOf(project).flatMap((session) => {
+/** 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')
-    if (!existsSync(directory)) return []
-    return readdirSync(directory).flatMap((name) => {
+    return namesIn(directory).flatMap((name) => {
       const id = META_FILE.exec(name)?.[1]
       return id ? logOf(directory, name, id, now) : []
     })
   })
+
+/**
+ * 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.
+ */
+const projectDirectoriesOf = (projects: string, root: string, worktreeDirectory?: string): string[] => {
+  const main = projectDirectoryOf(root)
+  const lanes = worktreeDirectory === undefined ? null : `${projectDirectoryOf(worktreeDirectory)}-`
+  return directoriesOf(projects).filter((name) => name === main || (lanes !== null && name.startsWith(lanes)))
 }
 
+/**
+ * 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
+ * is left out.
+ */
+export const readSubagentLogs = (
+  projects: string,
+  root: string,
+  now: number,
+  worktreeDirectory?: string,
+): SubagentLog[] =>
+  projectDirectoriesOf(projects, root, worktreeDirectory).flatMap((name) => sessionLogsOf(join(projects, name), now))
+
 /** The names the gate holds an open request under, as the watcher reads them. */
 const heldNames = (root: string, now: number): Set<string> =>
   new Set(
@@ -71,12 +110,22 @@ const heldNames = (root: string, now: number): Set<string> =>
       .map((request) => request.lane),
   )
 
-/** The state of every worktree a subagent of the main checkout's sessions works in. */
-export const readSubagentActivity = (
-  { projects, root, approvalsRoot, worktreeDirectory }: SubagentSource,
+/**
+ * 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(),
-): Map<string, SubagentActivity> =>
-  subagentsByLane(
-    runningSubagents(readSubagentLogs(projects, root, now), heldNames(approvalsRoot, now), now, worktreeDirectory),
+): RunningSubagent[] =>
+  runningSubagents(
+    readSubagentLogs(projects, root, now, worktreeDirectory),
+    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)

package/src/plans/subagents.ts

@@ -4,6 +4,8 @@ import { terminalSafe } from '../plan-format/terminal-text'
 import { isRecord } from '../shared/is-record'
 import { AGENT_STATUS, type AgentStatus } from '../terminal/types'
 import { activityTextOf } from './current-task'
+import { type PhaselessReview, type SubagentPhaseRun, subagentPhaseRunOf } from './subagent-phases'
+import type { DescribedSubagent } from './subagent-tasks'
 import { laneDirectoryOf } from './unlisted-lanes'
 
 /** What the log files of one subagent say: its id, its `meta.json` as parsed, when the log was written, its last lines. */
@@ -17,10 +19,25 @@ export type RunningSubagent = {
   status: Extract<AgentStatus, 'working' | 'blocked'>
   /** The text of its last log entries, from which the herd tells the task it works on (`taskSignalsOf`). */
   activity: string
+  /** The phases its full description names (`P21`, `P17-P20`), none for a review that names none; null for any other. */
+  phaseRun: SubagentPhaseRun | null
+  /** When its log was last written. */
+  writtenAt: number
 }
 
-/** What a worktree shows of the subagents working in it. */
-export type SubagentActivity = Pick<RunningSubagent, 'status' | 'description' | 'activity'>
+/** What a worktree shows of the subagents working in it; `phaseRuns` are those of all its subagents that name a phase. */
+export type SubagentActivity = Pick<RunningSubagent, 'status' | 'description' | 'activity'> & {
+  phaseRuns: SubagentPhaseRun[]
+  /** Its reviews that name no phase; the lane places them on its signalled phase (`laneSummary`). */
+  phaselessReviews: PhaselessReview[]
+  /**
+   * The descriptions of its other subagents that name no phase: what they work on, a signal of the lane like a
+   * reported task.
+   */
+  taskDescriptions: string[]
+  /** Its subagents that are no review, phase or not; one whose description starts with a task's short name sits on it. */
+  describedSubagents: DescribedSubagent[]
+}
 
 /**
  * A log untouched this long is not at work: Claude Code marks a finished subagent with `finished: true` in its
@@ -85,18 +102,21 @@ const workingDirectory = (tail: readonly string[], worktreeDirectory: string): s
 /**
  * The subagents at work: no `finished` mark in the meta, and the log written within `SUBAGENT_STALE_MINUTES`. One
  * waits for an answer while the approval gate holds a request under its name (`openRequests` are the names of the open
- * requests); the transcript alone cannot tell a permission dialog from a long tool call.
+ * requests); the transcript alone cannot tell a permission dialog from a long tool call. `reviewPrefixes` are the skill
+ * prefixes a copy of the review agents may carry.
  */
 export const runningSubagents = (
   logs: readonly SubagentLog[],
   openRequests: ReadonlySet<string>,
   now: number,
   worktreeDirectory: string,
+  reviewPrefixes: readonly string[],
 ): RunningSubagent[] =>
   logs.flatMap(({ id, meta, modifiedAt, tail }) => {
     if (!isRecord(meta) || meta.finished === true || now - modifiedAt > SUBAGENT_STALE_MINUTES * MS_PER_MINUTE)
       return []
-    const label = subagentLabelOf(id, textOrNull(meta.agentType))
+    const agentType = textOrNull(meta.agentType)
+    const label = subagentLabelOf(id, agentType)
     if (label === null) return []
     const description = textOrNull(typeof meta.description === 'string' ? terminalSafe(meta.description) : null)
     const shortDescription = description?.slice(0, DESCRIPTION_LENGTH) ?? null
@@ -107,25 +127,63 @@ export const runningSubagents = (
         description: shortDescription,
         status: openRequests.has(label) ? AGENT_STATUS.blocked : AGENT_STATUS.working,
         activity: activityTextOf(tail, ACTIVITY_ENTRIES),
+        phaseRun: subagentPhaseRunOf(description, agentType, modifiedAt, reviewPrefixes),
+        writtenAt: modifiedAt,
       },
     ]
   })
 
+/** The description of a subagent that names no phase, as a list of at most one; empty for a review or one that names a phase. */
+const taskDescriptionOf = ({ phaseRun, description }: RunningSubagent): string[] =>
+  phaseRun === null && description !== null ? [description] : []
+
+/** A subagent that is no review, with its description, as a list of at most one. */
+const describedSubagentOf = ({ phaseRun, description, writtenAt }: RunningSubagent): DescribedSubagent[] =>
+  description !== null && (phaseRun === null || phaseRun.review === null) ? [{ description, at: writtenAt }] : []
+
+/** The run of a subagent that names a phase, as a list of at most one. */
+const namedRunOf = ({ phaseRun }: RunningSubagent): SubagentPhaseRun[] =>
+  phaseRun !== null && phaseRun.ids.length > 0 ? [phaseRun] : []
+
+/** A review that names no phase, as a list of at most one. */
+const phaselessReviewOf = ({ phaseRun, description }: RunningSubagent): PhaselessReview[] => {
+  if (phaseRun === null || phaseRun.review === null || phaseRun.ids.length > 0) return []
+  return [{ review: phaseRun.review, at: phaseRun.at, description }]
+}
+
 /** The worktrees below `worktreeDirectory` the subagents work in; one that waits for an answer decides the state. */
 export const subagentsByLane = (
   running: readonly RunningSubagent[],
   worktreeDirectory: string,
 ): Map<string, SubagentActivity> => {
   const lanes = new Map<string, SubagentActivity>()
-  for (const { cwd, status, description, activity } of running) {
+  for (const subagent of running) {
+    const { cwd, status, description, activity } = subagent
     const lane = cwd === null ? null : laneDirectoryOf(cwd, worktreeDirectory)
     if (lane === null) continue
     const known = lanes.get(lane)
-    if (!known) lanes.set(lane, { status, description, activity })
+    const runs = namedRunOf(subagent)
+    const reviews = phaselessReviewOf(subagent)
+    const tasks = taskDescriptionOf(subagent)
+    const described = describedSubagentOf(subagent)
+    if (!known)
+      lanes.set(lane, {
+        status,
+        description,
+        activity,
+        phaseRuns: runs,
+        phaselessReviews: reviews,
+        taskDescriptions: tasks,
+        describedSubagents: described,
+      })
     else
       lanes.set(lane, {
         ...(status === AGENT_STATUS.blocked && known.status !== AGENT_STATUS.blocked ? { status, description } : known),
         activity: `${known.activity} ${activity}`,
+        phaseRuns: [...known.phaseRuns, ...runs],
+        phaselessReviews: [...known.phaselessReviews, ...reviews],
+        taskDescriptions: [...known.taskDescriptions, ...tasks],
+        describedSubagents: [...known.describedSubagents, ...described],
       })
   }
   return lanes

package/src/plans/supervisor.ts

@@ -4,6 +4,7 @@ import { dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { pendingKitUpdate, VERSION_POLL_MS } from '../version/installed-version'
 import type { StartedKit } from '../version/started-kit'
+import { STOP_REQUEST, type Stopper, stopperOf } from './child-stop'
 import { HERD_COMMAND } from './herd-command'
 import { CHILD_MARKER, exitCodeOf, isRestartTrigger, nextStep, RESTART_DEBOUNCE_MS } from './restart-decision'
 import { TERMINAL_OFF } from './view'
@@ -30,7 +31,8 @@ const spawnView = (scriptPath: string, args: string[]): ChildProcess =>
 /**
  * Runs the live view as a child process and restarts it when the package's own source changes,
  * so a long-lived `plans` never shows the behaviour of code that has since been edited. The child
- * stops on SIGTERM through the handler that restores the terminal. Resolves with the exit code
+ * stops on SIGTERM through the handler that restores the terminal, and is killed when it does not end within
+ * `GRACE_MS` (a restart included); a second signal while stopping kills it at once. Resolves with the exit code
  * of a wanted end only: the child's clean exit (`q`) or a signal forwarded to it. A child that
  * dies otherwise leaves the supervisor waiting, with the terminal restored, for the next change
  * to `src/`, which spawns a fresh child. `kit` is the package this process loaded (null when it cannot be
@@ -45,6 +47,7 @@ export const superviseView = (
 ): Promise<number> =>
   new Promise((resolveExit) => {
     let child: ChildProcess | undefined
+    let stopper: Stopper | undefined
     let restarting = false
     let stopping = false
     let timer: ReturnType<typeof setTimeout> | undefined
@@ -66,6 +69,12 @@ export const superviseView = (
     const start = (isFirst: boolean): void => {
       const current = spawnView(scriptPath, args)
       child = current
+      const currentStopper = stopperOf({
+        kill: (signal) => current.kill(signal),
+        setTimer: (run, ms) => setTimeout(run, ms),
+        clearTimer: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+      })
+      stopper = currentStopper
 
       current.on('error', (error) => {
         if (child !== current) return
@@ -79,6 +88,7 @@ export const superviseView = (
       })
 
       current.on('exit', (code, signal) => {
+        currentStopper.ended()
         if (child !== current) return
         const context = { restarting, stopping, code, signal }
         restarting = false
@@ -94,7 +104,7 @@ export const superviseView = (
     const restartView = (): void => {
       if (child) {
         restarting = true
-        child.kill('SIGTERM')
+        stopper?.request('SIGTERM')
       } else start(false)
     }
 
@@ -118,8 +128,8 @@ export const superviseView = (
         stopping = true
         clearTimeout(timer)
         clearInterval(versionTimer)
-        if (child) child.kill(signal)
-        else finish(exitCodeOf(null, signal))
+        if (!child || !stopper) finish(exitCodeOf(null, signal))
+        else if (stopper.request(signal) === STOP_REQUEST.killed) finish(exitCodeOf(null, signal))
       })
     }
   })

package/src/plans/symbols.ts

@@ -21,6 +21,9 @@ export const statusWord = (agent: string | null): string => agent ?? NO_AGENT_WO
 /** Before a row that opens and closes: lanes, the planned phases, the ticked items 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. */
+export const LESS_MARK = '▴'
+
 export const chevronOf = (open: boolean): string => (open ? CHEVRON.open : CHEVRON.closed)
 
 export const PHASE_STATE = { missing: 'missing', empty: 'empty', all: 'all', open: 'open' } as const

package/src/plans/task-name.ts

@@ -0,0 +1,34 @@
+const TASK_NAME = /^\*\*([^*]+)\*\*:/
+
+const TITLE_END = ': '
+
+const titleEndOf = (text: string): number => {
+  let inCode = false
+  for (let index = 0; index < text.length; index++) {
+    if (text[index] === '`') inCode = !inCode
+    else if (!inCode && text.startsWith(TITLE_END, index)) return index
+  }
+  return -1
+}
+
+/**
+ * The text up to its first colon followed by a space outside backticks, as a folded row shows it; the text as it is
+ * without such a colon or with nothing before it. A time like `18:55` has no space after its colon and does not split.
+ */
+export const shortTitle = (text: string): string => {
+  const end = titleEndOf(text)
+  return end > 0 ? text.slice(0, end) : text
+}
+
+/**
+ * The short name a task carries in bold at its start, `**Name**: content`, as written; null for a line without one.
+ * Nothing is guessed from the text up to its first colon: a path at the start of a line would read as a name.
+ */
+export const taskNameOf = (text: string): string | null => {
+  const name = text.match(TASK_NAME)?.[1]?.trim()
+  return name ? name : null
+}
+
+/** The text after a task's `**Name**:`, as an opened task shows it under its name; the text as it is without a name. */
+export const taskBodyOf = (text: string): string =>
+  taskNameOf(text) === null ? text : text.replace(TASK_NAME, '').trimStart()

package/src/plans/texts.ts

@@ -3,11 +3,11 @@ import { CHECK_NAME_LENGTH, CHECKS, type ChecksState, type PullRequest } from '.
 import { shownWithMore } from './shown-with-more'
 import { MODEL_MARK, NO_AGENT_WORD, PHASE_COUNT } from './symbols'
 
-/** The words of an open lane: the age of a running phase, the word before the open phases that wait, the finished phases not merged yet, and the pointer of a phase with only its review gate open. */
+/** The words of an open lane: the age of a running phase, the words before the open phases that wait and the finished ones, and the pointer of a phase with only its review gate open. */
 export type HerdTexts = {
   minutesAgo: (minutes: number) => string
   next: string
-  notMerged: string
+  done: string
   reviewGate: string
   gate: string
 }
@@ -23,9 +23,14 @@ export type PlanTexts = {
   noPlan: string
   noWorktree: string
   noRow: string
+  /** The heads of the blocks on top of the herd. */
+  waitingHeading: string
+  appointmentHeading: string
   notInPlan: string
   /** Before a task an agent reports that no task of the plan names. */
   now: string
+  /** Before the description of a running subagent that names no phase and sits on none. */
+  subagent: string
   /** In place of the count of a phase whose only open box is the documentation box of its review gate. */
   allButDocs: string
   tickedSummary: (count: number) => string
@@ -36,7 +41,13 @@ export type PlanTexts = {
   herd: HerdTexts
   checks: Record<ChecksState, string>
   hint: string
+  /** The notice when `a` is pressed with no phase open, where the key changes nothing on screen. */
+  showDoneNeedsPhase: string
   legend: string[]
+  /** The footer line when the coordinator could not be asked to put a question, with the reason. */
+  notAsked: (reason: string) => string
+  /** The footer line when the coordinator `name` was asked to put `subject`, `question <id>` or `board row <key>`. */
+  asked: (name: string, subject: string) => string
 }
 
 /** The words of the watcher's badges and of the header notice when they are missing. */
@@ -78,8 +89,11 @@ export const TEXTS: PlanTexts = {
   noPlan: 'no plan',
   noWorktree: 'no worktree',
   noRow: 'no row in lanes',
+  waitingHeading: 'Waiting for you',
+  appointmentHeading: 'Appointments',
   notInPlan: 'not in the plan',
   now: 'now:',
+  subagent: 'Subagent:',
   allButDocs: ALL_BUT_DOCS,
   tickedSummary: (count) => `${count} ticked · click or a lists them`,
   draft: 'draft · ',
@@ -88,7 +102,7 @@ export const TEXTS: PlanTexts = {
   herd: {
     minutesAgo: (minutes) => (minutes === 0 ? '· just now' : `· ${minutes} min ago`),
     next: 'next',
-    notMerged: 'not merged',
+    done: 'done',
     reviewGate: 'Review gate',
     gate: '· gate',
   },
@@ -100,16 +114,19 @@ export const TEXTS: PlanTexts = {
     [CHECKS.pending]: '… checks',
     [CHECKS.none]: 'no checks',
   },
-  hint: '↑↓ select  →← open  a show ticked  s html  q quit  ? help',
+  hint: '↑↓ select  →← open  a ticked tasks  s html  q quit  ? help',
+  showDoneNeedsPhase: 'a lists the ticked tasks inside an open phase: open one with → or a click',
   legend: [
     'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a link chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
     '● working · ◆ blocked, waits for you · ◉ done = the agent finished its answer, not the lane · ○ idle · (·) no agent = a worktree nobody works in · • state unknown · only blocked wears its word in the lane line, the symbol says the rest · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · a working or blocked lane opens by itself only when it first appears, after that → ← and clicks are yours alone',
-    `▸ ▾ open and close · an open lane's branches, top down: the agent's title and ⎇ its branch, ↗ its pull requests, its link chips, the phases it works on, next, ✓ · a lane shows only the phases its board rows name · a phase row = some of its tasks are ticked, one of its boxes was ticked in the last ${STALE_ACTIVITY_MINUTES} min, or an agent reports working on it, by number · n min ago since the last tick or report, · gate = only the review gate is open · ▶ teal = a task an agent reported (its task list or jh task; its name dim at the right edge when several agents work in the lane), ▷ dim = only guessed from the words of its log · now: <text> = a reported task no plan task names · next = the other open phases, as ranges · ✓ the finished ones, not merged = ticked in the worktree, not on the base branch yet · ${ALL_BUT_DOCS} = only the documentation box is open · a folded lane line names the phase moved last, +n more active ones, and its count · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a lists the ticked checkboxes one by one · s opens every lane and plan as one HTML page`,
+    `▸ ▾ open and close · an open lane's branches, top down: the agent's title and ⎇ its branch, ↗ its pull requests, its link chips, the phases it works on, next, done · a lane shows only the phases its board rows name · a phase row = some of its tasks are ticked, one of its boxes was ticked in the last ${STALE_ACTIVITY_MINUTES} min, or an agent reports working on it, by number · n min ago since the last tick or report, · gate = only the review gate is open · ▶ teal = a task an agent reported (its task list or jh task; its name dim at the right edge when several agents work in the lane), ▷ dim = only guessed from the words of its log · now: <text> = a reported task no plan task names · a running review sits on the gate box that names it, in the phase it names or else the lane's current one · Subagent: <text> = a running subagent that names no phase and sits on none · next = the other open phases, as ranges · done = the finished ones · ${ALL_BUT_DOCS} = only the documentation box is open · a folded lane line names the phase moved last, +n more active ones, and its count · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a lists the ticked checkboxes of an open phase one by one · s opens every lane and plan as one HTML page`,
     `the bar = progress over the lane's plans · n/m = m checkboxes, n ticked · n/m ph = n of m phases finished · n/n in green = all ticked · 🥣 share of the context window used, on a folded lane only once it warns · Sonnet ${MODEL_MARK.differs} Opus in amber = the phase's subagent ran on another model than the plan's`,
     '↗ pull request · 💬 new feedback · ✋ changes requested · 🌐 preview · 📡 ticket: chip 📡 T-1 · status among the link chips, 📡 <n> in amber on a folded lane when tickets are new',
-    '▌ on top = waits for your answer: 📎 a file or an Artifact that was sent (click: a cut-off row expands, then it opens), ? a question of the board · it goes when the board row is closed or `jh waiting close <id>` · woof closes the block',
+    '▌ on top = waits for your answer: 📎 a file or an Artifact that was sent (click: a cut-off row expands, then it opens), ? a question of the board or one a session left in its dialog (a click on its text only expands and folds it; [ask] at the right edge of a question asks the coordinator to put it) · it goes when the board row is closed or `jh waiting close <id>` · `Waiting for you` heads the block (click: fold; click on +n: show all, on ▴ n: five) · ◷ the appointments of the board in a grey bar below it (click: fold)',
     '⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main',
   ],
+  notAsked: (reason) => `no coordinator to ask: ${reason}`,
+  asked: (name, subject) => `asked ${name} for ${subject}`,
 }
 
 /** The mark of a running lane the board has no row for; null for a lane it lists. */

package/src/plans/view.ts

@@ -1,3 +1,4 @@
+import { ARTIFACT_LINK_KIND } from '../config/link-kinds'
 import { fit, plainText } from '../terminal/text'
 import { renderSelected, type Screen } from './layout'
 import type { Options } from './options'
@@ -20,7 +21,9 @@ const paneRows = (): number => process.stdout.rows ?? Number.MAX_SAFE_INTEGER
 export const bodyRows = (screen: Screen): number =>
   Math.max(paneRows() - screen.header.length - screen.footer.length, 1)
 
-export const clockOf = (locale: string): string => new Date().toLocaleTimeString(locale)
+/** The time as `HH:MM`, in the header and in the refresh error alike: a frame differs only once a minute. */
+export const clockOf = (locale: string, now: Date = new Date()): string =>
+  now.toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' })
 
 export const renderSnapshot = (
   snapshot: Snapshot,
@@ -38,6 +41,7 @@ export const renderSnapshot = (
       watch: snapshot.watch,
       watchesTickets: snapshot.watchesTickets,
       awaiting: snapshot.waiting,
+      appointments: snapshot.appointments,
       unplaced: snapshot.unplaced,
     },
     selection,
@@ -50,19 +54,23 @@ export const startSelection = (snapshot: Snapshot, options: Options): Selection
   options.lane ? laneSelection(snapshot.views[0]?.progress) : overviewSelection()
 
 /** Header and footer stay put; the body shows `bodyRows` lines from `top`, padded so the footer sits at the bottom. */
-export const draw = (screen: Screen, top: number): void => {
-  const width = paneWidth()
-  const rows = bodyRows(screen)
+export const frameOutput = (screen: Screen, top: number, width: number, rows: number): string => {
   const body = screen.body.lines.slice(top, top + rows)
   const padding = Array.from({ length: Math.max(rows - body.length, 0) }, () => '')
   const lines = [...screen.header, ...body, ...padding, ...screen.footer]
-  process.stdout.write(
-    `${CURSOR_HOME}${lines.map((line) => `${fit(line, width)}${CLEAR_LINE_END}`).join('\r\n')}${CLEAR_BELOW}`,
-  )
+  return `${CURSOR_HOME}${lines.map((line) => `${fit(line, width)}${CLEAR_LINE_END}`).join('\r\n')}${CLEAR_BELOW}`
 }
 
-/** One frame as text; ANSI styling is dropped when stdout is not a terminal. */
+/** The frame to write, or null when the terminal already shows it; a null `previous` means the terminal content is unknown. */
+export const frameToWrite = (previous: string | null, next: string): string | null => (previous === next ? null : next)
+
+const ARTIFACT_ADDRESS = new RegExp(ARTIFACT_LINK_KIND.pattern)
+
+/**
+ * One frame as text; ANSI styling is dropped when stdout is not a terminal, and links are written out as their
+ * address, except an Artifact's, which is long and would push the rest of its line past the pane.
+ */
 export const frameText = (screen: Screen, isTerminal: boolean): string => {
   const lines = [...screen.header, ...screen.body.lines, ...screen.footer]
-  return (isTerminal ? lines : lines.map(plainText)).join('\n')
+  return (isTerminal ? lines : lines.map((line) => plainText(line, (url) => !ARTIFACT_ADDRESS.test(url)))).join('\n')
 }