jackherd 1.9.0 → 1.11.0

package/src/plans/board-close.ts

@@ -0,0 +1,85 @@
+import { twoDigits } from '../plan-format/clock'
+import { firstTableRows, sectionLines, sectionStart } from '../plan-format/markdown'
+import { APPOINTMENT_VOCABULARY, PLAN_LANGUAGE, type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
+
+type SectionColumns = {
+  heading: string
+  /** The header names of the two cells that identify a row, then the names that count as the status column. */
+  keys: readonly [string, string]
+  status: readonly string[]
+}
+
+const DONE_WORD: Record<PlanLanguage, string> = { [PLAN_LANGUAGE.de]: 'erledigt', [PLAN_LANGUAGE.en]: 'done' }
+
+/** The status a closed row gets, `erledigt (User <date> <time>)`: the time comes from `now`, never from an estimate. */
+export const doneStatus = (language: PlanLanguage, now: Date): string =>
+  `${DONE_WORD[language]} (User ${twoDigits(now.getDate())}.${twoDigits(now.getMonth() + 1)}. ${twoDigits(now.getHours())}:${twoDigits(now.getMinutes())})`
+
+const squeezed = (text: string): string => text.replace(/\s+/g, ' ').trim()
+
+const waitingColumns = (language: PlanLanguage): SectionColumns => {
+  const { heading, columns, statusAlso } = WAITING_VOCABULARY[language]
+  return { heading, keys: [columns.since, columns.item], status: [columns.status, ...statusAlso] }
+}
+
+const appointmentColumns = (language: PlanLanguage): SectionColumns => {
+  const { heading, columns, statusAlso } = APPOINTMENT_VOCABULARY[language]
+  return { heading, keys: [columns.when, columns.action], status: [columns.status, ...statusAlso] }
+}
+
+/** The line with the status cell (the `index`th between the bars) replaced; the other cells keep their text as written. */
+const withStatus = (line: string, index: number, status: string): string => {
+  const parts = line.split('|')
+  if (index + 1 >= parts.length) return line
+  parts[index + 1] = ` ${status} `
+  return parts.join('|')
+}
+
+/**
+ * The board with the status cell of the first row of the section's table whose two key cells equal `keys` replaced by
+ * `status`; null when the section, a column or the row is missing, so a row the board lost since the herd drew it
+ * writes nothing.
+ */
+const closeRow = (
+  board: string,
+  { heading, keys: keyNames, status: statusNames }: SectionColumns,
+  keys: readonly [string, string],
+  status: string,
+): string | null => {
+  const start = sectionStart(board, heading)
+  if (start === -1) return null
+  const lines = sectionLines(board, heading)
+  const header = lines.find((line) => line.startsWith('|'))
+  if (!header) return null
+  const names = header
+    .slice(1, header.endsWith('|') ? -1 : undefined)
+    .split('|')
+    .map((cell) => cell.trim())
+  const positions = keyNames.map((name) => names.indexOf(name))
+  const statusAt = names.findIndex((name) => statusNames.includes(name))
+  if (positions.includes(-1) || statusAt === -1) return null
+  const row = firstTableRows(lines).find(({ cells }) =>
+    positions.every((position, index) => squeezed(cells[position] ?? '') === squeezed(keys[index])),
+  )
+  if (!row) return null
+  const all = board.split('\n')
+  const at = start + row.index
+  all[at] = withStatus(all[at], statusAt, status)
+  return all.join('\n')
+}
+
+/** The board with the waiting row `since`/`item` closed at `now`; null when the board has no such row. */
+export const closeWaitingRow = (
+  board: string,
+  language: PlanLanguage,
+  { since, item }: { since: string; item: string },
+  now: Date,
+): string | null => closeRow(board, waitingColumns(language), [since, item], doneStatus(language, now))
+
+/** The board with the appointment `when`/`action` closed at `now`; null when the board has no such row. */
+export const closeAppointmentRow = (
+  board: string,
+  language: PlanLanguage,
+  { when, action }: { when: string; action: string },
+  now: Date,
+): string | null => closeRow(board, appointmentColumns(language), [when, action], doneStatus(language, now))

package/src/plans/child-stop.ts

@@ -0,0 +1,51 @@
+/** Milliseconds a child gets to end after a signal before it is killed. */
+export const GRACE_MS = 2000
+
+export type StopperDeps = {
+  kill: (signal: NodeJS.Signals) => void
+  setTimer: (run: () => void, ms: number) => unknown
+  clearTimer: (handle: unknown) => void
+}
+
+export const STOP_REQUEST = { forwarded: 'forwarded', killed: 'killed' } as const
+
+export type StopRequest = (typeof STOP_REQUEST)[keyof typeof STOP_REQUEST]
+
+export type Stopper = {
+  /** The first call forwards `signal` and arms the kill; any further call kills at once. */
+  request: (signal: NodeJS.Signals) => StopRequest
+  /** The child has ended: nothing is left to kill. */
+  ended: () => void
+}
+
+/**
+ * Stops one child: the signal goes to it, and a child that ignores it is killed once `GRACE_MS` have passed, so a
+ * supervisor never waits on a view that does not end.
+ */
+export const stopperOf = ({ kill, setTimer, clearTimer }: StopperDeps): Stopper => {
+  let timer: unknown
+  let requested = false
+
+  const send = (signal: NodeJS.Signals): void => {
+    try {
+      kill(signal)
+    } catch {
+      // the child is already gone
+    }
+  }
+
+  return {
+    request: (signal) => {
+      if (requested) {
+        clearTimer(timer)
+        send('SIGKILL')
+        return STOP_REQUEST.killed
+      }
+      requested = true
+      send(signal)
+      timer = setTimer(() => send('SIGKILL'), GRACE_MS)
+      return STOP_REQUEST.forwarded
+    },
+    ended: () => clearTimer(timer),
+  }
+}

package/src/plans/closable-records.ts

@@ -0,0 +1,34 @@
+import { join } from 'node:path'
+import { readRecords, writeRecordAtomically } from '../shared/private-records'
+
+/** A record that waits on the user until something sets `closedAt`. */
+export type ClosableRecord = { id: string; closedAt: number | null }
+
+export type ClosableRecordLog<T extends ClosableRecord> = {
+  /** Every record of the log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
+  read: (root: string) => T[]
+  /** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+  close: (root: string, ids: readonly string[], now: number) => number
+  /** Marks every open record `closedAt` and returns how many it closed. */
+  closeAll: (root: string, now: number) => number
+}
+
+/** The log of `.jackherd/<directoryName>/`: records the `guard` accepts, ordered by `timeOf`. */
+export const closableRecordLog = <T extends ClosableRecord>(
+  directoryName: string,
+  guard: (value: unknown) => value is T,
+  timeOf: (record: T) => number,
+): ClosableRecordLog<T> => {
+  const directoryOf = (root: string): string => join(root, '.jackherd', directoryName)
+  const read = (root: string): T[] => readRecords(directoryOf(root), guard, timeOf)
+  const closeWhere = (root: string, isChosen: (record: T) => boolean, now: number): number => {
+    const open = read(root).filter((record) => record.closedAt === null && isChosen(record))
+    for (const record of open) writeRecordAtomically(directoryOf(root), { ...record, closedAt: now })
+    return open.length
+  }
+  return {
+    read,
+    close: (root, ids, now) => closeWhere(root, (record) => ids.includes(record.id), now),
+    closeAll: (root, now) => closeWhere(root, () => true, now),
+  }
+}

package/src/plans/command.ts

@@ -6,6 +6,7 @@ import { boardFor, foundLanesOf } from './board-pick'
 import { ensurePlanPanes } from './ensure-panes'
 import { mainCheckout, worktreeRoot } from './git'
 import { fetchPullRequests } from './github'
+import { claimOwnTerminal, startExclusive } from './herd-claim'
 import { recallLanes, rememberLanes } from './herd-memory'
 import { runLive } from './live'
 import { parseOptions } from './options'
@@ -59,8 +60,8 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
     }
     const source = { root, sprintFile: picked.file, options, settings, terminal }
     if (options.once || !process.stdout.isTTY) await printOnceWithNotice(source, picked.notice)
-    else if (isSupervisedChild(process.env)) runLive(source)
-    else return await superviseView(args, await startedKit())
+    else if (isSupervisedChild(process.env)) await startExclusive(claimOwnTerminal, () => runLive(source))
+    else process.exit(await superviseView(args, await startedKit()))
     return 0
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))

package/src/plans/fetch.ts

@@ -1,5 +1,7 @@
 import { errorText } from './error-text'
 import type { PullRequestState } from './github'
+import { pullHeadRefspec } from './plan-heads'
+import type { PullRequest } from './pull-requests'
 
 /** The background fetch of the base branch: when it last ran, when it last worked and why it failed. */
 export type FetchState = {
@@ -70,12 +72,13 @@ export const fetchNotice = (state: FetchState, baseRef: string, locale: string):
   return `fetch failed (${state.failure}), reading ${baseRef} as it is: ${known}`
 }
 
-/** Fetches the base branch; returns the reason when it did not work, null when it did. Never rejects. */
-export const fetchBase = async (root: string, remote: string, branch: string): Promise<string | null> => {
+/** Fetches `refspecs` from `remote` in one call; returns the reason when it did not work, null when it did or there was nothing to fetch. Never rejects. */
+export const fetchRefs = async (root: string, remote: string, refspecs: readonly string[]): Promise<string | null> => {
+  if (refspecs.length === 0) return null
   let timedOut = false
   let timer: Timer | undefined
   try {
-    const child = Bun.spawn(['git', '-C', root, 'fetch', '--quiet', remote, branch], {
+    const child = Bun.spawn(['git', '-C', root, 'fetch', '--quiet', remote, ...refspecs], {
       stdout: 'ignore',
       stderr: 'pipe',
       env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
@@ -94,3 +97,23 @@ export const fetchBase = async (root: string, remote: string, branch: string): P
     clearTimeout(timer)
   }
 }
+
+/** Fetches the base branch; returns the reason when it did not work, null when it did. Never rejects. */
+export const fetchBase = (root: string, remote: string, branch: string): Promise<string | null> =>
+  fetchRefs(root, remote, [branch])
+
+/**
+ * Fetches the heads of the given pull requests into the herd's own refs (`pullHeadRef`), in one call after the base.
+ * A failure is not reported: a head that was not fetched reads nothing, and the plan stays as the base has it.
+ */
+export const fetchPlanHeads = async (
+  root: string,
+  remote: string,
+  pullRequests: readonly Pick<PullRequest, 'number'>[],
+): Promise<void> => {
+  await fetchRefs(
+    root,
+    remote,
+    pullRequests.map(({ number }) => pullHeadRefspec(number)),
+  )
+}

package/src/plans/frame.ts

@@ -1,4 +1,5 @@
-import { BAR_SEGMENT, INVERSE_ON, paint, RESET, stripAnsi, visibleLength } from '../terminal/text'
+import { paint, visibleLength } from '../terminal/text'
+import { focusLine, isFocused } from './row-focus'
 import type { ClickTarget, Selection } from './selection'
 
 /**
@@ -73,17 +74,9 @@ const branches = (children: Frame[]): Frame[] => {
 export const nest = (children: Frame[]): Frame => joinFrames(branches(children))
 
 /**
- * A row drawn inverse across the pane. A progress bar inside it is switched back to normal video: inverted,
- * its filled and empty blocks would trade places with the background and the bar would be unreadable.
+ * A selectable row: drawn with the focus background and mark (`focusLine`) when selected or under the mouse, clickable
+ * across the pane on every line, `below` follows unselectable. Only the selected row holds the cursor.
  */
-const highlight = (line: string, width: number): string => {
-  const bars = line.match(BAR_SEGMENT) ?? []
-  const texts = line.split(BAR_SEGMENT).map(stripAnsi)
-  const body = texts.map((text, index) => `${text}${bars[index] ? `${bars[index]}${INVERSE_ON}` : ''}`).join('')
-  return `${INVERSE_ON}${body}${' '.repeat(Math.max(width - visibleLength(line), 0))}${RESET}`
-}
-
-/** A selectable row: drawn inverse when selected, clickable across the pane on every line, `below` follows unselectable. */
 export const rowFrame = (
   key: string,
   rows: string[],
@@ -92,7 +85,7 @@ export const rowFrame = (
 ): Frame => {
   const selected = state.selected === key
   return {
-    lines: [...(selected ? rows.map((row) => highlight(row, width)) : rows), ...below],
+    lines: [...(isFocused(state, key) ? rows.map((row, index) => focusLine(row, width, index === 0)) : rows), ...below],
     cursorLine: selected ? 0 : -1,
     targets: rows.map((_, line) => ({ line, from: 0, to: width, key, wholeLine: true as const })),
   }

package/src/plans/git.ts

@@ -32,21 +32,70 @@ export const showAtRef = (root: string, ref: string, path: string): string | nul
 export const commitOf = (root: string, ref: string): string | null =>
   git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
 
+const lastChangeAt = (root: string, commit: string, path: string): number | null => {
+  const seconds = Number(git(root, ['log', '-1', '--format=%ct', commit, '--', path]))
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : null
+}
+
+/** The last-change times read per `root\0commit`, by path, the commit asked last at the end; a change at a commit never moves. */
+const cachedChanges = new Map<string, Map<string, number | null>>()
+
+const changesOf = (root: string, commit: string): Map<string, number | null> => {
+  const key = `${root}\0${commit}`
+  const changes = cachedChanges.get(key) ?? new Map<string, number | null>()
+  cachedChanges.delete(key)
+  cachedChanges.set(key, changes)
+  const oldest = cachedChanges.keys().next().value
+  if (cachedChanges.size > CACHED_COMMITS && oldest !== undefined) cachedChanges.delete(oldest)
+  return changes
+}
+
+/**
+ * A reader of the commit time, in epoch milliseconds, of the last commit at `ref` that changed a path; null when the
+ * ref or the file is unknown there. The commit is resolved once per reader and each answer is kept per commit, so a
+ * refresh while the ref stands costs one `git rev-parse`, and a moved ref reads afresh.
+ */
+export const lastChangeReaderOf = (root: string, ref: string): ((path: string) => number | null) => {
+  const commit = commitOf(root, ref)
+  if (commit === null) return () => null
+  const changes = changesOf(root, commit)
+  return (path) => {
+    if (changes.has(path)) return changes.get(path) ?? null
+    const at = lastChangeAt(root, commit, path)
+    changes.set(path, at)
+    return at
+  }
+}
+
 /** Reads files as they are at the base ref. */
 export type BaseReader = (path: string) => string | null
 
-let cached: { root: string; commit: string; texts: Map<string, string> } | null = null
+/** How many commits keep their texts: the base ref and the heads of the open pull requests that change a plan. */
+const CACHED_COMMITS = 16
+
+/** The texts read per `root\0commit`, the one asked last at the end. */
+const cachedTexts = new Map<string, Map<string, string>>()
+
+const textsOf = (root: string, commit: string): Map<string, string> => {
+  const key = `${root}\0${commit}`
+  const texts = cachedTexts.get(key) ?? new Map<string, string>()
+  cachedTexts.delete(key)
+  cachedTexts.set(key, texts)
+  const oldest = cachedTexts.keys().next().value
+  if (cachedTexts.size > CACHED_COMMITS && oldest !== undefined) cachedTexts.delete(oldest)
+  return texts
+}
 
 /**
  * A reader for the files at `ref`, with the commit resolved once. A file at a commit never changes, so what was
- * read is kept for as long as the ref points at the same commit: a re-read of the sprint costs one `git
- * rev-parse` instead of one `git show` per plan.
+ * read is kept for as long as the commit is among the last `CACHED_COMMITS` asked: a re-read of the sprint costs
+ * one `git rev-parse` per ref instead of one `git show` per plan, and the base and the pull request heads read in
+ * the same round do not evict each other.
  */
 export const baseReaderOf = (root: string, ref: string): BaseReader => {
   const commit = commitOf(root, ref)
   if (commit === null) return () => null
-  if (cached?.root !== root || cached.commit !== commit) cached = { root, commit, texts: new Map() }
-  const { texts } = cached
+  const texts = textsOf(root, commit)
   return (path) => {
     const kept = texts.get(path)
     if (kept !== undefined) return kept

package/src/plans/groomed.ts

@@ -0,0 +1,27 @@
+import { DAY_MS } from '../plan-format/clock'
+import { APPOINTMENT_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { readAppointmentTable } from '../watch/appointments'
+
+const GROOMING_INTERVAL_DAYS = 7
+const STALE_FROM_DAYS = 8
+
+/**
+ * Whole days since the board was last groomed, or null when the board has no open grooming appointment. The
+ * coordinator moves that appointment a week on after each grooming, so the last one was a week before it. A time
+ * before that (a board never groomed on the clock) counts as 0.
+ */
+export const groomedDaysAgo = (board: string, language: PlanLanguage, now: Date): number | null => {
+  const word = APPOINTMENT_VOCABULARY[language].grooming
+  const next = readAppointmentTable(board, language, now)
+    .appointments.filter(({ open, action }) => open && action.toLowerCase().startsWith(word))
+    .sort((left, right) => left.when.getTime() - right.when.getTime())[0]
+  if (!next) return null
+  const groomedAt = next.when.getTime() - GROOMING_INTERVAL_DAYS * DAY_MS
+  return Math.max(Math.floor((now.getTime() - groomedAt) / DAY_MS), 0)
+}
+
+/** The header text; `stale` from eight days on, when the herd paints it amber. */
+export const groomedText = (days: number): { text: string; stale: boolean } => ({
+  text: days === 0 ? 'groomed today' : `groomed ${days}d ago`,
+  stale: days >= STALE_FROM_DAYS,
+})

package/src/plans/herd-claim.ts

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, readlinkSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import {
+  type LocationSystem,
+  readPrivateText,
+  runtimeBaseOf,
+  systemLocation,
+  userDirectoryOf,
+} from '../shared/private-location'
+import { HERD_COMMAND } from './herd-command'
+import { CHILD_MARKER, TAKEN_OVER_CODE, TAKEOVER_SIGNAL } from './restart-decision'
+
+const DIRECTORY_PREFIX = 'jackherd-herd'
+const POLL_MS = 50
+const POLLS_BEFORE_KILL = 20
+
+export type ClaimDeps = {
+  selfPid: number
+  prepare: () => void
+  readRecord: () => string | null
+  writeRecord: (pid: number) => void
+  removeRecordIf: (pid: number) => void
+  isHerdView: (pid: number) => boolean
+  isGone: (pid: number) => boolean
+  signal: (pid: number, signal: NodeJS.Signals) => void
+  sleep: (ms: number) => Promise<void>
+  onExit: (run: () => void) => void
+}
+
+/** A process id as the record file holds it; nothing for anything but a positive integer. */
+export const parsePid = (text: string | null): number | null => {
+  if (text === null || !/^\d+\s*$/.test(text)) return null
+  const pid = Number(text)
+  return pid > 0 ? pid : null
+}
+
+/**
+ * The older herd view of this terminal that has to end before `selfPid` draws: the recorded pid when it is not
+ * this process and still is a herd view (a number the system has reused for something else is not).
+ */
+export const olderHerdToStop = (
+  recorded: number | null,
+  selfPid: number,
+  isHerdView: (pid: number) => boolean,
+): number | null => (recorded === null || recorded === selfPid || !isHerdView(recorded) ? null : recorded)
+
+const endOlderHerd = async (pid: number, deps: ClaimDeps): Promise<void> => {
+  deps.signal(pid, TAKEOVER_SIGNAL)
+  for (let poll = 0; poll < POLLS_BEFORE_KILL; poll++) {
+    if (deps.isGone(pid)) return
+    await deps.sleep(POLL_MS)
+  }
+  if (!deps.isGone(pid) && deps.isHerdView(pid)) deps.signal(pid, 'SIGKILL')
+}
+
+/**
+ * Makes this process the one herd view of its terminal: an older one is sent `TAKEOVER_SIGNAL` and, when it has not ended
+ * after about a second and its pid still is a herd view, SIGKILL; then the own pid is recorded and removed again when the process ends. The claim
+ * directory is verified first: a record in a directory of someone else is never read, and a directory that cannot be
+ * verified throws before anything is read, signalled or written.
+ */
+export const claimTerminal = async (deps: ClaimDeps): Promise<void> => {
+  deps.prepare()
+  const older = olderHerdToStop(parsePid(deps.readRecord()), deps.selfPid, deps.isHerdView)
+  if (older !== null) await endOlderHerd(older, deps)
+  deps.writeRecord(deps.selfPid)
+  deps.onExit(() => deps.removeRecordIf(deps.selfPid))
+}
+
+/** The directory holding the claim records: one private level `jackherd-herd-<uid>` below `runtimeBaseOf`. */
+export const claimDirectoryOf = (system: LocationSystem): string =>
+  userDirectoryOf(runtimeBaseOf(system), DIRECTORY_PREFIX, system.uid)
+
+const exitWhenTakenOver = (): void => {
+  process.on(TAKEOVER_SIGNAL, () => process.exit(TAKEN_OVER_CODE))
+}
+
+/**
+ * Runs `start` once the takeover is done; a takeover that cannot be made (no terminal, no `/proc`) does not stop the
+ * view. `listen` runs first, so a newer herd's takeover signal that arrives while the claim is made ends this process
+ * as a wanted end instead of by the signal's default action; the view replaces that handler with its own.
+ */
+export const startExclusive = async (
+  claim: () => Promise<void>,
+  start: () => void,
+  listen: () => void = exitWhenTakenOver,
+): Promise<void> => {
+  listen()
+  try {
+    await claim()
+  } catch {
+    // the view still starts: one stale herd is better than none
+  }
+  start()
+}
+
+const terminalOfStdin = (): string | null => {
+  try {
+    const target = readlinkSync('/proc/self/fd/0')
+    return target.startsWith('/dev/') ? target : null
+  } catch {
+    return null
+  }
+}
+
+const readText = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const isHerdViewProcess = (pid: number): boolean => {
+  const environment = readText(`/proc/${pid}/environ`)
+  const command = readText(`/proc/${pid}/cmdline`)
+  if (environment === null || command === null) return false
+  return environment.split('\0').includes(`${CHILD_MARKER}=1`) && command.split('\0').includes(HERD_COMMAND.name)
+}
+
+const isGoneProcess = (pid: number): boolean => {
+  const stat = readText(`/proc/${pid}/stat`)
+  if (stat === null) return true
+  const stateIndex = stat.lastIndexOf(')') + 2
+  return stat.charAt(stateIndex) === 'Z'
+}
+
+const signalProcess = (pid: number, signal: NodeJS.Signals): void => {
+  try {
+    process.kill(pid, signal)
+  } catch {
+    // already gone
+  }
+}
+
+const recordFileOf = (terminal: string): string =>
+  join(claimDirectoryOf(systemLocation()), `${createHash('sha256').update(terminal).digest('hex').slice(0, 16)}.pid`)
+
+/**
+ * The claim operations for one record file; the claim directory is verified before the record is read or written, and
+ * a record that is a link or a FIFO is not read.
+ */
+export const herdClaimDeps = (file: string): ClaimDeps => ({
+  selfPid: process.pid,
+  prepare: () => ensurePrivateDirectory(join(file, '..')),
+  readRecord: () => readPrivateText(file),
+  writeRecord: (pid) => {
+    ensurePrivateDirectory(join(file, '..'))
+    writePrivateFile(file, `${pid}\n`)
+  },
+  removeRecordIf: (pid) => {
+    try {
+      if (parsePid(readPrivateText(file)) === pid) unlinkSync(file)
+    } catch {
+      // the next herd of this terminal overwrites it
+    }
+  },
+  isHerdView: isHerdViewProcess,
+  isGone: isGoneProcess,
+  signal: signalProcess,
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  onExit: (run) => {
+    process.on('exit', run)
+  },
+})
+
+/** Takes the terminal of stdin over from an older herd view; without a terminal (or `/proc`) it does nothing. */
+export const claimOwnTerminal = async (): Promise<void> => {
+  const terminal = terminalOfStdin()
+  if (terminal !== null) await claimTerminal(herdClaimDeps(recordFileOf(terminal)))
+}

package/src/plans/herd-memory.ts

@@ -1,14 +1,19 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { z } from 'zod'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import {
+  ensurePrivateLevels,
+  type LocationSystem,
+  readPrivateText,
+  runtimeBaseOf,
+  systemLocation,
+  userDirectoryOf,
+} from '../shared/private-location'
 import { repositoryKey } from '../watch/watcher-lock'
 import type { LaneMemory } from './current-phase'
 
 const DIRECTORY_PREFIX = 'jackherd-herd'
 const MEMORY_FILE = 'herd-memory.json'
-const PRIVATE_DIRECTORY = 0o700
-const PRIVATE_FILE = 0o600
 
 const phaseRef = z.object({ planHref: z.string(), phaseId: z.string() })
 
@@ -54,41 +59,46 @@ export const mergedMemories = (
  * Where the herds of the repository at `root` keep what they saw of each lane, one directory per user and
  * repository like the watcher's, so a `--once` run and a restarted herd know when a phase last moved.
  */
-const herdMemoryDirectory = (root: string): string =>
-  join(tmpdir(), `${DIRECTORY_PREFIX}-${process.getuid?.() ?? 'user'}`, repositoryKey(root))
+export const herdMemoryDirectoryOf = (root: string, system: LocationSystem): string =>
+  join(userDirectoryOf(runtimeBaseOf(system), DIRECTORY_PREFIX, system.uid), repositoryKey(root))
 
-export const memoryFileOf = (directory: string): string => join(directory, MEMORY_FILE)
-
-const readText = (file: string): string | null => {
-  try {
-    return readFileSync(file, 'utf8')
-  } catch {
-    return null
-  }
+/** The memory directory of `root` with both levels verified private (`ensurePrivateLevels`); throws when one is not. */
+const ensureHerdMemoryDirectory = (root: string, system: LocationSystem): string => {
+  const directory = herdMemoryDirectoryOf(root, system)
+  return ensurePrivateLevels(dirname(directory), directory)
 }
 
+export const memoryFileOf = (directory: string): string => join(directory, MEMORY_FILE)
+
 export const readLaneMemories = (directory: string): Map<string, LaneMemory> =>
-  parseLaneMemories(readText(memoryFileOf(directory)))
+  parseLaneMemories(readPrivateText(memoryFileOf(directory)))
 
 /**
  * Writes the memories of `lanes` into the file of `directory`, beside what other herds keep there; readable by the
- * user only, and replaced in one step so a herd reading at the same time never sees half a file.
+ * user only (the directory is verified with `ensurePrivateDirectory`), and replaced in one step through
+ * `writePrivateFile`, so a herd reading at the same time never sees half a file and a planted link is never followed.
  */
 export const writeLaneMemories = (
   directory: string,
   memories: ReadonlyMap<string, LaneMemory>,
   lanes: readonly string[],
 ): void => {
-  mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
-  const file = memoryFileOf(directory)
+  ensurePrivateDirectory(directory)
   const merged = mergedMemories(readLaneMemories(directory), memories, lanes)
-  const partial = `${file}.${process.pid}`
-  writeFileSync(partial, JSON.stringify(merged), { mode: PRIVATE_FILE })
-  renameSync(partial, file)
+  writePrivateFile(memoryFileOf(directory), JSON.stringify(merged))
 }
 
-/** The memories the herds of the repository at `root` kept. */
-export const recallLanes = (root: string): Map<string, LaneMemory> => readLaneMemories(herdMemoryDirectory(root))
+/**
+ * The memories the herds of the repository at `root` kept; none when the directory cannot be verified private, so a
+ * file planted in a directory of someone else is never read.
+ */
+export const recallLanes = (root: string, system: LocationSystem = systemLocation()): Map<string, LaneMemory> => {
+  try {
+    return readLaneMemories(ensureHerdMemoryDirectory(root, system))
+  } catch {
+    return new Map()
+  }
+}
 
 /**
  * Keeps the memories of `lanes` for the next herd. A memory that cannot be written costs only the times of the next
@@ -98,9 +108,10 @@ export const rememberLanes = (
   root: string,
   memories: ReadonlyMap<string, LaneMemory>,
   lanes: readonly string[],
+  system: LocationSystem = systemLocation(),
 ): void => {
   try {
-    writeLaneMemories(herdMemoryDirectory(root), memories, lanes)
+    writeLaneMemories(ensureHerdMemoryDirectory(root, system), memories, lanes)
   } catch {
     return
   }