jackherd 1.16.0 → 1.17.0

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`
+}

package/src/resume/ports.ts

@@ -0,0 +1,102 @@
+import { lstatSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import { herdrSendPorts } from '../lane/send-herdr'
+import { errorText } from '../plans/error-text'
+import { readSettings } from '../plans/settings'
+import { readPrivateText, systemLocation } from '../shared/private-location'
+import { herdrRunner } from '../terminal/herdr'
+import { isWatcherRunning, WATCHER_FILES, watcherDirectoryOf } from '../watch/watcher-lock'
+import type { RecordEntry, ResumePorts } from './command'
+import type { RecordStore } from './keeper'
+import { isTrustedRecordDirectory } from './location'
+import { logLine, RESUME_LOG_LINES, resumeLogDirectory, resumeLogPath, trimmedLog } from './log'
+import { isRecordFileOf, parseResumeRecord, type ResumeRecord, resumeRecordDirectory, resumeRecordPath } from './record'
+import { resumablePanesOf } from './targets'
+
+const RECORD_FILE = /^[A-Za-z0-9._-]+\.json$/
+
+const readRecord = (path: string): ResumeRecord | null => {
+  const text = readPrivateText(path)
+  return text === null ? null : parseResumeRecord(text)
+}
+
+/** A record counts only under the name its own `root` gives; a file under another name reads as damaged. */
+const entryOf = (directory: string, name: string): RecordEntry => {
+  const path = join(directory, name)
+  const record = readRecord(path)
+  return { path, record: record !== null && isRecordFileOf(name, record) ? record : null }
+}
+
+/**
+ * The records of `~/.jackherd/resume/`, read only from a directory nobody but the user can change
+ * (`isTrustedRecordDirectory`): board and lane names in there reach other sessions. Throws when the directory cannot be
+ * listed; `resumeAll` logs it.
+ */
+const readRecords = (home: string): RecordEntry[] => {
+  const directory = resumeRecordDirectory(home)
+  if (!isTrustedRecordDirectory(directory, systemLocation())) return []
+  return readdirSync(directory)
+    .filter((name) => RECORD_FILE.test(name))
+    .map((name) => entryOf(directory, name))
+}
+
+const writeRecord = (home: string, path: string, record: ResumeRecord) => {
+  ensurePrivateDirectory(resumeRecordDirectory(home))
+  writePrivateFile(path, `${JSON.stringify(record)}\n`)
+}
+
+/** The watcher's record of `root` below `home`, the file `jh resume` reads after a crash. */
+export const systemRecordStore = (root: string, home: string = homedir()): RecordStore => {
+  const path = resumeRecordPath(home, root)
+  return { read: () => readRecord(path), write: (record) => writeRecord(home, path, record) }
+}
+
+const isFile = (path: string): boolean => {
+  try {
+    return lstatSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+const appendLog = (home: string, line: string) => {
+  try {
+    ensurePrivateDirectory(resumeLogDirectory(home))
+    const path = resumeLogPath(home)
+    writePrivateFile(path, trimmedLog(readPrivateText(path), [line], RESUME_LOG_LINES))
+  } catch (error) {
+    console.error(`jh resume: cannot write the log: ${errorText(error)}`)
+  }
+  console.log(line)
+}
+
+/** The ports of `jh resume` on this machine: the user's records and log below `home`, the watcher lock, herdr. */
+export const systemResumePorts = (home: string = homedir()): ResumePorts => {
+  const herdr = herdrRunner(process.env)
+  const log = (root: string, message: string) => appendLog(home, logLine(Date.now(), root, message))
+  return {
+    now: Date.now,
+    records: () => readRecords(home),
+    reread: readRecord,
+    writeRecord: (path, record) => writeRecord(home, path, record),
+    watcherRunning: (root) => isWatcherRunning(join(watcherDirectoryOf(root), WATCHER_FILES.lock)),
+    boardExists: isFile,
+    settingsOf: (root) => {
+      const { responseLanguage, worktreeDirectory } = readSettings([root], home)
+      return { language: responseLanguage, worktreeDirectory }
+    },
+    agentPanes: () => resumablePanesOf(herdr(['agent', 'list']), herdr(['pane', 'list'])),
+    send: herdrSendPorts(),
+    sleep: (ms) => Bun.sleep(ms),
+    log,
+    notify: (title, body) => {
+      try {
+        herdr(['notification', 'show', title, '--body', body])
+      } catch (error) {
+        log('-', `herdr note failed: ${errorText(error)}`)
+      }
+    },
+  }
+}

package/src/resume/record.ts

@@ -0,0 +1,116 @@
+import { isAbsolute, join } from 'node:path'
+import { TOOL_DIRECTORY } from '../config/location'
+import { isRecord } from '../shared/is-record'
+import { parseJsonOrNull } from '../shared/parse-json'
+import { repositoryKey } from '../watch/watcher-lock'
+
+export const RESUME_RECORD_VERSION = 1
+
+/** Below `~/.jackherd/`: the user's own, outside every repository an agent writes to. */
+const RESUME_DIRECTORY = 'resume'
+
+/**
+ * What the watcher keeps about one repository so `jh resume` can tell a crash from a stop: a record without `stoppedAt`
+ * was left by a watcher that never ended cleanly. `lanes` holds each lane's last `agent_status`, `resumedAt` the one
+ * restart this record may cause.
+ */
+export type ResumeRecord = {
+  version: typeof RESUME_RECORD_VERSION
+  root: string
+  /** The board the watcher followed, absolute. */
+  board: string
+  /** The coordinator's herdr name. */
+  coordinator: string
+  pid: number
+  startedAt: number
+  savedAt: number
+  lanes: Record<string, string>
+  stoppedAt: number | null
+  resumedAt: number | null
+}
+
+/** What the watcher knows when it takes the lock. */
+export type RecordStart = Pick<ResumeRecord, 'root' | 'board' | 'coordinator' | 'pid'>
+
+const isTime = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
+
+const isTimeOrNull = (value: unknown): boolean => value === null || isTime(value)
+
+const isAbsolutePath = (value: unknown): boolean => typeof value === 'string' && isAbsolute(value)
+
+const isLaneStatuses = (value: unknown): boolean =>
+  isRecord(value) && Object.values(value).every((status) => typeof status === 'string')
+
+export const isResumeRecord = (value: unknown): value is ResumeRecord =>
+  isRecord(value) &&
+  value.version === RESUME_RECORD_VERSION &&
+  isAbsolutePath(value.root) &&
+  isAbsolutePath(value.board) &&
+  typeof value.coordinator === 'string' &&
+  Number.isInteger(value.pid) &&
+  (value.pid as number) > 0 &&
+  isTime(value.startedAt) &&
+  isTime(value.savedAt) &&
+  isLaneStatuses(value.lanes) &&
+  'stoppedAt' in value &&
+  isTimeOrNull(value.stoppedAt) &&
+  'resumedAt' in value &&
+  isTimeOrNull(value.resumedAt)
+
+/** The record in `text`; null for a damaged or foreign one, which the caller logs. */
+export const parseResumeRecord = (text: string): ResumeRecord | null => {
+  const value = parseJsonOrNull(text)
+  return isResumeRecord(value) ? value : null
+}
+
+/** `~/.jackherd/resume/<repositoryKey>.json`, the key the watcher directory of the same repository carries. */
+export const resumeRecordDirectory = (home: string): string => join(home, TOOL_DIRECTORY, RESUME_DIRECTORY)
+
+const recordFileName = (root: string): string => `${repositoryKey(root)}.json`
+
+export const resumeRecordPath = (home: string, root: string): string =>
+  join(resumeRecordDirectory(home), recordFileName(root))
+
+/** Whether the record lies under the name its `root` gives: a file under another name was not written by the watcher. */
+export const isRecordFileOf = (fileName: string, record: ResumeRecord): boolean =>
+  fileName === recordFileName(record.root)
+
+export const runningRecord = (start: RecordStart, now: number): ResumeRecord => ({
+  version: RESUME_RECORD_VERSION,
+  ...start,
+  startedAt: now,
+  savedAt: now,
+  lanes: {},
+  stoppedAt: null,
+  resumedAt: null,
+})
+
+const sameStatuses = (left: Record<string, string>, right: Record<string, string>): boolean => {
+  const names = Object.keys(left)
+  return names.length === Object.keys(right).length && names.every((name) => left[name] === right[name])
+}
+
+/** The record with the lanes' statuses; the same object when none changed, so the watcher writes only on a change. */
+export const withLanes = (record: ResumeRecord, lanes: Record<string, string>, now: number): ResumeRecord =>
+  sameStatuses(record.lanes, lanes) ? record : { ...record, lanes: { ...lanes }, savedAt: now }
+
+/**
+ * How often the watcher saves its record although no lane changed: once an hour, so a watcher that rests longer than
+ * `RESUME_MAX_AGE_MS` of `decision.ts` without a change still leaves a record young enough to resume after a crash.
+ */
+export const RESUME_REFRESH_MS = 60 * 60 * 1000
+
+/** The record with a new save time once `RESUME_REFRESH_MS` is up; the same object before, so nothing is written. */
+export const refreshedRecord = (record: ResumeRecord, now: number): ResumeRecord =>
+  now - record.savedAt < RESUME_REFRESH_MS ? record : { ...record, savedAt: now }
+
+/** The record after one herdr poll: new statuses, else a new save time once due; the same object when neither. */
+export const followedRecord = (record: ResumeRecord, lanes: Record<string, string>, now: number): ResumeRecord =>
+  refreshedRecord(withLanes(record, lanes, now), now)
+
+/** The record stamped as stopped cleanly; null when it names another process, whose record a successor keeps. */
+export const stoppedRecord = (record: ResumeRecord, ownPid: number, now: number): ResumeRecord | null =>
+  record.pid === ownPid ? { ...record, stoppedAt: now, savedAt: now } : null
+
+/** The record stamped as resumed, written before the first message goes out: one restart per record. */
+export const resumedRecord = (record: ResumeRecord, now: number): ResumeRecord => ({ ...record, resumedAt: now })