jackherd 1.16.0 → 1.18.0

package/src/plans/live.ts

@@ -47,10 +47,7 @@ import {
   parseMouse,
   splitKeys,
   syncLaneFolds,
-  TOP_BLOCK,
-  type TopBlockId,
   toggledExpansion,
-  topBlockHeadKey,
   type View,
   windowTop,
   withoutStaleMotions,
@@ -527,18 +524,18 @@ const applyBlockClick = (live: Live, outcome: BlockClick): void => {
 }
 
 /**
- * A plain click on a block on top of the herd, matched against `hit` as it was drawn: the head of `block` folds or
- * opens it (a block of entries, `block` null, has no such head), a
+ * A plain click on a block on top of the herd, matched against `hit` as it was drawn: the head folds or
+ * opens its block, a
  * cut-off row expands, a file or Artifact opens, a button asks the coordinator or closes the row; the failure or the
  * result shows in the footer.
  */
-const clickBlock = (live: Live, block: TopBlockId | null, hit: BlockHit | null, input: string): boolean => {
+const clickBlock = (live: Live, hit: BlockHit | null, input: string): boolean => {
   const mouse = parseMouse(input)
   if (!mouse || !hit) return false
-  if (block !== null && blockHeadClick(hit.firstLine - 1, mouse)) {
+  if (hit.headKey && blockHeadClick(hit.firstLine - 1, mouse)) {
     live.view = {
       ...live.view,
-      selection: applyClick(live.view.selection, topBlockHeadKey(block)),
+      selection: applyClick(live.view.selection, hit.headKey),
     }
     return true
   }
@@ -588,7 +585,6 @@ const handleInput = (live: Live, input: string) => {
     hover(live, screen, mouse)
     return
   }
-  live.notice = null
   const settled = settledSelection(live.view.selection, screen)
   live.view = { ...live.view, selection: mouse ? settled : withoutHover(settled) }
   if (activateBlockRow(live, screen, input)) {
@@ -600,9 +596,9 @@ const handleInput = (live: Live, input: string) => {
     return
   }
   if (
-    clickBlock(live, TOP_BLOCK.yourTurn, screen.yourTurnBlock, input) ||
-    screen.entryBlocks.some((hit) => clickBlock(live, null, hit, input)) ||
-    clickBlock(live, TOP_BLOCK.sources, screen.sourceBlock, input)
+    clickBlock(live, screen.yourTurnBlock, input) ||
+    screen.entryBlocks.some((hit) => clickBlock(live, hit, input)) ||
+    clickBlock(live, screen.sourceBlock, input)
   ) {
     redraw(live)
     return

package/src/plans/plan-panes.ts

@@ -35,6 +35,14 @@ export type PlanPaneResult = { actions: PaneAction[]; notes: string[] }
 
 type ListedPane = { pane_id: string; tab_id: string; cwd: string; agent?: unknown; label?: unknown }
 
+/**
+ * The exit codes of `herd --ensure`: `noCoordinator` when the coordinator's pane is missing or ambiguous, so a
+ * caller that runs it after a restart knows to wait for the coordinator's session; 1 stays the error of the CLI.
+ */
+export const ENSURE_EXIT = { done: 0, noCoordinator: 3 } as const
+
+export type EnsureExit = (typeof ENSURE_EXIT)[keyof typeof ENSURE_EXIT]
+
 const isListedPane = (value: unknown): value is ListedPane => {
   if (typeof value !== 'object' || value === null) return false
   const candidate = value as Record<string, unknown>
@@ -124,9 +132,13 @@ export const isIdleShell = ({ agent, foreground }: PaneState): boolean =>
 const isStartingShell = ({ agent, foreground }: PaneState): boolean =>
   !agent && (foreground.length === 0 || SHELLS.has(programOf(foreground[0])))
 
+const hasHerdBeside = (panes: readonly PaneState[], agent: PaneState): boolean =>
+  panes.some((each) => each.tab === agent.tab && each.label === herdLabel(null))
+
 /**
  * The coordinator's pane: the agent herdr lists under the coordinator's name, else the calling pane when an agent
- * in the main checkout runs there, else the only agent in the main checkout. Two agents there and no name: none.
+ * in the main checkout runs there, else the only agent in the main checkout, else the only one there whose tab holds
+ * a pane labelled `herd` (herdr keeps labels across a restart, agent names not always). Otherwise none.
  */
 export const coordinatorPaneOf = (
   panes: readonly PaneState[],
@@ -136,15 +148,20 @@ export const coordinatorPaneOf = (
   if (hints.named) return hints.named
   const inRoot = panes.filter((each) => each.agent && each.cwd === root)
   if (hints.caller && inRoot.some((each) => each.pane === hints.caller)) return hints.caller
-  return inRoot.length === 1 ? (inRoot[0]?.pane ?? null) : null
+  const candidates = inRoot.length === 1 ? inRoot : inRoot.filter((agent) => hasHerdBeside(panes, agent))
+  return candidates.length === 1 ? (candidates[0]?.pane ?? null) : null
 }
 
-/** Why no coordinator pane was found: no agent in the main checkout, or several and none of them named. */
+/** The exit code of `herd --ensure` for the coordinator pane it found among `panes`, or none. */
+export const ensureExitOf = (panes: readonly PaneState[], coordinator: string | null): EnsureExit =>
+  panes.some((each) => each.pane === coordinator) ? ENSURE_EXIT.done : ENSURE_EXIT.noCoordinator
+
+/** Why no coordinator pane was found: no agent in the main checkout, or several, none named and none alone beside a herd pane. */
 export const missingCoordinatorNote = (panes: readonly PaneState[], root: string, name: string): string => {
   const inRoot = panes.filter((each) => each.agent && each.cwd === root).length
   return inRoot === 0
     ? 'coordinator: no agent in the main checkout'
-    : `coordinator: ${inRoot} agents in the main checkout and none named ${name}; run herd --ensure in its pane, or herdr agent rename <pane> ${name}`
+    : `coordinator: ${inRoot} agents in the main checkout, none named ${name} and none alone beside a herd pane; run herd --ensure in its pane, or herdr agent rename <pane> ${name}`
 }
 
 const quoted = (arg: string): string => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`)

package/src/plans/selection.ts

@@ -27,6 +27,8 @@ export type Selection = {
   laneFolds: ReadonlyMap<string, LaneFold>
   /** The top blocks the user opened; every other one is folded, at the start of the herd all of them. */
   openBlocks?: ReadonlySet<TopBlockId>
+  /** The sources whose block of entries the user folded; absent or without the source while it is open, as at the start. */
+  foldedEntryBlocks?: ReadonlySet<string>
   /** True once the user folded the lanes block, which is open at the start; absent or false while it is open. */
   lanesFolded?: boolean
 }
@@ -110,6 +112,26 @@ export const topBlockHeadKey = (block: TopBlockId): string => `${TOP_HEAD_KEY_PR
 export const topBlockOfKey = (key: string): TopBlockId | null =>
   Object.values(TOP_BLOCK).find((block) => topBlockHeadKey(block) === key) ?? null
 
+const ENTRY_HEAD_KEY_PREFIX = `${TOP_HEAD_KEY_PREFIX}entries>`
+
+/** The key of the head of the block of entries of a source, which the arrows reach like every other clickable row. */
+export const entryBlockHeadKey = (source: string): string => `${ENTRY_HEAD_KEY_PREFIX}${source}`
+
+/** The source whose block of entries a head key names, null for any other key. */
+export const entryBlockOfKey = (key: string): string | null =>
+  key.startsWith(ENTRY_HEAD_KEY_PREFIX) ? key.slice(ENTRY_HEAD_KEY_PREFIX.length) : null
+
+/** Whether the block of entries of `source` is drawn folded: it is open at the start, until the user folds it. */
+export const isEntryBlockFolded = ({ foldedEntryBlocks }: Selection, source: string): boolean =>
+  foldedEntryBlocks?.has(source) === true
+
+const withEntryBlockOpen = (selection: Selection, source: string, open: boolean): Selection => {
+  const folded = new Set(selection.foldedEntryBlocks)
+  if (open) folded.delete(source)
+  else folded.add(source)
+  return { ...selection, foldedEntryBlocks: folded }
+}
+
 /** Whether the lanes block is drawn open: it is at the start of the herd, until the user folds it. */
 export const isLanesOpen = ({ lanesFolded }: Selection): boolean => !lanesFolded
 
@@ -274,6 +296,13 @@ const foldedHead = (selection: Selection, key: string, next: (open: boolean) =>
   const lane = laneOfKey(key)
   if (lane !== null) return { ...foldLane(selection, lane, next), selected: key }
   if (key === LANES_KEY) return { ...withLanesOpen(selection, next(isLanesOpen(selection))), selected: key }
+  const entrySource = entryBlockOfKey(key)
+  if (entrySource !== null) {
+    return {
+      ...withEntryBlockOpen(selection, entrySource, next(!isEntryBlockFolded(selection, entrySource))),
+      selected: key,
+    }
+  }
   const block = topBlockOfKey(key)
   if (block === null) return null
   return { ...withBlockOpen(selection, block, next(!isBlockFolded(selection, block))), selected: key }

package/src/plans/settings.ts

@@ -4,6 +4,7 @@ import { type JackherdConfig, parseJackherdConfig } from '../config'
 import { PROJECT_CONFIG_PATH } from '../config/location'
 import { readConfig } from '../config/read-config'
 import type { ToneName } from '../config/tones'
+import { DEFAULT_MIN_FREE_GB } from '../lane/space'
 import type { TicketSource } from '../watch/plan-badges'
 import type { SourceShow } from '../watch/sources'
 import { type WatchedSource, watchedSourceOf } from '../watch/watched-source'
@@ -15,6 +16,8 @@ export type PlansSettings = Pick<
   'planDirectory' | 'board' | 'worktreeDirectory' | 'baseBranch' | 'planLanguage' | 'responseLanguage' | 'skillPrefix'
 > & {
   adapter: JackherdConfig['terminal']['adapter']
+  /** Free gigabytes a new lane needs on the disk (`lanes.minFreeGb`). */
+  minFreeGb: number
   fetchIntervalMinutes: number
   /** Whether the running task of a folded lane shimmers; `NO_COLOR` keeps it still whatever this says. */
   shimmer: boolean
@@ -58,6 +61,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   responseLanguage: config.responseLanguage,
   skillPrefix: config.skillPrefix,
   adapter: config.terminal.adapter,
+  minFreeGb: config.lanes.minFreeGb ?? DEFAULT_MIN_FREE_GB,
   fetchIntervalMinutes: config.plans.fetchIntervalMinutes,
   shimmer: config.plans.shimmer,
   linkKinds: config.plans.linkKinds,

package/src/resume/command.ts

@@ -0,0 +1,213 @@
+import { join } from 'node:path'
+import { type SendPorts, sendLanePrompt } from '../lane/send'
+import { errorText } from '../plans/error-text'
+import type { PlanLanguage } from '../vocabulary'
+import { type ResumeDecision, resumeDecision } from './decision'
+import { type ResumeRecord, resumedRecord } from './record'
+import { type AgentPane, type Streak, steadyTarget, TARGET_MISS, type TargetMissed, targetFor } from './targets'
+import { resumeTexts } from './texts'
+
+type Limits = { attempts: number; intervalMs: number }
+
+/**
+ * After a crash the coordinator's session was back after ~8 s and the lanes' after ~3 s (`RESTORE_LIMITS`), but a slow
+ * machine resuming many sessions at once takes longer, and a message lost here is a lost restart: three minutes each
+ * for the coordinator and for the lanes, polled every two seconds.
+ */
+export const RESUME_LIMITS = {
+  coordinator: { attempts: 90, intervalMs: 2_000 },
+  lanes: { attempts: 90, intervalMs: 2_000 },
+} as const satisfies Record<string, Limits>
+
+/** A record file and what it holds; null for a damaged one. */
+export type RecordEntry = { path: string; record: ResumeRecord | null }
+
+/** What `jh resume` reads and does; `run` wires them to the files, the watcher lock and herdr. */
+export type ResumePorts = {
+  now: () => number
+  records: () => RecordEntry[]
+  /** The record at `path` once more, right before it is marked. */
+  reread: (path: string) => ResumeRecord | null
+  writeRecord: (path: string, record: ResumeRecord) => void
+  watcherRunning: (root: string) => boolean
+  boardExists: (board: string) => boolean
+  settingsOf: (root: string) => { language: PlanLanguage; worktreeDirectory: string }
+  /** herdr's agent panes; throws with herdr's error when it does not answer. */
+  agentPanes: () => AgentPane[]
+  send: SendPorts
+  sleep: (ms: number) => Promise<void>
+  log: (root: string, message: string) => void
+  notify: (title: string, body: string) => void
+}
+
+type Resume = Extract<ResumeDecision, { kind: 'resume' }>
+
+type Recipient = { name: string; directory: string }
+
+type Search = { found: Map<Recipient, string>; missed: Map<Recipient, TargetMissed> }
+
+const NOTE_TITLE = 'jackherd resume'
+
+const missLine = (who: string, miss: TargetMissed): string => {
+  if (miss.reason === TARGET_MISS.ambiguous)
+    return `${who}: no target, ${miss.panes.length} unnamed agent panes (${miss.panes.join(', ')}); nothing sent`
+  if (miss.reason === TARGET_MISS.elsewhere)
+    return `${who}: no target, the agent of that name runs in another directory (${miss.panes.join(', ')}); nothing sent`
+  return `${who}: no target, the agent did not come back in time; nothing sent`
+}
+
+const planLine = ({ coordinator, interrupted, blocked }: Resume): string =>
+  `resume: coordinator ${coordinator}, interrupted ${interrupted.join(', ') || '-'}, blocked ${blocked.join(', ') || '-'}`
+
+/** herdr's panes of one poll; none, with a log line, when herdr does not answer. */
+const pollPanes = (ports: ResumePorts, root: string): AgentPane[] => {
+  try {
+    return ports.agentPanes()
+  } catch (error) {
+    ports.log(root, `herdr did not answer: ${errorText(error)}`)
+    return []
+  }
+}
+
+/**
+ * Polls herdr until every recipient has a steady target (`steadyTarget`) or the window is used up; `onFound` runs for
+ * each as soon as it has one. Returns the targets found and, for the others, the last miss.
+ */
+const awaitTargets = async (
+  ports: ResumePorts,
+  root: string,
+  recipients: readonly Recipient[],
+  limits: Limits,
+  onFound: (target: string) => Promise<void>,
+): Promise<Search> => {
+  const search: Search = { found: new Map(), missed: new Map() }
+  const streaks = new Map<Recipient, Streak>()
+  for (let attempt = 1; search.found.size < recipients.length; attempt++) {
+    const panes = pollPanes(ports, root)
+    for (const recipient of recipients.filter((each) => !search.found.has(each))) {
+      const steady = steadyTarget(targetFor(panes, recipient.name, recipient.directory), streaks.get(recipient) ?? null)
+      streaks.set(recipient, steady.streak)
+      if (steady.target.kind === 'none') search.missed.set(recipient, steady.target)
+      else {
+        search.found.set(recipient, steady.target.target)
+        search.missed.delete(recipient)
+        await onFound(steady.target.target)
+      }
+    }
+    if (search.found.size === recipients.length || attempt >= limits.attempts) break
+    await ports.sleep(limits.intervalMs)
+  }
+  return search
+}
+
+const reportMisses = (ports: ResumePorts, root: string, missed: Search['missed'], who: (name: string) => string) => {
+  for (const [recipient, miss] of missed) {
+    const line = missLine(who(recipient.name), miss)
+    ports.log(root, line)
+    if (miss.reason !== TARGET_MISS.missing) ports.notify(NOTE_TITLE, `${root} ${line}`)
+  }
+}
+
+/**
+ * Marks the record as resumed, after reading it once more: a record another start marked or a new watcher replaced
+ * in between is left alone. False when it was left alone or could not be written, so nothing is sent.
+ */
+const marked = (ports: ResumePorts, path: string, record: ResumeRecord): boolean => {
+  const current = ports.reread(path)
+  if (current === null || current.resumedAt !== null || current.startedAt !== record.startedAt) {
+    ports.log(record.root, 'record changed since it was read; nothing sent')
+    return false
+  }
+  try {
+    ports.writeRecord(path, resumedRecord(current, ports.now()))
+    return true
+  } catch (error) {
+    ports.log(record.root, `cannot mark the record (${errorText(error)}); nothing sent`)
+    return false
+  }
+}
+
+const sendTo = async (ports: ResumePorts, root: string, target: string, text: string) => {
+  ports.log(root, (await sendLanePrompt(ports.send, target, text)).line)
+}
+
+/** The coordinator's target once it is back in the main checkout; null, logged, when it is not within the window. */
+const awaitCoordinator = async (ports: ResumePorts, decision: Resume): Promise<string | null> => {
+  const recipient = { name: decision.coordinator, directory: decision.root }
+  const search = await awaitTargets(ports, decision.root, [recipient], RESUME_LIMITS.coordinator, async () => {})
+  reportMisses(ports, decision.root, search.missed, (name) => `no coordinator ${name}`)
+  return search.found.get(recipient) ?? null
+}
+
+const resumeLanes = async (ports: ResumePorts, decision: Resume, worktreeDirectory: string, text: string) => {
+  const recipients = decision.interrupted.map((name) => ({
+    name,
+    directory: join(decision.root, worktreeDirectory, name),
+  }))
+  const search = await awaitTargets(ports, decision.root, recipients, RESUME_LIMITS.lanes, (target) =>
+    sendTo(ports, decision.root, target, text),
+  )
+  reportMisses(ports, decision.root, search.missed, (name) => name)
+}
+
+/**
+ * Wakes one repository: waits for its coordinator first, since a coordinator that never comes back here runs in
+ * another herdr session and its record stays for that one; marks the record; then sends the coordinator its line and
+ * each interrupted lane its text.
+ */
+const resumeRepository = async (ports: ResumePorts, path: string, record: ResumeRecord, decision: Resume) => {
+  const { language, worktreeDirectory } = ports.settingsOf(decision.root)
+  const texts = resumeTexts(language)
+  ports.log(decision.root, planLine(decision))
+  if (decision.unsafe.length > 0) ports.log(decision.root, `left out, no lane names: ${decision.unsafe.join(', ')}`)
+  const coordinator = await awaitCoordinator(ports, decision)
+  if (coordinator === null || !marked(ports, path, record)) return
+  const line = texts.coordinatorLine(decision.board, decision.interrupted, decision.blocked)
+  await sendTo(ports, decision.root, coordinator, line)
+  await resumeLanes(ports, decision, worktreeDirectory, texts.laneText)
+}
+
+const resumeEntry = async (ports: ResumePorts, path: string, record: ResumeRecord) => {
+  const decision = resumeDecision({
+    record,
+    now: ports.now(),
+    watcherRunning: ports.watcherRunning(record.root),
+    boardExists: ports.boardExists(record.board),
+  })
+  if (decision.kind === 'none') ports.log(record.root, decision.reason)
+  else await resumeRepository(ports, path, record, decision)
+}
+
+/** Every repository with a record, one after the other; a failure in one is logged and the next goes on. Always 0. */
+export const resumeAll = async (ports: ResumePorts): Promise<number> => {
+  try {
+    const entries = ports.records()
+    if (entries.length === 0) ports.log('-', 'no resume record')
+    for (const { path, record } of entries) {
+      try {
+        if (record === null) ports.log(path, 'damaged record, read as none')
+        else await resumeEntry(ports, path, record)
+      } catch (error) {
+        ports.log(record?.root ?? path, `failed: ${errorText(error)}`)
+      }
+    }
+  } catch (error) {
+    ports.log('-', `cannot read the records: ${errorText(error)}`)
+  }
+  return 0
+}
+
+/**
+ * `jh resume`: herdr's second `[[startup]]` hook. After a crash of the watcher (its record still marked running, no
+ * watcher holding the lock now) sends the coordinator one fixed `/orchestrate … ` line and each lane that worked one
+ * fixed text, at most once per record. Every step goes to `~/.jackherd/logs/resume.log`; the exit code is always 0,
+ * a hook leaves nothing behind but its log.
+ */
+export const run = async (args: string[]): Promise<number> => {
+  if (args.length > 0) {
+    console.log('Usage: jh resume   (run by the herdr plugin when herdr starts; takes no arguments)')
+    return args.includes('--help') || args.includes('-h') ? 0 : 1
+  }
+  const { systemResumePorts } = await import('./ports')
+  return resumeAll(systemResumePorts())
+}

package/src/resume/decision.ts

@@ -0,0 +1,102 @@
+import { isAbsolute, relative, sep } from 'node:path'
+import { AGENT_STATUS, type AgentStatus } from '../terminal/types'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+import type { ResumeRecord } from './record'
+
+/** Why `jh resume` leaves a repository alone. */
+export const RESUME_SKIP = {
+  noRecord: 'no-record',
+  stopped: 'stopped',
+  resumed: 'resumed',
+  stale: 'stale',
+  watcherRunning: 'watcher-running',
+  boardMissing: 'board-missing',
+  unsafeBoard: 'unsafe-board',
+  unsafeCoordinator: 'unsafe-coordinator',
+} as const
+
+export type ResumeSkip = (typeof RESUME_SKIP)[keyof typeof RESUME_SKIP]
+
+/**
+ * How long after the watcher last saved its record a herdr start still resumes: a crash in the evening
+ * and a herdr start the next morning resume, a start days later does not, since the interrupted commands then meet
+ * code that has moved on. Measured from `savedAt`.
+ */
+export const RESUME_MAX_AGE_MS = 12 * 60 * 60 * 1000
+
+export type ResumeInput = {
+  record: ResumeRecord | null
+  /** The time of this herdr start, against which the record's age is measured. */
+  now: number
+  /** Whether a watcher holds the repository's lock now: then herdr was handed over live, nothing crashed. */
+  watcherRunning: boolean
+  boardExists: boolean
+}
+
+export type ResumeDecision =
+  | { kind: 'none'; reason: ResumeSkip }
+  | {
+      kind: 'resume'
+      root: string
+      /** The board relative to the main checkout, one path without blanks, as the coordinator line carries it. */
+      board: string
+      coordinator: string
+      /** The lanes that worked when the watcher went down; each gets the resume text. */
+      interrupted: string[]
+      /** The lanes that waited for an answer; only named to the coordinator. */
+      blocked: string[]
+      /** Lane names that are no single file name: never sent to, only logged. */
+      unsafe: string[]
+    }
+
+/** Blanks, control and format characters (bidi marks, zero-width ones): a board path with them is not one plain word. */
+const NOT_ONE_WORD = /[\s\p{Cc}\p{Cf}]/u
+
+/** The board relative to `root`, null when it is not a file inside it or would not stay one word on the line. */
+const boardInside = (root: string, board: string): string | null => {
+  const path = relative(root, board)
+  const outside = path === '' || path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)
+  return outside || NOT_ONE_WORD.test(path) ? null : path
+}
+
+/** A single file name that herdr cannot read as an option: `herdr agent prompt <target> …` takes it as an argument. */
+const isSafeName = (name: string): boolean => SAFE_LANE_NAME.test(name) && !name.startsWith('-')
+
+const lanesWith = (lanes: Record<string, string>, status: AgentStatus): string[] =>
+  Object.entries(lanes).flatMap(([name, laneStatus]) => (laneStatus === status && isSafeName(name) ? [name] : []))
+
+const skip = (reason: ResumeSkip): ResumeDecision => ({ kind: 'none', reason })
+
+/** The reason the record itself gives against a restart, checked before what the system says now. */
+const recordSkip = (record: ResumeRecord, now: number): ResumeSkip | null => {
+  if (record.stoppedAt !== null) return RESUME_SKIP.stopped
+  if (record.resumedAt !== null) return RESUME_SKIP.resumed
+  if (now - record.savedAt > RESUME_MAX_AGE_MS) return RESUME_SKIP.stale
+  return null
+}
+
+/**
+ * Whether a herdr start follows a crash of the watcher and whom to wake: a record still marked running, never resumed,
+ * saved within `RESUME_MAX_AGE_MS`, with no watcher running now and its board in place. Only lanes that worked get a
+ * message; names that are no single file name, a coordinator name of that kind and a board outside the main checkout
+ * never reach a send.
+ */
+export const resumeDecision = ({ record, now, watcherRunning, boardExists }: ResumeInput): ResumeDecision => {
+  if (record === null) return skip(RESUME_SKIP.noRecord)
+  const reason = recordSkip(record, now)
+  if (reason !== null) return skip(reason)
+  if (watcherRunning) return skip(RESUME_SKIP.watcherRunning)
+  if (!isSafeName(record.coordinator)) return skip(RESUME_SKIP.unsafeCoordinator)
+  const board = boardInside(record.root, record.board)
+  if (board === null) return skip(RESUME_SKIP.unsafeBoard)
+  if (!boardExists) return skip(RESUME_SKIP.boardMissing)
+  return {
+    kind: 'resume',
+    root: record.root,
+    board,
+    coordinator: record.coordinator,
+    interrupted: lanesWith(record.lanes, AGENT_STATUS.working),
+    blocked: lanesWith(record.lanes, AGENT_STATUS.blocked),
+    unsafe: Object.keys(record.lanes).filter((name) => !isSafeName(name)),
+  }
+}

package/src/resume/keeper.ts

@@ -0,0 +1,65 @@
+import { errorText } from '../plans/error-text'
+import type { LaneSnapshot } from '../watch/lane-watch'
+import { followedRecord, type RecordStart, type ResumeRecord, runningRecord, stoppedRecord } from './record'
+
+/** The one record file of a repository; `read` gives null for a missing or damaged one. */
+export type RecordStore = {
+  read: () => ResumeRecord | null
+  write: (record: ResumeRecord) => void
+}
+
+export type KeeperPorts = {
+  store: RecordStore
+  log: (line: string) => void
+}
+
+/** What the watcher calls: `follow` at every herdr poll, `stop` once on a clean end. */
+export type RecordKeeper = {
+  follow: (lanes: LaneSnapshot, now: number) => void
+  stop: (now: number) => void
+}
+
+export const laneStatusesOf = (snapshot: LaneSnapshot): Record<string, string> =>
+  Object.fromEntries(Object.entries(snapshot).map(([name, lane]) => [name, lane.status]))
+
+/**
+ * Keeps the resume record of the watcher in `start.pid` beside its loop: running at the start, saved when a lane status
+ * changes or `RESUME_REFRESH_MS` is up, stamped as stopped at a clean end unless a successor holds the file by then (a
+ * missing or damaged file is left alone). A write that fails is retried at the next poll and logged once per series; it
+ * never ends the watch, since without the record a crash only goes unresumed.
+ *
+ * Accepted: `follow` writes without reading the file first, so a predecessor that outlived `takeOverLock`'s wait can
+ * overwrite its successor's record until the successor's next write.
+ */
+export const keepRecord = (start: RecordStart, now: number, ports: KeeperPorts): RecordKeeper => {
+  let failing = false
+  const attempt = (action: () => void): boolean => {
+    try {
+      action()
+      if (failing) ports.log('resume record written again')
+      failing = false
+      return true
+    } catch (error) {
+      if (!failing) ports.log(`resume record failed: ${errorText(error)}`)
+      failing = true
+      return false
+    }
+  }
+  let current = runningRecord(start, now)
+  let unsaved = !attempt(() => ports.store.write(current))
+  return {
+    follow: (lanes, at) => {
+      const next = followedRecord(current, laneStatusesOf(lanes), at)
+      if (next === current && !unsaved) return
+      current = next
+      unsaved = !attempt(() => ports.store.write(next))
+    },
+    stop: (at) => {
+      attempt(() => {
+        const stored = ports.store.read()
+        const stopped = stored === null ? null : stoppedRecord(stored, start.pid, at)
+        if (stopped !== null) ports.store.write(stopped)
+      })
+    },
+  }
+}

package/src/resume/location.ts

@@ -0,0 +1,22 @@
+import { dirname } from 'node:path'
+import { isOwnedBy } from '../../kit/hooks/hooks/shared/private-directory'
+import { isPrivateLevels, type LocationSystem } from '../shared/private-location'
+
+const OTHERS_WRITE = 0o002
+
+/**
+ * Whether `jh resume` may trust the records in `directory`: the directory itself is the user's, no link, closed to
+ * group and others (`isPrivateLevels`), and the level above (`~/.jackherd`) is the user's, no link and closed to others'
+ * writes, so nobody else can swap the directory. That level is checked less strictly: it holds the user's own config,
+ * and a umask of `002` leaves it open to the user's own group.
+ */
+export const isTrustedRecordDirectory = (directory: string, system: LocationSystem): boolean => {
+  const parent = system.entryAt(dirname(directory))
+  const parentHolds =
+    parent !== null &&
+    !parent.isSymbolicLink() &&
+    parent.isDirectory() &&
+    isOwnedBy(parent, system.uid) &&
+    (parent.mode & OTHERS_WRITE) === 0
+  return parentHolds && isPrivateLevels(directory, directory, system)
+}

package/src/resume/log.ts

@@ -0,0 +1,27 @@
+import { join } from 'node:path'
+import { TOOL_DIRECTORY } from '../config/location'
+import { terminalSafe } from '../plan-format/terminal-text'
+
+/** How many lines the resume log keeps: a few restarts' worth, so one can be checked afterwards. */
+export const RESUME_LOG_LINES = 200
+
+const LOG_DIRECTORY = 'logs'
+const LOG_FILE = 'resume.log'
+
+export const resumeLogDirectory = (home: string): string => join(home, TOOL_DIRECTORY, LOG_DIRECTORY)
+
+export const resumeLogPath = (home: string): string => join(resumeLogDirectory(home), LOG_FILE)
+
+/**
+ * One log line: the time, the repository and the step. A line break of herdr's answers becomes a blank, and every
+ * other control character is dropped (`terminalSafe`): the line is also printed, and a name read from a record must
+ * not act on the terminal.
+ */
+export const logLine = (now: number, root: string, message: string): string =>
+  terminalSafe(`${new Date(now).toISOString()} ${root} ${message}`.replace(/\s*\n\s*/g, ' '))
+
+/** The log with `lines` appended, cut to its last `max` lines. */
+export const trimmedLog = (existing: string | null, lines: readonly string[], max: number): string => {
+  const kept = [...(existing ?? '').split('\n').filter((line) => line !== ''), ...lines]
+  return `${kept.slice(-max).join('\n')}\n`
+}