jackherd 1.23.2 → 1.24.0

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.23.2"
+version = "1.24.0"
 min_herdr_version = "0.8.2"
 description = "Show the herd, the state of a board's lanes, in a herdr pane"
 platforms = ["linux", "macos"]

package/install.sh

@@ -9,7 +9,7 @@ set -eu
 
 # The default is the version this file ships with. The release bump changes it together with
 # package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
-JACKHERD_VERSION="${JACKHERD_VERSION:-1.23.2}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.24.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/merge-guard/decision.ts

@@ -821,7 +821,7 @@ const paneInputSentence = (commands: string[]): string[] =>
   commands.length === 0
     ? []
     : [
-        `${commands.map((command) => `\`${command}\``).join(' and ')} writes input into a pane; the herd takes clicks from it, so the user confirms it. Only \`${LIFTABLE_PANE_INPUT}\` passes, once per call, into a plain pane id (\`${LIFTABLE_PANE_INPUT} w1:p2 …\` at the start of its command, no wrapper or assignment before it, every word fixed) whose foreground herdr names and which is not the herd, with a command that names no guarded command, no input into a pane and no herd. To end a lane's session, do not type into its pane: send \`herdr agent prompt <lane> /exit\` as a call of its own.`,
+        `${commands.map((command) => `\`${command}\``).join(' and ')} writes input into a pane; the herd takes clicks from it, so the user confirms it. Only \`${LIFTABLE_PANE_INPUT}\` passes, once per call, into a plain pane id (\`${LIFTABLE_PANE_INPUT} w1:p2 …\` at the start of its command, no wrapper or assignment before it, every word fixed) whose foreground herdr names and which is not the herd, with a command that names no guarded command, no input into a pane and no herd. To end a lane's session, do not type into its pane: send \`herdr agent prompt <lane> /exit\` as a call of its own. To restart a dev server, stop it by its PID (the port names it, \`/proc/<pid>/cwd\` shows the lane's worktree), then \`herdr pane run\` the same command in its pane.`,
       ]
 
 /** Why an input into an agent asks: a key there can answer the dialog the agent has open, as if the user clicked. */

package/kit/workflow/skills/orchestrate/SKILL.md

@@ -86,7 +86,8 @@ through steps 0 to 8. One line to the user afterwards.
 ## 3. Dev server
 
 A lane whose phase changes something a user sees gets its dev server **when the lane starts**:
-[`references/start-lane.md`](references/start-lane.md).
+[`references/start-lane.md`](references/start-lane.md); with `lanes.backend`, the services of the shared backend:
+[`references/backend.md`](references/backend.md).
 
 ## 4. Watch
 

package/kit/workflow/skills/orchestrate/references/backend.md

@@ -0,0 +1,30 @@
+# § 3: the shared backend of `lanes.backend`
+
+Read on a `backend:` watcher line, or at a lane's start (`start-lane.md` § 3) when `lanes.backend`
+is set. The services every lane's app talks to run in one pane of a tab in the main checkout; the watcher starts and
+keeps it. Without `lanes.backend` nothing here applies.
+
+## At a lane's start
+
+When the phase's Writes column names a path of one of those services, hand that service to the lane first, from the
+main checkout: `jh backend release <service> --lane <lane>` restarts the backend pane without it and prints the freed
+port; then `jh lane dev <lane> --filter <service> --port <port>`. Only you call `jh backend release`, from the main
+checkout; a lane that finds out later asks in its report. Before `jh lane close`, stop the lane's dev server, then
+`jh backend return <service>`; done when it prints that the service returned. Skipped, the watcher returns it once the
+worktree is gone.
+
+## Watcher lines
+
+Each line is said once while it stands, without the `backend: ` prefix. A `kit updated` leaves the pane running.
+
+| Line | What to do |
+| --- | --- |
+| `started in <pane>` | Nothing. |
+| `port <n> in use, not started` | Find the holder as in `start-lane.md` § 3; a lane's server for a handed-over service (`jh backend` lists them) is the lane's, any other goes to the user. The pane starts once the port is free. |
+| `running command differs from lanes.backend` | The config changed after the start. Tell the user once; `jh backend restart` after they agree, since it stops the services. |
+| `gave up after 3 starts in 10 minutes` | The command ends right after it starts. Read the pane, tell the user the cause; `jh backend restart` once fixed. |
+| `<service> returned from <lane> (worktree gone)` | Nothing. |
+| `backend check failed, still watching: <reason>` | Fix the cause (herdr answering, one workspace of the main checkout, `lanes.backend` readable); done when `jh backend` shows the pane. |
+| `… left alone` (several panes with the label, an agent in the pane, a pane outside the main checkout) | Tell the user; the pane is theirs. |
+
+`jh backend` only ever stops the process in the backend pane; a pane it cannot read goes to the user.

package/kit/workflow/skills/orchestrate/references/close-lane.md

@@ -9,6 +9,7 @@ or when the user names a lane to close. Run both commands from the main checkout
    nothing: resolve each reason it prints (a named file goes to the user first, a working agent is waited for, a lock
    is lifted once its session ended, an unmerged branch is not closed) and repeat until it exits 0.
    A worktree on no branch closes when its head is on the base branch and only staged plan changes the base holds are left.
+   Handed-over service: [`backend.md`](backend.md).
 2. `jh lane close <lane>` Run it without asking the user; its checks are the safeguard. It repeats the step 1 checks (resolve a refusal as in step 1) and runs the listed steps, one line each. After a failure,
    run it again: with the worktree gone and the branch left, `jh lane close <lane> --branch <branch>` finishes the
    branch and the board; a lane closed in full says so and changes nothing.

package/kit/workflow/skills/orchestrate/references/start-lane.md

@@ -62,5 +62,9 @@ herdr pane run <new-pane> "PORT=<port> {{kit.command.dev}}"
 ```
 
 The new pane starts in the lane's worktree; check with `/proc/<pid>/cwd` (macOS: `lsof -p <pid>`) that the server runs
-there, and before stopping one by PID. Stop only a server you started; another's port
+there, also before stopping one by PID. Stop only a server you started; another's port
 goes to the user.
+
+To restart it after a rebase, stop it by PID (found through the port) once `/proc/<pid>/cwd` (macOS: `lsof -p <pid>`) shows
+the lane's worktree, then `herdr pane run <pane> "<the same command>"` in the same pane. Each step is its own call and
+passes the pane guard without a question; keys typed into the pane ask the user.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.23.2",
+  "version": "1.24.0",
   "keywords": [
     "claude-code",
     "coding-agents",

package/schemas/jackherd.schema.json

@@ -156,6 +156,48 @@
         "devCommand": {
           "type": "string",
           "minLength": 1
+        },
+        "backend": {
+          "type": "object",
+          "properties": {
+            "command": {
+              "type": "string",
+              "minLength": 1
+            },
+            "services": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "pattern": "^(?!-)[\\w@./:-]+$"
+                  },
+                  "port": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 65535
+                  }
+                },
+                "required": [
+                  "name",
+                  "port"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "label": {
+              "default": "backend",
+              "type": "string",
+              "pattern": "^(?!-)[\\w.-]+$"
+            }
+          },
+          "required": [
+            "command",
+            "services"
+          ],
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

package/src/backend/command-line.ts

@@ -0,0 +1,116 @@
+import { readConfig } from '../config/read-config'
+import { TERMINAL_ADAPTER } from '../config/schema'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { mainCheckout } from '../plans/git'
+import { asksForHelp } from '../preview/options'
+import { CLI_NAME } from '../version/release'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+import {
+  type BackendOutcome,
+  type BackendSystem,
+  releaseService,
+  restartBackend,
+  returnService,
+  statusLines,
+} from './control'
+import { withBackendLock } from './lock'
+import type { BackendConfig } from './schema'
+import { backendFilesOf, backendSystemOf } from './system'
+
+/** The exit codes of `jh backend`: done, refused, and a call it does not understand. */
+export const BACKEND_EXIT = { done: 0, refused: 1, usage: 2 } as const
+
+export const BACKEND_REQUEST = { status: 'status', restart: 'restart', release: 'release', return: 'return' } as const
+
+/** What `jh backend` was asked for. */
+export type BackendRequest =
+  | { kind: typeof BACKEND_REQUEST.status }
+  | { kind: typeof BACKEND_REQUEST.restart }
+  | { kind: typeof BACKEND_REQUEST.release; service: string; lane: string }
+  | { kind: typeof BACKEND_REQUEST.return; service: string }
+
+const LANE = '--lane'
+
+/** How long a call waits for the watcher's check, which may itself wait for a stop. */
+const LOCK_WAIT_MS = 90_000
+
+export const BACKEND_USAGE = `usage: ${CLI_NAME} backend
+       ${CLI_NAME} backend restart
+       ${CLI_NAME} backend release <service> ${LANE} <lane>
+       ${CLI_NAME} backend return <service>
+
+The shared backend of the lanes (lanes.backend): one pane in a tab of the main checkout that the watcher starts and
+keeps. Without arguments it shows the pane, the command last started, the services handed to lanes and the recent
+starts. restart stops the pane, forgets "gave up" and starts it again. release takes a service out of the backend,
+so a lane runs it itself (${CLI_NAME} lane dev <lane> --filter <service> --port <port>); return puts it back. A busy
+service port prevents a start; nothing frees a port.`
+
+const usage = (): never => {
+  throw new Error(BACKEND_USAGE)
+}
+
+/** Reads the arguments of `jh backend`; throws with the usage on anything else. */
+export const parseBackendRequest = (args: readonly string[]): BackendRequest => {
+  const [kind, service, option, lane, ...rest] = args
+  if (kind === undefined) return { kind: BACKEND_REQUEST.status }
+  if (kind === BACKEND_REQUEST.restart && args.length === 1) return { kind }
+  if (kind === BACKEND_REQUEST.return && service !== undefined && args.length === 2) return { kind, service }
+  const isRelease = kind === BACKEND_REQUEST.release && service !== undefined && option === LANE
+  if (isRelease && lane !== undefined && rest.length === 0 && SAFE_LANE_NAME.test(lane)) return { kind, service, lane }
+  return usage()
+}
+
+/** Carries out `request` against the backend; the caller holds the lock. */
+export const carryOutRequest = async (
+  request: BackendRequest,
+  backend: BackendConfig,
+  system: BackendSystem,
+): Promise<BackendOutcome> => {
+  if (request.kind === BACKEND_REQUEST.restart) return restartBackend(backend, system)
+  if (request.kind === BACKEND_REQUEST.release) return releaseService(backend, system, request.service, request.lane)
+  if (request.kind === BACKEND_REQUEST.return) return returnService(backend, system, request.service)
+  return { ok: true, lines: statusLines(await system.look(), system.readState(), system.now()) }
+}
+
+/** The backend of the main checkout's own config: a lane's worktree must not change the command the main checkout runs. */
+const backendOfMainCheckout = (root: string) => {
+  const config = readConfig([root])
+  if (config.terminal.adapter !== TERMINAL_ADAPTER.herdr) throw new Error('backend: needs terminal.adapter herdr')
+  if (!config.lanes.backend) throw new Error('backend: no lanes.backend in the main checkout .jackherd/config.json')
+  return { backend: config.lanes.backend, worktreeDirectory: config.worktreeDirectory }
+}
+
+const print = (lines: readonly string[]) => {
+  for (const line of lines) console.log(terminalSafe(line))
+}
+
+/**
+ * `jh backend [restart | release <service> --lane <lane> | return <service>]`: works on the main checkout from any
+ * worktree. Exit 0 done, 1 refused, 2 usage.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(BACKEND_USAGE)
+    return BACKEND_EXIT.done
+  }
+  let request: BackendRequest
+  try {
+    request = parseBackendRequest(args)
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return BACKEND_EXIT.usage
+  }
+  try {
+    const root = mainCheckout(cwd)
+    const { backend, worktreeDirectory } = backendOfMainCheckout(root)
+    const files = backendFilesOf(root)
+    const system = backendSystemOf({ root, worktreeDirectory, backend, files })
+    const outcome = await withBackendLock(files.lock, LOCK_WAIT_MS, () => carryOutRequest(request, backend, system))
+    if (outcome === null) throw new Error('backend: the watcher holds the backend lock; try again in a minute')
+    print(outcome.lines)
+    return outcome.ok ? BACKEND_EXIT.done : BACKEND_EXIT.refused
+  } catch (error) {
+    console.error(terminalSafe(error instanceof Error ? error.message : String(error)))
+    return BACKEND_EXIT.refused
+  }
+}

package/src/backend/command.ts

@@ -0,0 +1,14 @@
+import { type BackendConfig, SERVICES_PLACEHOLDER } from './schema'
+
+/** Frees the lanes' `PORT` for the services: a service reading `PORT ?? <NAME>_PORT` must not bind a lane's port. */
+export const BACKEND_ENVIRONMENT_PREFIX = 'env -u PORT '
+
+/**
+ * The shell line of the backend pane: the configured command without `PORT`, with `{services}` filled by the services
+ * not handed to a lane, in configuration order. Null when none is left to run.
+ */
+export const backendCommandOf = (backend: BackendConfig, released: readonly string[]): string | null => {
+  const names = backend.services.map(({ name }) => name).filter((name) => !released.includes(name))
+  if (names.length === 0) return null
+  return `${BACKEND_ENVIRONMENT_PREFIX}${backend.command.replaceAll(SERVICES_PLACEHOLDER, names.join(' '))}`
+}

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