jackherd 1.15.2 → 1.17.0

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/plans/snapshot.ts

@@ -635,15 +635,20 @@ const decoratedViews = (
     ),
   )
 
-/** Each source with the tone and the label its config gives it. */
+/** Each source with the tone, the label and the `show` its config gives it. */
 const withSourceStyle = (
   statuses: readonly SourceStatus[],
   { herdSources, sourceLabels }: HerdSourceSettings,
 ): HerdSource[] =>
   statuses.map((status) => {
     const label = sourceLabels[status.name]
-    const tone = herdSources.find(({ name }) => name === status.name)?.tone ?? null
-    return { ...status, tone, ...(label === undefined ? {} : { label }) }
+    const config = herdSources.find(({ name }) => name === status.name)
+    return {
+      ...status,
+      tone: config?.tone ?? null,
+      ...(label === undefined ? {} : { label }),
+      ...(config?.show === undefined ? {} : { show: config.show }),
+    }
   })
 
 /**

package/src/plans/source-rows.ts

@@ -2,6 +2,7 @@ import { TONE, type ToneName } from '../config/tones'
 import { padVisible } from '../terminal/text'
 import { textWidth } from '../terminal/width'
 import type { EntryStatus, SourceStatus } from '../watch/source-statuses'
+import { SOURCE_SHOW, type SourceShow } from '../watch/sources'
 import { ASK_KIND } from './ask-target'
 import type { AskedCheck } from './source-asked'
 import { chevronOf } from './symbols'
@@ -9,9 +10,10 @@ import type { BlockItem } from './waiting-click'
 
 /**
  * A source's status with the tone its config names for the mark while its report is new (null where it names none) and
- * the label its config gives it, absent where it gives none.
+ * the label its config gives it, absent where it gives none, and `show` where it asks for its entries in a block of
+ * their own.
  */
-export type HerdSource = SourceStatus & { tone?: ToneName | null; label?: string }
+export type HerdSource = SourceStatus & { tone?: ToneName | null; label?: string; show?: SourceShow }
 
 /** One source in the line of the folded sources block: what it says and the tone it wears, none for dim. */
 export type SourceSummary = { text: string; tone?: ToneName }
@@ -179,6 +181,37 @@ const entryItems = (source: HerdSource, view: SourceView, now: number, newTone:
   ]
 }
 
+/** Whether the source asks for its entries in a block of their own. */
+export const showsEntries = (source: HerdSource): boolean => source.show === SOURCE_SHOW.entries
+
+/** The sources that have a block of their own: those that ask for it and have entries; an empty run draws none. */
+export const entryBlockSources = (sources: readonly HerdSource[]): HerdSource[] =>
+  sources.filter((source) => showsEntries(source) && source.entries.length > 0)
+
+/** The source as the `Sources` block draws it: a source with a block of its own keeps its status, not its entries. */
+export const statusOnly = (source: HerdSource): HerdSource =>
+  showsEntries(source) ? { ...source, entries: [], latest: null } : source
+
+/**
+ * The rows of the block of a source that shows its entries: count, time and title as in the opened source, in the
+ * order the state holds them, in the tone of the source, none of them asking or expanding; a row with an address
+ * is linked. Only the first `limit` entries become rows, the columns measured over those.
+ */
+export const entryBlockItems = (source: HerdSource, now: number, limit: number): BlockItem[] => {
+  const shown = source.entries.slice(0, limit)
+  const columns = columnsOf(shown, now)
+  return shown.map((entry) => ({
+    key: entryKey(source.name, entry),
+    mark: ENTRY_MARK,
+    lead: entryLeadOf(entry, now, columns),
+    text: entry.title,
+    url: entry.url,
+    ask: null,
+    expands: false,
+    ...(source.tone && { tone: source.tone }),
+  }))
+}
+
 const DEFAULT_VIEW: SourceView = { expanded: new Set(), asked: () => false }
 
 /**

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