jackherd 1.23.3 → 1.25.0

package/src/backend/control.ts

@@ -0,0 +1,194 @@
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { backendCommandOf } from './command'
+import { lanesGone, released, returned } from './handover'
+import type { BackendSight } from './herdr'
+import type { BackendConfig } from './schema'
+import { BACKEND_PANE, type BackendState, restarted } from './state'
+import {
+  BACKEND_START_WINDOW_MS,
+  BACKEND_STEP_ACTION,
+  type BackendObservation,
+  type BackendStep,
+  backendStep,
+  noticed,
+  startedByHand,
+} from './step'
+
+type Awaitable<T> = T | Promise<T>
+
+/** The calls the backend makes; `backendSystemOf` wires them to herdr, the state file, the port probe and the clock. */
+export type BackendSystem = {
+  readState: () => BackendState
+  writeState: (state: BackendState) => void
+  /** The backend pane as it is now, or why it is left alone. */
+  look: () => Awaitable<BackendSight>
+  busyPorts: (ports: readonly number[]) => Awaitable<number[]>
+  /** Opens the backend's tab in the main checkout, labels its pane and runs `command` there; answers the pane. */
+  create: (command: string) => Awaitable<string>
+  run: (pane: string, command: string) => Awaitable<void>
+  /** Stops the process in `pane` with SIGTERM and waits until the pane is a shell again and `ports` are free. */
+  stop: (pane: string, ports: readonly number[]) => Awaitable<{ ok: true } | { ok: false; line: string }>
+  /** The lanes' worktree names. */
+  worktrees: () => string[]
+  now: () => number
+}
+
+/** What a `jh backend` call did: its lines and whether it got done. */
+export type BackendOutcome = { ok: boolean; lines: string[] }
+
+type Looked = { kind: 'refused'; line: string } | { kind: 'seen'; observation: BackendObservation; pane: string | null }
+
+const releasedNames = (state: BackendState): string[] => state.released.map(({ service }) => service)
+
+/** The ports of the services the backend runs while `state` holds. */
+export const runningPortsOf = (backend: BackendConfig, state: BackendState): number[] =>
+  backend.services.filter(({ name }) => !releasedNames(state).includes(name)).map(({ port }) => port)
+
+const desiredOf = (backend: BackendConfig, state: BackendState): string | null =>
+  backendCommandOf(backend, releasedNames(state))
+
+/** The pane and, unless it runs, which of the ports `state` asks for are busy. */
+const lookAt = async (backend: BackendConfig, state: BackendState, system: BackendSystem): Promise<Looked> => {
+  const sight = await system.look()
+  if (sight.kind === 'refused') return sight
+  const busyPorts = sight.pane === BACKEND_PANE.running ? [] : await system.busyPorts(runningPortsOf(backend, state))
+  const observation = { pane: sight.pane, place: sight.place, busyPorts, desired: desiredOf(backend, state) }
+  return { kind: 'seen', observation, pane: sight.paneId }
+}
+
+/** Carries out a step's action: a new tab for `split`, a run in the pane for `start`. */
+const carryOut = async (step: BackendStep, pane: string | null, system: BackendSystem): Promise<void> => {
+  const command = step.state.command
+  if (step.action === BACKEND_STEP_ACTION.none || command === null) return
+  if (step.action === BACKEND_STEP_ACTION.split) await system.create(command)
+  else if (pane !== null) await system.run(pane, command)
+}
+
+const lineList = (line: string | null): string[] => (line === null ? [] : [line])
+
+/** A refusal said once while it stands, as the step does for its own standing conditions. */
+const refusedOnce = (state: BackendState, line: string, system: BackendSystem): string[] => {
+  const step = noticed(state, line)
+  system.writeState(step.state)
+  return lineList(step.line)
+}
+
+/** A start by hand got done: the pane was started, or every service is handed to a lane and nothing is to run. */
+const isHandStartDone = (step: BackendStep): boolean =>
+  step.action !== BACKEND_STEP_ACTION.none || step.state.command === null
+
+/**
+ * Stops the pane that ran with `before` and starts it with `after`, as `jh backend` asks. A pane that does not run is
+ * only started; a stop that fails leaves the start to the next check once the pane is a shell again.
+ */
+const restartWith = async (
+  backend: BackendConfig,
+  system: BackendSystem,
+  before: BackendState,
+  after: BackendState,
+): Promise<BackendOutcome> => {
+  system.writeState(after)
+  const first = await lookAt(backend, after, system)
+  if (first.kind === 'refused') return { ok: false, lines: [first.line] }
+  if (first.observation.pane === BACKEND_PANE.running && first.pane !== null) {
+    const stopped = await system.stop(first.pane, runningPortsOf(backend, before))
+    if (!stopped.ok) return { ok: false, lines: [stopped.line] }
+  }
+  const looked = await lookAt(backend, after, system)
+  if (looked.kind === 'refused') return { ok: false, lines: [looked.line] }
+  const step = startedByHand(after, looked.observation)
+  await carryOut(step, looked.pane, system)
+  system.writeState(step.state)
+  return { ok: isHandStartDone(step), lines: lineList(step.line) }
+}
+
+/** Gives back the services whose lane has no worktree any more and restarts the pane with them; null when none is gone. */
+const returnGone = async (backend: BackendConfig, system: BackendSystem, state: BackendState) => {
+  const gone = lanesGone(state, system.worktrees())
+  if (gone.length === 0) return null
+  const after = { ...state, released: state.released.filter(({ service }) => !gone.includes(service)) }
+  const lines = state.released
+    .filter(({ service }) => gone.includes(service))
+    .map(({ service, lane }) => `backend: ${service} returned from ${lane} (worktree gone)`)
+  return [...lines, ...(await restartWith(backend, system, state, after)).lines]
+}
+
+/**
+ * The watcher's check: services of lanes that are gone come back first; otherwise `backendStep` decides on the pane
+ * as it is, and its action is carried out. Answers the lines to print; a standing condition is printed once.
+ */
+export const checkBackend = async (backend: BackendConfig, system: BackendSystem): Promise<string[]> => {
+  const state = system.readState()
+  const back = await returnGone(backend, system, state)
+  if (back !== null) return back
+  const looked = await lookAt(backend, state, system)
+  if (looked.kind === 'refused') return refusedOnce(state, looked.line, system)
+  const step = backendStep(state, looked.observation, system.now())
+  await carryOut(step, looked.pane, system)
+  system.writeState(step.state)
+  return lineList(step.line)
+}
+
+/** `jh backend restart`: forgets the start history and "gave up", stops the pane and starts it again. */
+export const restartBackend = (backend: BackendConfig, system: BackendSystem): Promise<BackendOutcome> => {
+  const state = system.readState()
+  return restartWith(backend, system, state, restarted(state))
+}
+
+const portOf = (backend: BackendConfig, service: string): number | null =>
+  backend.services.find(({ name }) => name === service)?.port ?? null
+
+/**
+ * `jh backend release <service> --lane <lane>`: takes the service out of the backend's command, restarts the pane
+ * and names the call that starts the service in the lane.
+ */
+export const releaseService = async (
+  backend: BackendConfig,
+  system: BackendSystem,
+  service: string,
+  lane: string,
+): Promise<BackendOutcome> => {
+  const before = system.readState()
+  const handed = released(
+    before,
+    backend.services.map(({ name }) => name),
+    service,
+    lane,
+  )
+  if (!handed.ok) return { ok: false, lines: [handed.line] }
+  const restart = await restartWith(backend, system, before, handed.state)
+  const port = portOf(backend, service)
+  const next = restart.ok
+    ? `backend: ${service} handed to ${lane}, port ${port} is free; jh lane dev ${lane} --filter ${service} --port ${port}`
+    : `backend: ${service} handed to ${lane}; port ${port} is free once the backend pane has stopped`
+  return { ok: restart.ok, lines: [...restart.lines, next] }
+}
+
+/** `jh backend return <service>`: puts the service back into the backend's command and restarts the pane. */
+export const returnService = async (
+  backend: BackendConfig,
+  system: BackendSystem,
+  service: string,
+): Promise<BackendOutcome> => {
+  const before = system.readState()
+  const back = returned(before, service)
+  if (!back.ok) return { ok: false, lines: [back.line] }
+  const restart = await restartWith(backend, system, before, back.state)
+  return { ok: restart.ok, lines: [...restart.lines, `backend: ${service} returned`] }
+}
+
+const sightLine = (sight: BackendSight): string =>
+  sight.kind === 'refused' ? sight.line : `backend: pane ${sight.paneId ?? '(none)'}, ${sight.pane}`
+
+/** `jh backend`: the pane, the command last started, the services handed to lanes, the recent starts, "gave up". */
+export const statusLines = (sight: BackendSight, state: BackendState, now: number): string[] => {
+  const handed = state.released.map(({ service, lane }) => `${service} → ${lane}`).join(', ')
+  const recent = state.starts.filter((start) => now - start < BACKEND_START_WINDOW_MS).length
+  return [
+    sightLine(sight),
+    `backend: command ${state.command ?? '(none started)'}`,
+    `backend: handed to lanes ${handed === '' ? '(none)' : handed}`,
+    `backend: ${recent} automatic starts in the last ${BACKEND_START_WINDOW_MS / MS_PER_MINUTE} minutes`,
+    ...(state.gaveUp ? ['backend: gave up; jh backend restart'] : []),
+  ]
+}

package/src/backend/handover.ts

@@ -0,0 +1,28 @@
+import type { BackendState } from './state'
+
+/** The new state, or the line that says why the request is refused. */
+export type HandoverResult = { ok: true; state: BackendState } | { ok: false; line: string }
+
+/** Hands `service` to `lane`; refuses a service the backend does not run and one already handed over. */
+export const released = (
+  state: BackendState,
+  known: readonly string[],
+  service: string,
+  lane: string,
+): HandoverResult => {
+  if (!known.includes(service)) return { ok: false, line: `backend: ${service} is no service of lanes.backend` }
+  const holder = state.released.find((entry) => entry.service === service)
+  if (holder) return { ok: false, line: `backend: ${service} is already handed to ${holder.lane}` }
+  return { ok: true, state: { ...state, released: [...state.released, { service, lane }] } }
+}
+
+/** Takes `service` back; refuses one that is not handed over. */
+export const returned = (state: BackendState, service: string): HandoverResult => {
+  if (!state.released.some((entry) => entry.service === service))
+    return { ok: false, line: `backend: ${service} is not handed to a lane` }
+  return { ok: true, state: { ...state, released: state.released.filter((entry) => entry.service !== service) } }
+}
+
+/** The handed-over services whose lane has no worktree any more. */
+export const lanesGone = (state: BackendState, worktrees: readonly string[]): string[] =>
+  state.released.filter(({ lane }) => !worktrees.includes(lane)).map(({ service }) => service)

package/src/backend/herdr.ts

@@ -0,0 +1,147 @@
+import { isIdleShell, isStartingShell, type PaneState } from '../plans/plan-panes'
+import { isRecord } from '../shared/is-record'
+import { BACKEND_PANE, type BackendPane } from './state'
+
+/** One process of a pane's foreground as `herdr pane process-info` names it. */
+export type ForegroundProcess = { pid: number; argv: string[] }
+
+/** The process facts of one pane: its shell, the foreground process group and the processes in it. */
+export type PaneProcesses = { shellPid: number | null; groupId: number | null; processes: ForegroundProcess[] }
+
+/** A pane as the backend check reads it from `herdr pane list`. */
+export type PaneListing = Omit<PaneState, 'foreground'>
+
+/** What the check found: the pane (or none yet) and where it sits, or why it leaves everything alone. */
+export type BackendSight =
+  | { kind: 'found'; pane: BackendPane; paneId: string | null; place: string }
+  | { kind: 'refused'; line: string }
+
+export type StopTarget = { ok: true; pid: number } | { ok: false; line: string }
+
+const positiveInteger = (value: unknown): number | null =>
+  typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : null
+
+const isArgv = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((arg) => typeof arg === 'string')
+
+const foregroundProcessOf = (value: unknown): ForegroundProcess[] => {
+  if (!isRecord(value)) return []
+  const pid = positiveInteger(value.pid)
+  return pid !== null && isArgv(value.argv) ? [{ pid, argv: value.argv }] : []
+}
+
+const unexpected = (command: string): Error => new Error(`herdr ${command}: unexpected answer`)
+
+/** The `result.<field>` of a herdr answer; throws when the answer has no `result`. */
+const resultFieldOf = (json: string, field: string, command: string): unknown => {
+  const answer: unknown = JSON.parse(json)
+  const result = isRecord(answer) ? answer.result : undefined
+  if (!isRecord(result)) throw unexpected(command)
+  return result[field]
+}
+
+/** The shell, process group and foreground processes of a `herdr pane process-info` answer; throws on a changed answer. */
+export const paneProcessesOf = (json: string): PaneProcesses => {
+  const info = resultFieldOf(json, 'process_info', 'pane process-info')
+  if (!isRecord(info)) throw unexpected('pane process-info')
+  const processes = Array.isArray(info.foreground_processes) ? info.foreground_processes : []
+  return {
+    shellPid: positiveInteger(info.shell_pid),
+    groupId: positiveInteger(info.foreground_process_group_id),
+    processes: processes.flatMap(foregroundProcessOf),
+  }
+}
+
+const workspaceEntries = (json: string): unknown[] => {
+  const workspaces = resultFieldOf(json, 'workspaces', 'workspace list')
+  if (!Array.isArray(workspaces)) throw unexpected('workspace list')
+  return workspaces
+}
+
+const isMainCheckoutOf =
+  (root: string) =>
+  (workspace: unknown): workspace is { workspace_id: string } => {
+    if (!isRecord(workspace) || typeof workspace.workspace_id !== 'string') return false
+    const { worktree } = workspace
+    return isRecord(worktree) && worktree.checkout_path === root && worktree.is_linked_worktree === false
+  }
+
+/**
+ * The herdr workspace of the main checkout `root`; throws when there is none or several, since the backend's tab
+ * must sit in exactly one place.
+ */
+export const mainWorkspaceOf = (json: string, root: string): string => {
+  const matches = workspaceEntries(json).filter(isMainCheckoutOf(root))
+  if (matches.length === 1 && matches[0]) return matches[0].workspace_id
+  throw new Error(`backend: ${matches.length} herdr workspaces of the main checkout, need exactly one`)
+}
+
+/** The tab ids of a `herdr tab list` answer; throws on a changed answer. */
+export const tabIdsOf = (json: string): string[] => {
+  const tabs = resultFieldOf(json, 'tabs', 'tab list')
+  if (!Array.isArray(tabs)) throw unexpected('tab list')
+  return tabs.flatMap((tab) => (isRecord(tab) && typeof tab.tab_id === 'string' ? [tab.tab_id] : []))
+}
+
+/** The root pane of a `herdr tab create` answer; throws on a changed answer. */
+export const createdPaneOf = (json: string): string => {
+  const pane = resultFieldOf(json, 'root_pane', 'tab create')
+  if (!isRecord(pane) || typeof pane.pane_id !== 'string') throw unexpected('tab create')
+  return pane.pane_id
+}
+
+/** A pane whose foreground is a shell, or nothing yet: the command it ran has ended. */
+const isShellOnly = (pane: PaneState): boolean => isIdleShell(pane) || isStartingShell(pane)
+
+/**
+ * The backend pane among `panes`: the one labelled `label` in a tab of the main checkout's workspace (`tabs`). It
+ * is touched only when it is the only such pane, works in `root` and holds no agent; otherwise the check refuses
+ * with a line and leaves every pane alone.
+ */
+export const backendSightOf = (input: {
+  panes: readonly PaneListing[]
+  tabs: readonly string[]
+  label: string
+  root: string
+  foregroundOf: (pane: string) => string[][]
+}): BackendSight => {
+  const { panes, tabs, label, root } = input
+  const labelled = panes.filter((pane) => pane.label === label && tabs.includes(pane.tab))
+  if (labelled.length === 0)
+    return { kind: 'found', pane: BACKEND_PANE.missing, paneId: null, place: `new tab ${label}` }
+  const [pane] = labelled
+  if (labelled.length > 1 || !pane)
+    return { kind: 'refused', line: `backend: ${labelled.length} panes labelled ${label}, left alone` }
+  if (pane.agent) return { kind: 'refused', line: `backend: an agent runs in pane ${pane.pane} (${label}), left alone` }
+  if (pane.cwd !== root)
+    return { kind: 'refused', line: `backend: pane ${pane.pane} (${label}) is not in the main checkout, left alone` }
+  const shellOnly = isShellOnly({ ...pane, foreground: input.foregroundOf(pane.pane) })
+  return {
+    kind: 'found',
+    pane: shellOnly ? BACKEND_PANE.exited : BACKEND_PANE.running,
+    paneId: pane.pane,
+    place: pane.pane,
+  }
+}
+
+/**
+ * The process to send SIGTERM to: the leader of the pane's foreground process group, never the pane's shell, and only
+ * when `cwdOf` shows it works in `root`. Anything else refuses with a line that leaves the stop to the user.
+ */
+export const stopTargetOf = (
+  processes: PaneProcesses,
+  root: string,
+  cwdOf: (pid: number) => string | null,
+  pane: string,
+): StopTarget => {
+  const { groupId, shellPid } = processes
+  const leader = processes.processes.find((each) => each.pid === groupId)
+  if (groupId === null || groupId === shellPid || !leader)
+    return { ok: false, line: `backend: no process to stop in pane ${pane}; stop it there by hand` }
+  if (cwdOf(leader.pid) !== root)
+    return {
+      ok: false,
+      line: `backend: process ${leader.pid} in pane ${pane} is not in the main checkout; stop it there by hand`,
+    }
+  return { ok: true, pid: leader.pid }
+}

package/src/backend/lock.ts

@@ -0,0 +1,84 @@
+import { closeSync, openSync, readFileSync, rmSync, statSync, writeSync } from 'node:fs'
+import { lockedPid } from '../watch/watcher-lock'
+
+const PRIVATE_FILE = 0o600
+const RETRY_MS = 200
+const UNFILLED_LOCK_MS = 10_000
+/** Longer than any call holds the lock: a `jh backend` call waits at most 90 s for it and 30 s for a stop. */
+const HELD_LOCK_MS = 5 * 60_000
+
+/** Whether a process with this id exists; a process of another user still counts as alive. */
+const isAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+const readHolder = (path: string): number | null => {
+  try {
+    return lockedPid(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+const modifiedAt = (path: string): number | null => {
+  try {
+    return statSync(path).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A lock whose holder has ended, one older than `HELD_LOCK_MS` (no call holds it that long, so its process id was
+ * reused by another process), or one without a holder (a writer between creating and filling it) that is older than
+ * `UNFILLED_LOCK_MS`.
+ */
+const isStale = (path: string): boolean => {
+  const modified = modifiedAt(path)
+  const age = modified === null ? 0 : Date.now() - modified
+  const holder = readHolder(path)
+  if (holder !== null) return !isAlive(holder) || age > HELD_LOCK_MS
+  return age > UNFILLED_LOCK_MS
+}
+
+/** Creates the lock file with this process's id; false when another holds it. A lock of a process that ended is taken over. */
+const tryLock = (path: string): boolean => {
+  try {
+    const descriptor = openSync(path, 'wx', PRIVATE_FILE)
+    writeSync(descriptor, String(process.pid))
+    closeSync(descriptor)
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+    if (!isStale(path)) return false
+    rmSync(path, { force: true })
+    return tryLock(path)
+  }
+}
+
+/**
+ * Runs `work` while this process holds the lock at `path`, so the watcher and `jh backend` never write `backend.json`
+ * over each other. Waits up to `waitMs` for another holder; null when the lock stayed taken (the watcher passes 0 and
+ * tries again at its next check).
+ *
+ * Accepted risk: two callers that find the same stale lock at the same moment can both remove it, and the second
+ * removes the lock the first just created; both then run. It needs a holder that died and two callers within
+ * milliseconds, and both are the same user's watcher and `jh backend`.
+ */
+export const withBackendLock = async <T>(path: string, waitMs: number, work: () => Promise<T>): Promise<T | null> => {
+  const deadline = Date.now() + waitMs
+  while (!tryLock(path)) {
+    if (Date.now() >= deadline) return null
+    await Bun.sleep(RETRY_MS)
+  }
+  try {
+    return await work()
+  } finally {
+    if (readHolder(path) === process.pid) rmSync(path, { force: true })
+  }
+}

package/src/backend/process-cwd.ts

@@ -0,0 +1,32 @@
+import { readlinkSync } from 'node:fs'
+
+/** Longest an `lsof` call may take; a call past it counts as no answer. */
+const LSOF_TIMEOUT_MS = 2000
+
+/** The directory of an `lsof -Fn` answer for one process's `cwd`: the line that starts with `n`. */
+export const cwdOfLsofOutput = (output: string): string | null => {
+  const line = output.split('\n').find((each) => each.startsWith('n'))
+  return line ? line.slice(1) : null
+}
+
+const linuxCwdOf = (pid: number): string | null => {
+  try {
+    return readlinkSync(`/proc/${pid}/cwd`)
+  } catch {
+    return null
+  }
+}
+
+const lsofCwdOf = (pid: number): string | null => {
+  const result = Bun.spawnSync(['lsof', '-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'ignore',
+    timeout: LSOF_TIMEOUT_MS,
+  })
+  return result.exitCode === 0 ? cwdOfLsofOutput(result.stdout.toString()) : null
+}
+
+/** The working directory of a process: `/proc/<pid>/cwd` on Linux, `lsof` elsewhere (macOS); null when unreadable. */
+export const processCwdOf = (pid: number, platform: NodeJS.Platform = process.platform): string | null =>
+  platform === 'linux' ? linuxCwdOf(pid) : lsofCwdOf(pid)

package/src/backend/schema.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod'
+import { MAX_PORT } from '../lane/port'
+import { SHELL_WORD } from '../shared/shell-word'
+
+/** Where the names of the services not handed to a lane go in `lanes.backend.command`. */
+export const SERVICES_PLACEHOLDER = '{services}'
+
+/** The pane label of the backend when the config names none. */
+export const DEFAULT_BACKEND_LABEL = 'backend'
+
+/** One herdr argument that cannot read as an option. */
+const BACKEND_LABEL = /^(?!-)[\w.-]+$/
+
+const duplicateIn = (values: readonly (string | number)[]): boolean => new Set(values).size !== values.length
+
+const serviceSchema = z.strictObject({
+  /** The name the command's tool takes, e.g. a package name. */
+  name: z.string().regex(SHELL_WORD, 'must be one shell word of letters, digits and @ . / : _ -, not starting with -'),
+  /** The port the service listens on; checked before a start and named when the service is handed to a lane. */
+  port: z.number().int().min(1).max(MAX_PORT),
+})
+
+export const backendSchema = z
+  .strictObject({
+    /** The command that runs the services in the main checkout; `{services}` becomes the names of the services not handed to a lane. */
+    command: z
+      .string()
+      .min(1)
+      .refine((command) => command.includes(SERVICES_PLACEHOLDER), `must contain ${SERVICES_PLACEHOLDER}`),
+    services: z.array(serviceSchema).min(1),
+    /** The label of the backend pane; `backend` when left out. */
+    label: z
+      .string()
+      .regex(BACKEND_LABEL, 'letters, digits and . _ -, not starting with -')
+      .default(DEFAULT_BACKEND_LABEL),
+  })
+  .refine(({ services }) => !duplicateIn(services.map(({ name }) => name)), {
+    message: 'service names must be unique',
+    path: ['services'],
+  })
+  .refine(({ services }) => !duplicateIn(services.map(({ port }) => port)), {
+    message: 'service ports must be unique',
+    path: ['services'],
+  })
+
+/** The shared backend of the lanes: its command, the services it runs and the pane label. */
+export type BackendConfig = z.infer<typeof backendSchema>

package/src/backend/state.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod'
+
+/** What the watcher sees of the backend pane. */
+export const BACKEND_PANE = { missing: 'missing', running: 'running', exited: 'exited' } as const
+
+export type BackendPane = (typeof BACKEND_PANE)[keyof typeof BACKEND_PANE]
+
+export const isBackendPane = (value: string): value is BackendPane =>
+  (Object.values(BACKEND_PANE) as string[]).includes(value)
+
+/** The version `backend.json` is written with; a file of another version is read as empty. */
+export const BACKEND_STATE_VERSION = 1
+
+const backendStateSchema = z.strictObject({
+  version: z.literal(BACKEND_STATE_VERSION),
+  /** The command line last started, null before the first start. */
+  command: z.string().nullable(),
+  /** The services a lane works on, by service name and lane name. */
+  released: z.array(z.strictObject({ service: z.string(), lane: z.string() })),
+  /** When the automatic starts happened, in milliseconds since the epoch. */
+  starts: z.array(z.number()),
+  /** Whether the start limit was reached; only `jh backend restart` clears it. */
+  gaveUp: z.boolean(),
+  /** The last line the watcher reported for a standing condition, so the same line is not repeated; null when none stands. */
+  notice: z.string().nullable(),
+})
+
+/** The content of `backend.json` in the watcher's state directory. */
+export type BackendState = z.infer<typeof backendStateSchema>
+
+export const EMPTY_BACKEND_STATE: BackendState = {
+  version: BACKEND_STATE_VERSION,
+  command: null,
+  released: [],
+  starts: [],
+  gaveUp: false,
+  notice: null,
+}
+
+/** The state in the text of `backend.json`; a missing, old or damaged file reads as the empty state. */
+export const parseBackendState = (text: string | null): BackendState => {
+  if (text === null) return EMPTY_BACKEND_STATE
+  try {
+    const parsed = backendStateSchema.safeParse(JSON.parse(text))
+    return parsed.success ? parsed.data : EMPTY_BACKEND_STATE
+  } catch {
+    return EMPTY_BACKEND_STATE
+  }
+}
+
+/** The state after `jh backend restart`: the start history and "gave up" are forgotten, the handovers stay. */
+export const restarted = (state: BackendState): BackendState => ({
+  ...state,
+  starts: [],
+  gaveUp: false,
+  notice: null,
+})