jackherd 1.16.0 → 1.17.0

package/src/lane/close-check.ts

@@ -9,11 +9,17 @@ export const BOARD_LANE = { open: 'open', closed: 'closed', missing: 'missing' }
 
 export type BoardLane = (typeof BOARD_LANE)[keyof typeof BOARD_LANE]
 
-/** The lane's branch, the head the check compared, and its merged pull request once nothing stands against closing it. */
-export type ClosableLane = { branch: string; head: string; pullRequest: MergedPullRequest }
+/**
+ * What the check proved once nothing stands against closing: a lane on a branch (its branch, the head the check
+ * compared, null when the branch is gone already, and its merged pull request), or a worktree on no branch whose head
+ * stands on the base branch.
+ */
+export type ClosableLane =
+  | { kind: 'branch'; branch: string; head: string | null; pullRequest: MergedPullRequest }
+  | { kind: 'detached'; head: string }
 
 /** Every reason against closing, or the lane ready to close; the second only when the first is empty. */
-export type CloseVerdict = { kind: 'refused'; refusals: string[] } | ({ kind: 'closable' } & ClosableLane)
+export type CloseVerdict = { kind: 'refused'; refusals: string[] } | { kind: 'closable'; lane: ClosableLane }
 
 /** One entry of `git status --porcelain`: its two status letters (`!!` ignored, `??` untracked) and its path. */
 export type StatusEntry = { code: string; path: string }
@@ -28,14 +34,19 @@ export type CloseFacts = {
   lane: string
   boardLane: BoardLane
   worktreeExists: boolean
+  /** The worktree's branch; without a worktree the branch `--branch` names, null when none was named. */
   branch: string | null
-  /** The commit the worktree's branch points to, as `git worktree list` reports it; null without a worktree. */
+  /** The commit the worktree or, without one, the named branch points to; null when neither exists. */
   head: string | null
   pullRequest: MergedPullRequest | null
   treeDiff: readonly string[]
   status: readonly StatusEntry[]
   setupFiles: readonly string[]
   handoverEntries: readonly string[]
+  /** Whether the head of a worktree on no branch is an ancestor of the base branch on the remote. */
+  headOnBase: boolean
+  /** The staged paths of a worktree on no branch that the base branch on the remote holds with the same content. */
+  baseHeldPaths: readonly string[]
   /** The agent named after the lane whose directory lies in the worktree, with its pane. */
   agent: { pane: string; status: string } | null
   /** The panes of other agents whose directory lies in the worktree: a helper, or a session without the lane's name. */
@@ -64,6 +75,10 @@ const BUILD_OUTPUT = [
 const BUILD_OUTPUT_DIRECTORY_ENTRIES = [new Bun.Glob('packages/*/bin')]
 const HANDOVER = claudePath(HANDOVER_DIRECTORY)
 
+/** A change that is staged and nothing more: the worktree file equals the index. */
+const isStagedOnly = (code: string): boolean =>
+  code[0] !== ' ' && code[0] !== '?' && code[0] !== IGNORED_CODE[0] && code[1] === ' '
+
 const withoutSlashes = (path: string): string => path.replace(/^\/+|\/+$/g, '')
 
 const isHandoverDirectory = (path: string): boolean => withoutSlashes(path) === HANDOVER
@@ -121,23 +136,33 @@ export const isBuildOutput = (path: string): boolean => {
  * The paths removing the worktree would delete for good: every tracked change and untracked file, and every ignored
  * path except dependencies (`node_modules` at any depth), the setup files, build output and the handover directory.
  */
-export const lostPathsOf = (status: readonly StatusEntry[], setupFiles: readonly string[]): string[] => {
+export const lostPathsOf = (
+  status: readonly StatusEntry[],
+  setupFiles: readonly string[],
+  baseHeldPaths: readonly string[] = [],
+): string[] => {
   const kept = (path: string) =>
     isDependencyPath(path) || isSetupFile(path, setupFiles) || isBuildOutput(path) || isHandoverDirectory(path)
-  return status.filter(({ code, path }) => code !== IGNORED_CODE || !kept(path)).map(({ path }) => path)
+  const held = ({ code, path }: StatusEntry) => isStagedOnly(code) && baseHeldPaths.includes(path)
+  return status
+    .filter((entry) => (entry.code !== IGNORED_CODE || !kept(entry.path)) && !held(entry))
+    .map(({ path }) => path)
 }
 
 /** The lost paths and the entries of the handover directory, each once: the directory stands for all of them. */
-const deletedPathsOf = ({ status, setupFiles, handoverEntries }: CloseFacts): string[] => [
-  ...new Set([...lostPathsOf(status, setupFiles), ...handoverEntries]),
+const deletedPathsOf = ({ status, setupFiles, handoverEntries, baseHeldPaths }: CloseFacts): string[] => [
+  ...new Set([...lostPathsOf(status, setupFiles, baseHeldPaths), ...handoverEntries]),
 ]
 
 /** A lane the board marks cleaned up already may still have its worktree left over; only a lane it never named is refused. */
 const boardRefusals = ({ lane, boardLane }: CloseFacts): string[] =>
   boardLane === BOARD_LANE.missing ? [`the board has no row for lane ${lane}`] : []
 
-const mergeRefusals = ({ lane, branch, pullRequest, treeDiff }: CloseFacts): string[] => {
-  if (branch === null) return [`the worktree of ${lane} is on no branch`]
+const detachedRefusals = ({ lane, headOnBase }: CloseFacts): string[] =>
+  headOnBase ? [] : [`the worktree of ${lane} is on no branch and its head is not on the base branch`]
+
+const mergeRefusals = ({ branch, pullRequest, treeDiff }: CloseFacts): string[] => {
+  if (branch === null) return []
   if (pullRequest === null) return [`branch ${branch} has no merged pull request`]
   return treeDiff.map(
     (path) => `branch ${branch} differs from the merge of #${pullRequest.number} (${pullRequest.mergeCommit}): ${path}`,
@@ -162,11 +187,17 @@ const lockRefusals = ({ lane, locked }: CloseFacts): string[] =>
  * on the worktree (a Claude Code session may still hold it).
  */
 export const closeRefusals = (facts: CloseFacts): string[] => {
-  if (!facts.worktreeExists) return [...boardRefusals(facts), `lane ${facts.lane} has no worktree`]
+  if (!facts.worktreeExists)
+    return [
+      ...boardRefusals(facts),
+      ...(facts.branch === null
+        ? [`lane ${facts.lane} has no worktree; name its branch with --branch to finish closing it`]
+        : mergeRefusals(facts)),
+    ]
   if (facts.runsInside) return [`run it outside the worktree of ${facts.lane}, which it would remove`]
   return [
     ...boardRefusals(facts),
-    ...mergeRefusals(facts),
+    ...(facts.branch === null ? detachedRefusals(facts) : mergeRefusals(facts)),
     ...deletedPathsOf(facts).map((path) => `removing the worktree deletes ${path}`),
     ...agentRefusals(facts),
     ...lockRefusals(facts),
@@ -176,8 +207,11 @@ export const closeRefusals = (facts: CloseFacts): string[] => {
 /** `closeRefusals` as a verdict that carries the branch and pull request it proved, so a caller needs no second check. */
 export const closeVerdict = (facts: CloseFacts): CloseVerdict => {
   const refusals = closeRefusals(facts)
+  if (refusals.length > 0) return { kind: 'refused', refusals }
   const { branch, head, pullRequest } = facts
-  if (refusals.length > 0 || branch === null || head === null || pullRequest === null)
-    return { kind: 'refused', refusals }
-  return { kind: 'closable', branch, head, pullRequest }
+  if (branch !== null && pullRequest !== null)
+    return { kind: 'closable', lane: { kind: 'branch', branch, head, pullRequest } }
+  return head === null
+    ? { kind: 'refused', refusals: [`the worktree of ${facts.lane} has no head to compare`] }
+    : { kind: 'closable', lane: { kind: 'detached', head } }
 }

package/src/lane/close-command.ts

@@ -13,9 +13,17 @@ import { runGh } from '../watch/gh'
 import { parseWatchedPullRequests, WATCHED_PULL_REQUEST_FIELDS } from '../watch/pull-requests'
 import { type ClosePorts, type CloseRequest, type CloseSurvey, closeLane } from './close'
 import { boardLaneOf } from './close-board'
-import { type CloseFacts, type MergedPullRequest, statusEntriesOf } from './close-check'
+import { type CloseFacts, type MergedPullRequest, type StatusEntry, statusEntriesOf } from './close-check'
 import { type CloseOptions, LANE_CLOSE_USAGE, parseCloseOptions } from './close-options'
-import { agentFactsOf, mergedPullRequestOf, openWorkspaceOf, type WorktreeEntry, worktreeEntryOf } from './close-survey'
+import {
+  agentFactsOf,
+  baseHeldPathsOf,
+  mergedPullRequestOf,
+  openWorkspaceOf,
+  stagedPlanPathsOf,
+  type WorktreeEntry,
+  worktreeEntryOf,
+} from './close-survey'
 
 /** Where the command runs and what it acts on, located once. */
 type CloseContext = { root: string; cwd: string; settings: PlansSettings; worktree: string; boardFile: string }
@@ -23,7 +31,16 @@ type CloseContext = { root: string; cwd: string; settings: PlansSettings; worktr
 /** The facts that only a worktree git lists has. */
 type WorktreeFacts = Pick<
   CloseFacts,
-  'worktreeExists' | 'branch' | 'head' | 'pullRequest' | 'treeDiff' | 'status' | 'handoverEntries' | 'locked'
+  | 'worktreeExists'
+  | 'branch'
+  | 'head'
+  | 'pullRequest'
+  | 'treeDiff'
+  | 'status'
+  | 'handoverEntries'
+  | 'headOnBase'
+  | 'baseHeldPaths'
+  | 'locked'
 >
 
 /** The file the lane setup copies into every new worktree, in `.gitignore` syntax. */
@@ -51,6 +68,8 @@ const ABSENT_WORKTREE: WorktreeFacts = {
   treeDiff: [],
   status: [],
   handoverEntries: [],
+  headOnBase: false,
+  baseHeldPaths: [],
   locked: null,
 }
 
@@ -97,30 +116,71 @@ const mergedPullRequestOn = async (context: CloseContext, branch: string): Promi
   return mergedPullRequestOf(parseWatchedPullRequests(answer.stdout), branch)
 }
 
+const remoteBase = (context: CloseContext): string => `origin/${context.settings.baseBranch}`
+
+/** Whether `head` is an ancestor of the base branch on the remote; false for an answer other than yes. */
+const isOnBase = (context: CloseContext, head: string): boolean =>
+  Bun.spawnSync(['git', '-C', context.root, 'merge-base', '--is-ancestor', head, remoteBase(context)]).exitCode === 0
+
+/** The staged plan changes of the worktree that the base branch on the remote holds as they are staged. */
+const baseHeldPathsIn = (context: CloseContext, status: readonly StatusEntry[]): string[] => {
+  const candidates = stagedPlanPathsOf(status, context.settings.planDirectory)
+  if (candidates.length === 0) return []
+  const differing = linesOf(
+    runGit(context.worktree, ['diff', '--cached', '--name-only', remoteBase(context), '--', ...candidates]),
+  )
+  return baseHeldPathsOf(candidates, differing)
+}
+
 /** Branch, merged pull request, tree difference, status, handover files and lock of the worktree git lists for the lane. */
 const worktreeFactsOf = async (context: CloseContext, entry: WorktreeEntry): Promise<WorktreeFacts> => {
   const pullRequest = entry.branch === null ? null : await mergedPullRequestOn(context, entry.branch)
+  const status = statusEntriesOf(
+    runGit(context.worktree, ['status', '--porcelain=v1', '-z', IGNORED_MATCHING, ALL_UNTRACKED]),
+  )
+  const detached = entry.branch === null
   return {
     worktreeExists: true,
     branch: entry.branch,
     head: entry.head,
     pullRequest,
     treeDiff: pullRequest === null ? [] : treeDiffOf(context, entry.head, pullRequest.mergeCommit),
-    status: statusEntriesOf(
-      runGit(context.worktree, ['status', '--porcelain=v1', '-z', IGNORED_MATCHING, ALL_UNTRACKED]),
-    ),
+    status,
     handoverEntries: handoverEntriesOf(context.worktree),
+    headOnBase: detached && isOnBase(context, entry.head),
+    baseHeldPaths: detached ? baseHeldPathsIn(context, status) : [],
     locked: entry.locked,
   }
 }
 
+/** The commit the local branch points to; null when there is no such branch. */
+const branchHeadOf = (context: CloseContext, branch: string): string | null => {
+  const result = Bun.spawnSync(
+    ['git', '-C', context.root, 'rev-parse', '--verify', '--quiet', `${BRANCH_REF}${branch}^{commit}`],
+    { stdout: 'pipe' },
+  )
+  return result.exitCode === 0 ? result.stdout.toString().trim() : null
+}
+
+/** What survives of a lane whose worktree is gone: the branch `--branch` names, if it is still there, and its merged pull request. */
+const branchFactsOf = async (context: CloseContext, branch: string): Promise<WorktreeFacts> => {
+  const head = branchHeadOf(context, branch)
+  const pullRequest = await mergedPullRequestOn(context, branch)
+  const treeDiff = head === null || pullRequest === null ? [] : treeDiffOf(context, head, pullRequest.mergeCommit)
+  return { ...ABSENT_WORKTREE, branch, head, pullRequest, treeDiff }
+}
+
 const workspaceOf = (context: CloseContext): string | null =>
   context.settings.adapter === TERMINAL_ADAPTER.herdr
     ? openWorkspaceOf(runHerdr(['worktree', 'list', '--cwd', context.root]), context.worktree)
     : null
 
+/** The facts of a lane without a worktree: only what survives in the branch `--branch` names, if one was named. */
+const absentWorktreeFactsOf = (context: CloseContext, branch: string | null): Promise<WorktreeFacts> | WorktreeFacts =>
+  branch === null ? ABSENT_WORKTREE : branchFactsOf(context, branch)
+
 /** What git, GitHub and the terminal say about the lane now; throws when one of them cannot be asked. */
-const surveyOf = async (lane: string, context: CloseContext): Promise<CloseSurvey> => {
+const surveyOf = async (lane: string, branch: string | null, context: CloseContext): Promise<CloseSurvey> => {
   const entry = worktreeEntryOf(runGit(context.root, ['worktree', 'list', '--porcelain']), context.worktree)
   const present = entry !== null && existsSync(context.worktree)
   const facts: CloseFacts = {
@@ -129,7 +189,7 @@ const surveyOf = async (lane: string, context: CloseContext): Promise<CloseSurve
     setupFiles: setupFilesOf(context.root),
     ...agentFactsOf(laneStatusSourceFor(context.settings.adapter).listAgents(), lane, context.worktree),
     runsInside: realPath(worktreeRoot(context.cwd)) === realPath(context.worktree),
-    ...(present ? await worktreeFactsOf(context, entry) : ABSENT_WORKTREE),
+    ...(present ? await worktreeFactsOf(context, entry) : await absentWorktreeFactsOf(context, branch)),
   }
   return { facts, workspace: present ? workspaceOf(context) : null }
 }
@@ -166,8 +226,8 @@ const deleteBranchIn =
     runGit(context.root, ['update-ref', '-d', `${BRANCH_REF}${branch}`, head])
   }
 
-const portsFor = (lane: string, context: CloseContext): ClosePorts => ({
-  survey: () => surveyOf(lane, context),
+const portsFor = (lane: string, branch: string | null, context: CloseContext): ClosePorts => ({
+  survey: () => surveyOf(lane, branch, context),
   exitAgent: exitAgentIn(context),
   removeWorktree: removeWorktreeIn(context),
   deleteBranch: deleteBranchIn(context),
@@ -209,7 +269,7 @@ export const run = async (args: string[], cwd: string = process.cwd()): Promise<
       now: new Date(),
       language: context.settings.planLanguage,
     }
-    return await closeLane(request, portsFor(options.lane, context))
+    return await closeLane(request, portsFor(options.lane, options.branch, context))
   } catch (error) {
     console.error(terminalSafe(error instanceof Error ? error.message : String(error)))
     return 1

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