jackherd 1.16.0 → 1.18.0

package/src/lane/close-options.ts

@@ -3,19 +3,37 @@ import { SAFE_LANE_NAME } from '../watch/lane-name'
 import { DRY_RUN_OPTION, LANE_CLOSE_COMMAND } from './close-command-line'
 
 /** What `jh lane close` was asked for; `boardPath` is null where `--board` was left out. */
-export type CloseOptions = { lane: string; dryRun: boolean; boardPath: string | null }
+export type CloseOptions = { lane: string; dryRun: boolean; boardPath: string | null; branch: string | null }
 
 const BOARD = '--board'
+const BRANCH = '--branch'
+/** A branch name as the lane setup makes one; no leading dash or dot, no `..`, no `//`, no trailing `/` or `.lock`. */
+const SAFE_BRANCH = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/
+const isBranchName = (name: string): boolean =>
+  SAFE_BRANCH.test(name) &&
+  !name.includes('..') &&
+  !name.includes('//') &&
+  !name.endsWith('/') &&
+  !name.endsWith('.lock')
 
-export const LANE_CLOSE_USAGE = `usage: ${LANE_CLOSE_COMMAND} <lane> [${DRY_RUN_OPTION}] [--board <board.md>]
+export const LANE_CLOSE_USAGE = `usage: ${LANE_CLOSE_COMMAND} <lane> [${DRY_RUN_OPTION}] [--board <board.md>] [${BRANCH} <branch>]
 
 Closes a lane whose pull request is merged, once nothing in it would be lost: exits its agent, removes its workspace,
 worktree and local branch, and marks its rows in the board with a history row. Refuses with every reason otherwise.
   --dry-run            check and print the steps, change nothing
-  --board <board.md>   the board to mark; without it the board is picked as for ${CLI_NAME} herd`
+  --board <board.md>   the board to mark; without it the board is picked as for ${CLI_NAME} herd
+  --branch <branch>    finishes a lane whose worktree is gone already (a close that stopped half way): the branch
+                       to prove merged and delete`
 
 const usageError = (message: string): Error => new Error(`${message}\n${LANE_CLOSE_USAGE}`)
 
+/** The value after an option; refused when the line ends or the next word is an option. */
+const valueAfter = (args: readonly string[], index: number, option: string): string => {
+  const value = args[index + 1]
+  if (value === undefined || value.startsWith('--')) throw usageError(`${option} needs a value`)
+  return value
+}
+
 const laneOf = (words: readonly string[]): string => {
   if (words.length === 0) throw usageError('the lane is required')
   if (words.length > 1) throw usageError(`one lane at most, got ${words.join(' ')}`)
@@ -23,21 +41,24 @@ const laneOf = (words: readonly string[]): string => {
   return words[0]
 }
 
-/** Reads `<lane> [--dry-run] [--board <file>]` in any order, the arguments after `close`; throws on a wrong line. */
+/** Reads `<lane> [--dry-run] [--board <file>] [--branch <name>]` in any order, the arguments after `close`; throws on a wrong line. */
 export const parseCloseOptions = (args: readonly string[]): CloseOptions => {
   const words: string[] = []
   let dryRun = false
   let boardPath: string | null = null
+  let branch: string | null = null
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i]
     if (arg === DRY_RUN_OPTION) dryRun = true
     else if (arg === BOARD) {
-      const value = args[i + 1]
-      if (value === undefined || value.startsWith('--')) throw usageError(`${BOARD} needs a value`)
-      boardPath = value
+      boardPath = valueAfter(args, i, BOARD)
+      i += 1
+    } else if (arg === BRANCH) {
+      branch = valueAfter(args, i, BRANCH)
+      if (!isBranchName(branch)) throw usageError(`${branch} is no branch name`)
       i += 1
     } else if (arg.startsWith('--')) throw usageError(`unknown option ${arg}`)
     else words.push(arg)
   }
-  return { lane: laneOf(words), dryRun, boardPath }
+  return { lane: laneOf(words), dryRun, boardPath, branch }
 }

package/src/lane/close-survey.ts

@@ -2,7 +2,7 @@ import { sep } from 'node:path'
 import { isRecord } from '../shared/is-record'
 import type { LaneAgent } from '../terminal'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from '../watch/pull-requests'
-import type { CloseFacts, MergedPullRequest } from './close-check'
+import type { CloseFacts, MergedPullRequest, StatusEntry } from './close-check'
 
 /** A worktree as `git worktree list --porcelain` lists it; `branch` null when detached, `locked` as in `CloseFacts`. */
 export type WorktreeEntry = { head: string; branch: string | null; locked: string | null }
@@ -81,3 +81,15 @@ export const agentFactsOf = (
     otherAgents: inWorktree.filter((agent) => agent !== own).map(({ pane }) => pane),
   }
 }
+
+const STAGED_ONLY = /^[MARC] $/
+
+/** The staged-and-nothing-more changes under `planDirectory`: the paths a worktree on no branch may hold if the base does. */
+export const stagedPlanPathsOf = (status: readonly StatusEntry[], planDirectory: string): string[] =>
+  status
+    .filter(({ code, path }) => STAGED_ONLY.test(code) && path.startsWith(`${planDirectory.replace(/\/+$/, '')}/`))
+    .map(({ path }) => path)
+
+/** The candidates the base branch holds as they are staged, that is, those `git diff --cached <base>` does not list. */
+export const baseHeldPathsOf = (candidates: readonly string[], differing: readonly string[]): string[] =>
+  candidates.filter((path) => !differing.includes(path))

package/src/lane/close.ts

@@ -35,25 +35,44 @@ export type ClosePorts = {
   printError: (line: string) => void
 }
 
-type ClosedLane = { lane: string } & ClosableLane
+type BranchLane = Extract<ClosableLane, { kind: 'branch' }>
+
+type ClosedLane = { lane: string; closable: ClosableLane }
 
 type Step = { label: string; run: () => Promise<void> | void }
 
 /** A merge commit as the history row cites it. */
 const SHORT_COMMIT_LENGTH = 7
 
-const HISTORY_TEXT: Record<PlanLanguage, (closed: ClosedLane, mergeCommit: string) => string> = {
-  [PLAN_LANGUAGE.de]: ({ lane, branch, pullRequest }, mergeCommit) =>
+const BRANCH_HISTORY_TEXT: Record<PlanLanguage, (lane: string, closed: BranchLane, mergeCommit: string) => string> = {
+  [PLAN_LANGUAGE.de]: (lane, { branch, pullRequest }, mergeCommit) =>
     `Spur \`${lane}\` abgeräumt mit \`${LANE_CLOSE_COMMAND}\`: PR #${pullRequest.number} gemergt (\`${mergeCommit}\`), Baum gleich Merge, Worktree entfernt, lokaler Branch \`${branch}\` gelöscht`,
-  [PLAN_LANGUAGE.en]: ({ lane, branch, pullRequest }, mergeCommit) =>
+  [PLAN_LANGUAGE.en]: (lane, { branch, pullRequest }, mergeCommit) =>
     `Lane \`${lane}\` cleaned up with \`${LANE_CLOSE_COMMAND}\`: PR #${pullRequest.number} merged (\`${mergeCommit}\`), tree equal to the merge, worktree removed, local branch \`${branch}\` deleted`,
 }
 
+const DETACHED_HISTORY_TEXT: Record<PlanLanguage, (lane: string, head: string) => string> = {
+  [PLAN_LANGUAGE.de]: (lane, head) =>
+    `Spur \`${lane}\` abgeräumt mit \`${LANE_CLOSE_COMMAND}\`: Worktree ohne Branch, Stand \`${head}\` liegt auf dem Basis-Branch, Worktree entfernt`,
+  [PLAN_LANGUAGE.en]: (lane, head) =>
+    `Lane \`${lane}\` cleaned up with \`${LANE_CLOSE_COMMAND}\`: worktree on no branch, head \`${head}\` is on the base branch, worktree removed`,
+}
+
 const clockOf = (time: Date): string => `${twoDigits(time.getHours())}:${twoDigits(time.getMinutes())}`
 
 /** The history row's text: the time, then what was closed and proven, in the board's language. */
-export const historyText = (closed: ClosedLane, request: Pick<CloseRequest, 'now' | 'language'>): string =>
-  `${clockOf(request.now)}: ${HISTORY_TEXT[request.language](closed, closed.pullRequest.mergeCommit.slice(0, SHORT_COMMIT_LENGTH))}`
+export const historyText = (closed: ClosedLane, request: Pick<CloseRequest, 'now' | 'language'>): string => {
+  const { lane, closable } = closed
+  const text =
+    closable.kind === 'detached'
+      ? DETACHED_HISTORY_TEXT[request.language](lane, closable.head.slice(0, SHORT_COMMIT_LENGTH))
+      : BRANCH_HISTORY_TEXT[request.language](
+          lane,
+          closable,
+          closable.pullRequest.mergeCommit.slice(0, SHORT_COMMIT_LENGTH),
+        )
+  return `${clockOf(request.now)}: ${text}`
+}
 
 /** The board with the lane's rows marked and the history row on top. */
 const closedBoard = (board: string, closed: ClosedLane, request: CloseRequest): string =>
@@ -73,16 +92,28 @@ const boardLabel = (facts: CloseFacts, request: CloseRequest): string =>
 const removalSteps = (closed: ClosedLane, survey: CloseSurvey, request: CloseRequest, ports: ClosePorts): Step[] => {
   const { workspace, facts } = survey
   const place = workspace === null ? '' : ` and close workspace ${workspace}`
+  const worktree: Step[] = facts.worktreeExists
+    ? [
+        {
+          label: `remove worktree ${request.worktree}${place}`,
+          run: () => ports.removeWorktree(request.worktree, workspace),
+        },
+      ]
+    : []
   return [
-    {
-      label: `remove worktree ${request.worktree}${place}`,
-      run: () => ports.removeWorktree(request.worktree, workspace),
-    },
-    { label: `delete branch ${closed.branch}`, run: () => ports.deleteBranch(closed.branch, closed.head) },
+    ...worktree,
+    ...branchSteps(closed.closable, ports),
     { label: boardLabel(facts, request), run: () => ports.writeBoard(closedBoard(ports.readBoard(), closed, request)) },
   ]
 }
 
+/** Deleting the branch is a step only while the branch exists: a lane resumed after a partial failure may have lost it. */
+const branchSteps = (closable: ClosableLane, ports: ClosePorts): Step[] => {
+  if (closable.kind === 'detached' || closable.head === null) return []
+  const { branch, head } = closable
+  return [{ label: `delete branch ${branch}`, run: () => ports.deleteBranch(branch, head) }]
+}
+
 const exitSteps = ({ facts }: CloseSurvey, request: CloseRequest, ports: ClosePorts): Step[] => {
   const { agent } = facts
   if (agent === null) return []
@@ -91,10 +122,14 @@ const exitSteps = ({ facts }: CloseSurvey, request: CloseRequest, ports: ClosePo
   ]
 }
 
+/** Nothing is left to close: no worktree, no branch, and the board marks the lane. */
+const isClosedInFull = ({ worktreeExists, head, boardLane }: CloseFacts): boolean =>
+  !worktreeExists && head === null && boardLane === BOARD_LANE.closed
+
 /** The lane closable from `survey`, or null after printing every reason against it under `heading`. */
 const checked = (survey: CloseSurvey, heading: string, request: CloseRequest, ports: ClosePorts): ClosedLane | null => {
   const verdict = closeVerdict(survey.facts)
-  if (verdict.kind === 'closable') return { lane: request.lane, ...verdict }
+  if (verdict.kind === 'closable') return { lane: request.lane, closable: verdict.lane }
   ports.printError(heading)
   for (const refusal of verdict.refusals) ports.printError(`  ${terminalSafe(refusal)}`)
   return null
@@ -123,6 +158,10 @@ const runSteps = async (steps: readonly Step[], ports: ClosePorts): Promise<bool
  */
 export const closeLane = async (request: CloseRequest, ports: ClosePorts): Promise<number> => {
   const first = await ports.survey()
+  if (isClosedInFull(first.facts)) {
+    ports.print(`${request.lane} is closed already: no worktree, no branch, and the board marks it`)
+    return 0
+  }
   const closed = checked(first, `not closing ${request.lane}:`, request, ports)
   if (closed === null) return 1
   const exit = exitSteps(first, request, ports)

package/src/lane/command.ts

@@ -1,13 +1,31 @@
 import { run as runPrompt } from '../lane-prompt/command'
+import { asksForHelp } from '../preview/options'
+import { startLaneHintFor } from './start-lane-hint'
 
 const CLOSE = 'close'
+const SPACE = 'space'
+const SEND = 'send'
+const BASE = 'base'
+
+/** `code` after the call; a call from the main checkout that succeeded adds the hint to the start-lane reference on stderr, so the output a caller captures stays the one value. */
+const withStartLaneHint = (code: number, args: readonly string[], cwd: string): number => {
+  const hint = code === 0 && !asksForHelp(args) ? startLaneHintFor(cwd) : null
+  if (hint !== null) console.error(hint)
+  return code
+}
 
 /**
- * `jh lane close …` closes a lane, everything else is `jh lane prompt …`. `close` must come first, so the ask rule
- * `jh lane close` always sees it; `jh lane --board b.md close x` reaches the prompt parser and is refused there.
+ * `jh lane close …` closes a lane, `jh lane space …` checks the disk for a new one, `jh lane send …` sends its prompt
+ * file, `jh lane base …` names the ref its worktree starts from, everything else is `jh lane prompt …`. `close` must
+ * come first, so the ask rule `jh lane close` always sees it; `jh lane --board b.md close x` reaches the prompt parser
+ * and is refused there.
  */
 export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
-  if (args[0] !== CLOSE) return runPrompt(args, cwd)
+  if (args[0] === SPACE) return (await import('./space-command')).run(args.slice(1), cwd)
+  if (args[0] === SEND) return (await import('./send-command')).run(args.slice(1), cwd)
+  if (args[0] === BASE)
+    return withStartLaneHint(await (await import('./base-command')).run(args.slice(1), cwd), args.slice(1), cwd)
+  if (args[0] !== CLOSE) return withStartLaneHint(await runPrompt(args, cwd), args, cwd)
   const { run: runClose } = await import('./close-command')
   return runClose(args.slice(1), cwd)
 }

package/src/lane/send-command.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { defaultPromptFile } from '../lane-prompt/command'
+import { mainCheckout } from '../plans/git'
+import { asksForHelp } from '../preview/options'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+import { sendLanePrompt } from './send'
+import { herdrSendPorts } from './send-herdr'
+import { LANE_SEND_USAGE, parseSendOptions } from './send-options'
+
+/**
+ * `jh lane send <lane> [--file <prompt>]`: sends the lane's prompt file (default: the one `jh lane prompt` wrote) to
+ * its agent with `--wait --until working`, and reads the screen on a stall (orchestrate § 2 step 8). Prints one line.
+ * Exit 0 sent, 1 refused or stalled twice.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(LANE_SEND_USAGE)
+    return 0
+  }
+  try {
+    const { lane, file } = parseSendOptions(args)
+    if (!SAFE_LANE_NAME.test(lane)) throw new Error(`${lane} is no lane name (letters, digits, . _ -)`)
+    const path = file === null ? defaultPromptFile(mainCheckout(cwd), lane) : resolve(cwd, file)
+    const outcome = await sendLanePrompt(herdrSendPorts(), lane, readFileSync(path, 'utf8'))
+    console.log(outcome.line)
+    return outcome.exitCode
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/lane/send-herdr.ts

@@ -0,0 +1,77 @@
+import { isRecord } from '../shared/is-record'
+import { herdrBinary } from '../sync/tools'
+import type { HerdrAnswer, SendPorts } from './send'
+
+const PROMPT_TIMEOUT_MS = '30000'
+const SCREEN_LINES = '12'
+const WORKING = 'working'
+const WORKING_POLLS = 10
+const WORKING_POLL_MS = 1000
+
+/** The JSON object herdr printed; empty for anything else. */
+const answerObject = (stdout: string): Record<string, unknown> => {
+  try {
+    const answer: unknown = JSON.parse(stdout)
+    return isRecord(answer) ? answer : {}
+  } catch {
+    return {}
+  }
+}
+
+/** The answer of one herdr call from its exit code and its JSON on stdout: `error.code` where it failed. */
+export const answerOf = (exitCode: number, stdout: string): HerdrAnswer => {
+  if (exitCode === 0) return { ok: true, code: null }
+  const { error } = answerObject(stdout)
+  const code = isRecord(error) ? error.code : undefined
+  return { ok: false, code: typeof code === 'string' ? code : null }
+}
+
+/** Whether the answer of `herdr agent get <lane>` reports the agent as working. */
+export const isWorkingAnswer = (stdout: string): boolean => {
+  const { result } = answerObject(stdout)
+  const agent = isRecord(result) ? result.agent : undefined
+  return isRecord(agent) && agent.agent_status === WORKING
+}
+
+type Run = (args: string[]) => { exitCode: number; stdout: string }
+
+const spawnHerdr =
+  (binary: string): Run =>
+  (args) => {
+    const result = Bun.spawnSync([binary, ...args], { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
+    return { exitCode: result.exitCode, stdout: result.stdout.toString() }
+  }
+
+/** The send's calls on the lane's agent, made with the `herdr` binary; the text is one argument, no shell reads it. */
+export const herdrSendPorts = (run: Run = spawnHerdr(herdrBinary(process.env))): SendPorts => {
+  const isWorking = (lane: string): boolean => isWorkingAnswer(run(['agent', 'get', lane]).stdout)
+  return {
+    prompt: (lane, text) => {
+      const { exitCode, stdout } = run([
+        'agent',
+        'prompt',
+        lane,
+        text,
+        '--wait',
+        '--until',
+        WORKING,
+        '--timeout',
+        PROMPT_TIMEOUT_MS,
+      ])
+      return answerOf(exitCode, stdout)
+    },
+    isWorking,
+    screen: (lane) => run(['agent', 'read', lane, '--source', 'visible', '--lines', SCREEN_LINES]).stdout,
+    enter: (lane) => {
+      const { exitCode, stdout } = run(['agent', 'send-keys', lane, 'enter'])
+      return answerOf(exitCode, stdout)
+    },
+    awaitWorking: async (lane) => {
+      for (let poll = 0; poll < WORKING_POLLS; poll++) {
+        if (isWorking(lane)) return true
+        await Bun.sleep(WORKING_POLL_MS)
+      }
+      return false
+    },
+  }
+}

package/src/lane/send-options.ts

@@ -0,0 +1,23 @@
+import { CLI_NAME } from '../version/release'
+
+/** What `jh lane send` was asked for; `file` is null where `--file` was left out. */
+export type SendOptions = { lane: string; file: string | null }
+
+const FILE = '--file'
+
+export const LANE_SEND_USAGE = `usage: ${CLI_NAME} lane send <lane> [${FILE} <prompt-file>]
+
+Sends the lane's prompt file (default: .claude/handover/<lane>-prompt.md of the main checkout) to its agent and waits
+until it works. On a stall it reads the screen: a lane at work counts as sent, a prompt on the screen gets enter (exit 1 if that does not start the lane), else the
+file is sent once more. A second stall exits 1 with one line for the coordinator.`
+
+/** Reads `<lane> [--file <path>]`; throws with the usage on anything else. */
+export const parseSendOptions = (args: readonly string[]): SendOptions => {
+  const [lane, ...rest] = args
+  if (lane === undefined || lane.startsWith('-')) throw new Error(LANE_SEND_USAGE)
+  if (rest.length === 0) return { lane, file: null }
+  const [option, file, ...extra] = rest
+  if (option !== FILE || file === undefined || file.startsWith('--') || extra.length > 0)
+    throw new Error(LANE_SEND_USAGE)
+  return { lane, file }
+}

package/src/lane/send.ts

@@ -0,0 +1,90 @@
+/** The codes of herdr's answer to `herdr agent prompt --wait` that do not prove the text is lost. */
+export const SEND_CODE = { stalled: 'agent_prompt_stalled', timeout: 'timeout' } as const
+
+/** How long the input line's mark is: whole on any screen width the lane's pane has. */
+const MARK_LENGTH = 40
+
+type Awaitable<T> = T | Promise<T>
+
+/** What one call of herdr answered: `ok`, else the `error.code` of its answer, null when it named none. */
+export type HerdrAnswer = { ok: boolean; code: string | null }
+
+/** The calls the send makes on the lane's agent; the command wires them to `herdr`. */
+export type SendPorts = {
+  /** `herdr agent prompt <lane> <text> --wait --until working`. */
+  prompt: (lane: string, text: string) => Awaitable<HerdrAnswer>
+  /** Whether herdr reports the lane's agent as working. */
+  isWorking: (lane: string) => Awaitable<boolean>
+  /** The visible screen of the lane's agent. */
+  screen: (lane: string) => Awaitable<string>
+  /** `herdr agent send-keys <lane> enter`. */
+  enter: (lane: string) => Awaitable<HerdrAnswer>
+  /** Whether the lane's agent starts working within a few seconds. */
+  awaitWorking: (lane: string) => Awaitable<boolean>
+}
+
+export type SendOutcome = {
+  kind: 'sent' | 'entered' | 'resent' | 'failed'
+  exitCode: 0 | 1
+  /** The one line for Jack. */
+  line: string
+}
+
+const isStall = ({ code }: HerdrAnswer): boolean => code === SEND_CODE.stalled || code === SEND_CODE.timeout
+
+/** The start of the prompt's first line: what the input line shows while the text waits there, unsent. */
+export const inputLineMarkOf = (prompt: string): string =>
+  (prompt.split('\n').find((line) => line.trim() !== '') ?? '').slice(0, MARK_LENGTH)
+
+const outcome = (kind: SendOutcome['kind'], lane: string, text: string): SendOutcome => ({
+  kind,
+  exitCode: kind === 'failed' ? 1 : 0,
+  line: `${lane}: ${text}`,
+})
+
+const refused = (lane: string, answer: HerdrAnswer): SendOutcome =>
+  outcome('failed', lane, `herdr refused the prompt (${answer.code ?? 'unknown'}); ask the user.`)
+
+/** Whether the start of the prompt is on the visible screen: in the input line, or already in the transcript. */
+const screenShowsPrompt = async (ports: SendPorts, lane: string, prompt: string): Promise<boolean> => {
+  const mark = inputLineMarkOf(prompt)
+  return mark !== '' && (await ports.screen(lane)).includes(mark)
+}
+
+/**
+ * After a stall: done when the lane works; `enter` when the prompt is on the screen (an `enter` on an empty input line
+ * does nothing); null when the screen does not show it. `stuck` is a prompt on the screen that `enter` did not start:
+ * sending the file again would append it to the text that waits.
+ */
+const recovered = async (
+  ports: SendPorts,
+  lane: string,
+  prompt: string,
+): Promise<'working' | 'entered' | 'stuck' | null> => {
+  if (await ports.isWorking(lane)) return 'working'
+  if (!(await screenShowsPrompt(ports, lane, prompt))) return null
+  const answer = await ports.enter(lane)
+  return answer.ok && (await ports.awaitWorking(lane)) ? 'entered' : 'stuck'
+}
+
+/**
+ * Sends the prompt text to the lane and makes sure it arrived. A stall or a timeout does not prove the text is lost:
+ * the screen decides. A lane at work is done; a prompt on the screen gets `enter`, and an `enter` the lane does not
+ * answer ends with exit 1, since another send would append to the waiting text; a screen without the prompt sends the
+ * text once more. A second stall, or any other error, ends with exit 1 and a line for Jack.
+ */
+export const sendLanePrompt = async (ports: SendPorts, lane: string, prompt: string): Promise<SendOutcome> => {
+  const first = await ports.prompt(lane, prompt)
+  if (first.ok) return outcome('sent', lane, 'prompt sent.')
+  if (!isStall(first)) return refused(lane, first)
+  const state = await recovered(ports, lane, prompt)
+  if (state === 'working') return outcome('sent', lane, 'prompt sent, the lane works.')
+  if (state === 'entered') return outcome('entered', lane, 'prompt was waiting in the input line, sent with enter.')
+  if (state === 'stuck')
+    return outcome('failed', lane, 'the prompt is on the screen and enter did not start the lane; ask the user.')
+  const second = await ports.prompt(lane, prompt)
+  if (second.ok || (await ports.isWorking(lane))) return outcome('resent', lane, 'prompt sent a second time.')
+  return isStall(second)
+    ? outcome('failed', lane, 'the prompt stalled twice and the lane does not work; ask the user.')
+    : refused(lane, second)
+}

package/src/lane/skill-hint.ts

@@ -0,0 +1,27 @@
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { DEFAULT_SKILL_PREFIX } from '../config/schema'
+import { mainCheckoutOrNull } from '../plans/git'
+import { readSettings } from '../plans/settings'
+import { type Reference, referenceHint, skillCopiesFor, skillDirectoryFor } from '../watch/reference-paths'
+
+/** The directory of the orchestrate skill installed for `root`: the project's copy, else the global one; null without. */
+export const installedSkillDirectory = (root: string, home: string = homedir()): string | null =>
+  skillDirectoryFor(skillCopiesFor(root, home, readSettings([root]).skillPrefix, DEFAULT_SKILL_PREFIX), existsSync)
+
+/**
+ * ` · read <skill directory>/<reference>` for the orchestrate skill installed for `root`; empty without one. A command
+ * that also runs without orchestrate (`jh check`, `jh plan check`, `jh waiting`) stays silent then, so a user who does
+ * not have the skill is not sent to its files; orchestrate's own commands (`jh lane`, the watcher) name the skill
+ * instead (`referenceHint` with no directory).
+ */
+export const installedReferenceHint = (root: string, reference: Reference, home: string = homedir()): string => {
+  const directory = installedSkillDirectory(root, home)
+  return directory === null ? '' : referenceHint(reference, directory)
+}
+
+/** `installedReferenceHint` for the main checkout of the repository `cwd` is in; empty outside a git checkout. */
+export const installedReferenceHintFor = (cwd: string, reference: Reference): string => {
+  const root = mainCheckoutOrNull(cwd)
+  return root === null ? '' : installedReferenceHint(root, reference)
+}

package/src/lane/space-command.ts

@@ -0,0 +1,30 @@
+import { statfsSync } from 'node:fs'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { readSettings } from '../plans/settings'
+import { asksForHelp } from '../preview/options'
+import { freeSpaceLine, LANE_SPACE_USAGE, parseSpaceOptions, spaceVerdict } from './space'
+
+/** The bytes a normal user can still write on the disk that holds `path`. */
+const freeBytesAt = (path: string): number => {
+  const { bavail, bsize } = statfsSync(path)
+  return Number(bavail) * Number(bsize)
+}
+
+/** `jh lane space [--min-gb <n>]`: prints one line; exit 0 with room for a lane, 1 without, or on a wrong line. */
+export const run = (args: string[], cwd: string = process.cwd()): number => {
+  if (asksForHelp(args)) {
+    console.log(LANE_SPACE_USAGE)
+    return 0
+  }
+  try {
+    const root = mainCheckout(cwd)
+    const { minFreeGb } = readSettings([root, worktreeRoot(cwd)])
+    const needed = parseSpaceOptions(args).minFreeGb ?? minFreeGb
+    const verdict = spaceVerdict(freeBytesAt(root), needed)
+    console.log(freeSpaceLine(verdict))
+    return verdict.enough ? 0 : 1
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/lane/space.ts

@@ -0,0 +1,49 @@
+import { CLI_NAME } from '../version/release'
+
+/**
+ * Free space a new lane needs before its dependencies are installed, in gigabytes. Measured 24.10.2026: a first
+ * `bun install` of a worktree writes 2.3 GB when the cache holds none of it, and a warm one about 0.1 GB beside the
+ * 0.2 GB checkout (the packages are hardlinks into the cache); the rest is room to build and test.
+ */
+export const DEFAULT_MIN_FREE_GB = 5
+
+const BYTES_PER_GB = 1024 ** 3
+const COLD_INSTALL_GB = 2.3
+
+/** `minFreeGb` is null where `--min-gb` was left out: the configured threshold then stands. */
+export type SpaceOptions = { minFreeGb: number | null }
+
+export type SpaceVerdict = { enough: boolean; freeGb: number; neededGb: number }
+
+const MIN_GB_OPTION = '--min-gb'
+
+export const LANE_SPACE_USAGE = `usage: ${CLI_NAME} lane space [${MIN_GB_OPTION} <gigabytes>]
+
+Checks that the disk holds enough free space for a new lane before its dependencies are installed; exit 1 and one line
+when it does not. The threshold is lanes.minFreeGb of the config (default ${DEFAULT_MIN_FREE_GB} GB) unless ${MIN_GB_OPTION} says otherwise.`
+
+/** Reads `[--min-gb <n>]`; throws with the usage on anything else. */
+export const parseSpaceOptions = (args: readonly string[]): SpaceOptions => {
+  if (args.length === 0) return { minFreeGb: null }
+  const [option, value, ...rest] = args
+  if (option !== MIN_GB_OPTION || rest.length > 0) throw new Error(LANE_SPACE_USAGE)
+  const minFreeGb = Number(value)
+  if (value === undefined || !Number.isFinite(minFreeGb) || minFreeGb <= 0)
+    throw new Error(`${MIN_GB_OPTION} needs a number of gigabytes above 0\n${LANE_SPACE_USAGE}`)
+  return { minFreeGb }
+}
+
+const roundedDown = (value: number): number => Math.floor(value * 10) / 10
+
+/** Whether `freeBytes` reach the threshold; the free value is rounded down to one decimal. */
+export const spaceVerdict = (freeBytes: number, neededGb: number): SpaceVerdict => ({
+  enough: freeBytes >= neededGb * BYTES_PER_GB,
+  freeGb: roundedDown(freeBytes / BYTES_PER_GB),
+  neededGb,
+})
+
+/** The one line the command prints, for the coordinator to pass on. */
+export const freeSpaceLine = ({ enough, freeGb, neededGb }: SpaceVerdict): string =>
+  enough
+    ? `${freeGb} GB free, ${neededGb} GB needed: room for a lane`
+    : `no lane started: ${freeGb} GB free, ${neededGb} GB needed (a fresh install takes about ${COLD_INSTALL_GB} GB, a lane needs room to build); free space first`

package/src/lane/start-lane-hint.ts

@@ -0,0 +1,18 @@
+import { homedir } from 'node:os'
+import { mainCheckoutOrNull, worktreeRoot } from '../plans/git'
+import { REFERENCE, referenceHint } from '../watch/reference-paths'
+import { installedSkillDirectory } from './skill-hint'
+
+/** `· read <skill directory>/references/start-lane.md`, the line after the output of `jh lane base` and `jh lane prompt`. */
+export const startLaneHintLine = (skillDirectory: string | null): string =>
+  referenceHint(REFERENCE.startLane, skillDirectory).trimStart()
+
+/**
+ * The hint line for a call from the main checkout, where a lane is started from; null from a lane's worktree or outside a
+ * checkout, which have no start to guide. The skill copy is the project's, else the global one.
+ */
+export const startLaneHintFor = (cwd: string): string | null => {
+  const root = mainCheckoutOrNull(cwd)
+  if (root === null || worktreeRoot(cwd) !== root) return null
+  return startLaneHintLine(installedSkillDirectory(root, homedir()))
+}

package/src/plan-contract/base-check-git.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { commitOf, existsOnRef, mainCheckout, worktreeRoot } from '../plans/git'
+import { baseRefOf, boardGlobOf, boardRepoPathOf, readSettings } from '../plans/settings'
+import { baseGapLines, repoPathOf } from './base-check'
+
+/** The boards of the main checkout that link the plan, by its file name, as paths from the repository root. */
+const boardPathsLinking = (root: string, plan: string): string[] => {
+  const settings = readSettings([root])
+  const name = basename(plan)
+  return [...new Bun.Glob(boardGlobOf(settings)).scanSync({ cwd: root })]
+    .map((file) => resolve(root, file))
+    .filter((file) => readFileSync(file, 'utf8').includes(name))
+    .map((file) => boardRepoPathOf(root, settings, file))
+}
+
+/**
+ * The lines that say the plan or a board that links it is not on the base branch (orchestrate § 0), each with its path
+ * from the repository root. None where git cannot judge: outside a repository, without the base ref, or for a file
+ * outside the repository.
+ */
+export const baseGapLinesFor = (file: string, cwd: string): string[] => {
+  try {
+    const root = mainCheckout(cwd)
+    const baseRef = baseRefOf(readSettings([root]))
+    if (commitOf(root, baseRef) === null) return []
+    const plan = repoPathOf(worktreeRoot(cwd), resolve(cwd, file))
+    if (plan === null) return []
+    return baseGapLines(baseRef, [plan, ...boardPathsLinking(root, plan)], (path) => existsOnRef(root, baseRef, path))
+  } catch {
+    return []
+  }
+}

package/src/plan-contract/base-check.ts

@@ -0,0 +1,17 @@
+import { isAbsolute, relative, resolve } from 'node:path'
+
+/** The path of `file` from the repository root, without `..`; null for the root itself or a file outside it. */
+export const repoPathOf = (root: string, file: string): string | null => {
+  const path = relative(resolve(root), resolve(file))
+  return path === '' || path.startsWith('..') || isAbsolute(path) ? null : path
+}
+
+/** One line per file of `paths` that `isOnBase` does not find on `baseRef`: git does not resolve `..` in a tree path. */
+export const baseGapLines = (
+  baseRef: string,
+  paths: readonly string[],
+  isOnBase: (path: string) => boolean,
+): string[] =>
+  paths
+    .filter((path) => !isOnBase(path))
+    .map((path) => `base: ${path} is not on ${baseRef}: ask for its documentation commit (orchestrate § 2 step 0).`)