jackherd 1.26.1 → 1.26.3

package/src/lane/close.ts

@@ -1,15 +1,16 @@
+import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
 import { twoDigits } from '../plan-format/clock'
 import { terminalSafe } from '../plan-format/terminal-text'
 import { errorText } from '../plans/error-text'
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
 import { closedMark, historyDate, withHistoryRow, withLaneClosed } from './close-board'
-import { BOARD_LANE, type ClosableLane, type CloseFacts, closeVerdict } from './close-check'
+import { BOARD_LANE, type ClosableLane, type CloseFacts, closeVerdict, remoteBranchPlanOf } from './close-check'
 import { LANE_CLOSE_COMMAND } from './close-command-line'
 
 /** The facts the check reads, and the herdr workspace the worktree is open in, null when none is. */
 export type CloseSurvey = { facts: CloseFacts; workspace: string | null }
 
-/** What `jh lane close` was asked for; `worktree` comes from the settings and the lane's name, never from a reply. */
+/** What `jh lane close` was asked for; `worktree` comes from the lane's name or from the directory its agent runs in (`worktreeOf`), never from a reply. */
 export type CloseRequest = {
   lane: string
   worktree: string
@@ -27,6 +28,10 @@ export type ClosePorts = {
   exitAgent: (pane: string) => Promise<void>
   /** Removes the worktree without force, then closes the terminal workspace `workspace` names, if any. */
   removeWorktree: (worktree: string, workspace: string | null) => void
+  /** Copies the handover directory of `worktree` to `destination`, a path relative to the main checkout; merges into one that exists. */
+  archiveHandover: (worktree: string, destination: string) => void
+  /** Deletes the branch on origin only while it still points to `head`; throws when it moved or the push fails. */
+  deleteRemoteBranch: (branch: string, head: string) => void
   /** Deletes the branch only while it still points to `head`, the commit the check compared. */
   deleteBranch: (branch: string, head: string) => void
   readBoard: () => string
@@ -58,6 +63,10 @@ const DETACHED_HISTORY_TEXT: Record<PlanLanguage, (lane: string, head: string) =
     `Lane \`${lane}\` cleaned up with \`${LANE_CLOSE_COMMAND}\`: worktree on no branch, head \`${head}\` is on the base branch, worktree removed`,
 }
 
+/** Where the lane's handover directory is kept once its worktree is gone: below the main checkout's own handover directory. */
+export const handoverArchiveOf = (lane: string, now: Date): string =>
+  claudePath(HANDOVER_DIRECTORY, 'closed', `${lane}-${historyDate(now)}`)
+
 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. */
@@ -101,12 +110,44 @@ const removalSteps = (closed: ClosedLane, survey: CloseSurvey, request: CloseReq
       ]
     : []
   return [
+    ...archiveSteps(survey, request, ports),
     ...worktree,
     ...branchSteps(closed.closable, ports),
     { label: boardLabel(facts, request), run: () => ports.writeBoard(closedBoard(ports.readBoard(), closed, request)) },
+    ...remoteBranchSteps(facts, ports),
   ]
 }
 
+/** The handover files are copied before the worktree goes; when the copy fails, the worktree stays. */
+const archiveSteps = ({ facts }: CloseSurvey, request: CloseRequest, ports: ClosePorts): Step[] => {
+  if (!facts.worktreeExists || facts.handoverEntries.length === 0) return []
+  const destination = handoverArchiveOf(request.lane, request.now)
+  return [
+    {
+      label: `archive the handover files of ${request.lane} in ${destination}`,
+      run: () => ports.archiveHandover(request.worktree, destination),
+    },
+  ]
+}
+
+/** Last, so a failed push on origin leaves everything else done: a rerun with `--branch` finishes it. */
+const remoteBranchSteps = (facts: CloseFacts, ports: ClosePorts): Step[] => {
+  const plan = remoteBranchPlanOf(facts)
+  if (plan.kind !== 'delete') return []
+  return [
+    {
+      label: `delete branch ${plan.branch} on origin`,
+      run: () => ports.deleteRemoteBranch(plan.branch, plan.head),
+    },
+  ]
+}
+
+/** The one line saying why a branch on origin stays; null when it goes or there is none. */
+const remoteKeptNote = (facts: CloseFacts): string | null => {
+  const plan = remoteBranchPlanOf(facts)
+  return plan.kind === 'keep' ? `keeping branch ${plan.branch} on origin: ${plan.reason}` : null
+}
+
 /** 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 []
@@ -123,8 +164,8 @@ 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
+const isClosedInFull = ({ worktreeExists, head, boardLane, remoteHead }: CloseFacts): boolean =>
+  !worktreeExists && head === null && boardLane === BOARD_LANE.closed && remoteHead === null
 
 /** 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 => {
@@ -135,6 +176,11 @@ const checked = (survey: CloseSurvey, heading: string, request: CloseRequest, po
   return null
 }
 
+const printKept = (facts: CloseFacts, ports: ClosePorts): void => {
+  const note = remoteKeptNote(facts)
+  if (note !== null) ports.print(note)
+}
+
 /** Runs the steps in order, one line each; at the first failure, names it and every step left undone. */
 const runSteps = async (steps: readonly Step[], ports: ClosePorts): Promise<boolean> => {
   for (const [index, step] of steps.entries()) {
@@ -153,8 +199,8 @@ const runSteps = async (steps: readonly Step[], ports: ClosePorts): Promise<bool
 /**
  * Closes a lane in one run, or refuses with every reason and changes nothing. Checks first (`closeVerdict`); a dry run
  * stops there and prints the steps. Otherwise it ends the lane's agent, checks again, since the agent may have written
- * until it exited, then removes the worktree and its workspace, deletes the local branch, and marks the board last, so
- * the board never records a removal that failed. Exit 0 closed or dry run, 1 refused or failed.
+ * until it exited, then archives the handover files, removes the worktree and its workspace, deletes the local branch, marks the board, and deletes the branch on origin last when it
+ * still holds the merged head (`remoteBranchPlanOf`), so the board never records a removal that failed. Exit 0 closed or dry run, 1 refused or failed.
  */
 export const closeLane = async (request: CloseRequest, ports: ClosePorts): Promise<number> => {
   const first = await ports.survey()
@@ -168,12 +214,14 @@ export const closeLane = async (request: CloseRequest, ports: ClosePorts): Promi
   if (request.dryRun) {
     ports.print(`dry run, nothing changed; closing ${request.lane} would:`)
     for (const step of [...exit, ...removalSteps(closed, first, request, ports)]) ports.print(`  ${step.label}`)
+    printKept(first.facts, ports)
     return 0
   }
   if (!(await runSteps(exit, ports))) return 1
   const settled = exit.length === 0 ? first : await ports.survey()
   const late = checked(settled, `not closing ${request.lane} after its agent exited:`, request, ports)
   if (late === null) return 1
+  printKept(settled.facts, ports)
   if (!(await runSteps(removalSteps(late, settled, request, ports), ports))) return 1
   ports.print(`closed ${request.lane}`)
   return 0

package/src/lane/send-options.ts

@@ -7,8 +7,9 @@ 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
+Refuses (exit 1, nothing sent) while a background agent's view is open on the lane's screen: the input line would
+write to that agent. Otherwise 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. */

package/src/lane/send.ts

@@ -1,3 +1,5 @@
+import { isSubagentViewOpen } from './subagent-view'
+
 /** 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
 
@@ -30,6 +32,9 @@ export type SendOutcome = {
   line: string
 }
 
+const SUBAGENT_VIEW_REFUSAL =
+  'the input line belongs to a background agent whose view is open, so the prompt would go to it and not to the lane; nothing was sent. Close the view (select main in the agent list) or send later.'
+
 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. */
@@ -68,12 +73,14 @@ const recovered = async (
 }
 
 /**
- * Sends the prompt text to the lane and makes sure it arrived. A stall or a timeout does not prove the text is lost:
+ * Sends the prompt text to the lane and makes sure it arrived. An open background agent's view refuses the send first:
+ * the input line would write to that agent. 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> => {
+  if (isSubagentViewOpen(await ports.screen(lane))) return outcome('failed', lane, SUBAGENT_VIEW_REFUSAL)
   const first = await ports.prompt(lane, prompt)
   if (first.ok) return outcome('sent', lane, 'prompt sent.')
   if (!isStall(first)) return refused(lane, first)

package/src/lane/subagent-view.ts

@@ -0,0 +1,21 @@
+/**
+ * A row of Claude Code's agent list that shows the main agent not selected: `◯ main`, the row of the main agent
+ * without the filled `●`. The list sits under the input line; `●` marks the agent whose view is open, so `◯ main`
+ * means a background agent's view is open and the input line writes to that agent. Seen in a real Claude Code pane:
+ * the list reads `◯ main` / `● general-purpose …`. The optional `❯` is the list cursor, which stays on the row while
+ * the list is in selection mode.
+ */
+const MAIN_NOT_SELECTED_ROW = /^\s*(?:❯\s+)?◯ main\s*$/m
+
+/**
+ * The empty input line of an open agent view: `❯ Message @general-purpose…`. It does not depend on how long the agent
+ * list is, which can push the `◯ main` row out of a short screen read; it shows only while the line is empty.
+ */
+const AGENT_INPUT_PLACEHOLDER = /^\s*❯ Message @\S/m
+
+/**
+ * Whether the screen text shows a background agent's view as the open one, so a prompt would go to that agent. A
+ * screen cut so short that neither mark is on it reads as no view: the send then goes ahead as it did before.
+ */
+export const isSubagentViewOpen = (screen: string): boolean =>
+  MAIN_NOT_SELECTED_ROW.test(screen) || AGENT_INPUT_PLACEHOLDER.test(screen)

package/src/lane-prompt/command.ts

@@ -3,6 +3,7 @@ import { dirname, join, relative, resolve } from 'node:path'
 import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
 import { boardFor } from '../plans/board-pick'
 import { mainCheckout, worktreeRoot } from '../plans/git'
+import { settingsPlacingBoardLanes } from '../plans/lane-worktrees'
 import { boardRepoPathOf, readSettings, worktreeOf } from '../plans/settings'
 import { asksForHelp } from '../preview/options'
 import { withAdditions } from './additions'
@@ -54,7 +55,9 @@ const promptSourcesOf = (options: LanePromptOptions, cwd: string): PromptSources
     },
     board: { text: readFileSync(board.file, 'utf8'), directory, path: relative(cwd, board.file) },
     readPlan: readFirstIn([root, checkout]),
-    readLanePlan: readFirstIn([worktreeOf(root, settings, options.lane)]),
+    readLanePlan: readFirstIn([
+      worktreeOf(root, settingsPlacingBoardLanes(root, settings, board.file, options.lane), options.lane),
+    ]),
     root,
   }
 }

package/src/plans/active-tasks.ts

@@ -3,6 +3,7 @@ import { terminalSafe } from '../plan-format/terminal-text'
 import { matchSignals, type OpenPlanTask } from '../task-signals/matcher'
 import type { TaskSignal } from '../task-signals/types'
 import type { TaskPhase } from './current-task'
+import { type LaneWorktrees, laneOfWorktree } from './unlisted-lanes'
 
 /**
  * A task an agent is working on: its index among the phase's checkboxes, who works on it (null while only one agent
@@ -83,8 +84,9 @@ export const freshSignals = (signals: readonly TaskSignal[], lastTickAt: number
   signals.filter(({ source, startedAt }) => source !== 'jh' || lastTickAt === null || startedAt >= lastTickAt)
 
 /** The lane a directory belongs to: the first directory below `worktrees` it lies in; null anywhere else. */
-export const laneOfDirectory = (directory: string, worktrees: string): string | null => {
+export const laneOfDirectory = (directory: string, worktrees: string, placed: LaneWorktrees = {}): string | null => {
   const prefix = worktrees.endsWith(sep) ? worktrees : `${worktrees}${sep}`
   if (!directory.startsWith(prefix)) return null
-  return directory.slice(prefix.length).split(sep)[0] || null
+  const name = directory.slice(prefix.length).split(sep)[0]
+  return name ? laneOfWorktree(name, placed) : null
 }

package/src/plans/activity-read.ts

@@ -3,7 +3,7 @@ import { keptLogEntry } from '../context/session-log'
 import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
 import { isRecord } from '../shared/is-record'
 import { type RunningSubagent, type SubagentActivity, type SubagentLog, subagentLabelOf } from './subagents'
-import { laneDirectoryOf } from './unlisted-lanes'
+import { type LaneWorktrees, laneOfCwd } from './unlisted-lanes'
 
 /** What a running subagent did last, with the name the herd calls it by. */
 export type SubagentLine = { label: string; description: string | null; line: string }
@@ -83,11 +83,12 @@ export const withSubagentLines = (
   running: readonly RunningSubagent[],
   logs: readonly SubagentLog[],
   worktreeDirectory: string,
+  placed: LaneWorktrees = {},
 ): Map<string, LaneSubagents> => {
   const result = new Map<string, LaneSubagents>(lanes)
   const tails = new Map(logs.flatMap((log) => [[labelOfLog(log), log.tail] as const]))
   for (const { label, cwd, description } of running) {
-    const lane = cwd === null ? null : laneDirectoryOf(cwd, worktreeDirectory)
+    const lane = cwd === null ? null : laneOfCwd(cwd, worktreeDirectory, placed)
     const tail = tails.get(label)
     const known = lane === null ? undefined : result.get(lane)
     const line = tail === undefined ? null : activityLineOf(tail)

package/src/plans/command.ts

@@ -10,6 +10,7 @@ import { fetchPullRequests } from './github'
 import { claimOwnTerminal, startExclusive } from './herd-claim'
 import { recallLanes, rememberLanes } from './herd-memory'
 import { publishedKey } from './herd-state'
+import { settingsPlacingBoardLanes } from './lane-worktrees'
 import { runLive } from './live'
 import { parseOptions } from './options'
 import { ENSURE_EXIT } from './plan-panes'
@@ -41,6 +42,7 @@ const printOnceWithNotice = async (source: Source, notice: string | null): Promi
   await printOnce(source)
 }
 
+/** The settings placing each open lane of the board by where its agent runs. */
 /**
  * `jh herd [<board.md>] [--lane <name>] [--once | --ensure]`: a live view of a board's lanes and their plan
  * progress; `--ensure` instead brings back the missing herd panes beside the coordinator and each lane.
@@ -58,7 +60,7 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
     if (options.ensure) {
       const { lines, exitCode } =
         settings.adapter === TERMINAL_ADAPTER.herdr
-          ? ensurePlanPaneRun(root, settings, picked.file)
+          ? ensurePlanPaneRun(root, settingsPlacingBoardLanes(root, settings, picked.file, null), picked.file)
           : { lines: ['the terminal adapter is not herdr: no panes to bring back'], exitCode: ENSURE_EXIT.done }
       for (const line of lines.length > 0 ? lines : ['every herd pane is running']) console.log(line)
       return exitCode

package/src/plans/coordinator-row.ts

@@ -7,6 +7,7 @@ import { fit, visibleLength } from '../terminal/text'
 import { AGENT_STATUS, type LaneAgent } from '../terminal/types'
 import { laneOfDirectory } from './active-tasks'
 import { statusWord } from './symbols'
+import type { LaneWorktrees } from './unlisted-lanes'
 
 export type CoordinatorTask = Pick<TaskSignal, 'text' | 'startedAt'>
 
@@ -43,9 +44,13 @@ export const coordinatorAgentOf = (agents: readonly LaneAgent[], repository: str
  * The coordinator's task: the newest signal reported outside the lanes' worktrees, where the coordinator works (its
  * Claude task list, or `jh task start` from the main checkout); null without one.
  */
-export const coordinatorTaskOf = (signals: readonly TaskSignal[], worktrees: string): TaskSignal | null =>
+export const coordinatorTaskOf = (
+  signals: readonly TaskSignal[],
+  worktrees: string,
+  placed: LaneWorktrees = {},
+): TaskSignal | null =>
   signals
-    .filter(({ cwd }) => laneOfDirectory(cwd, worktrees) === null)
+    .filter(({ cwd }) => laneOfDirectory(cwd, worktrees, placed) === null)
     .reduce<TaskSignal | null>(
       (newest, signal) => (newest && newest.startedAt >= signal.startedAt ? newest : signal),
       null,

package/src/plans/ensure-panes.ts

@@ -21,7 +21,7 @@ import {
   withAgentPanes,
   withForeground,
 } from './plan-panes'
-import { type PlansSettings } from './settings'
+import { type PlansSettings, worktreeOf } from './settings'
 
 const panesWithForeground = (agentPanes: readonly string[]): { panes: PaneState[]; notes: string[] } =>
   withForeground(withAgentPanes(paneListOf(runHerdr(['pane', 'list'])), agentPanes), (pane) =>
@@ -32,7 +32,7 @@ const panesWithForeground = (agentPanes: readonly string[]): { panes: PaneState[
 const lanesOf = (root: string, settings: PlansSettings, boardFile: string) =>
   parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.boardLanguage)
     .filter((lane) => !lane.closed)
-    .map((lane) => ({ name: lane.name, cwd: join(root, settings.worktreeDirectory, lane.name) }))
+    .map((lane) => ({ name: lane.name, cwd: worktreeOf(root, settings, lane.name) }))
     .filter((lane) => existsSync(lane.cwd))
 
 /** Carries out one action; a failure becomes the action's line, so the other views are still tried. */

package/src/plans/lane-discovery.ts

@@ -46,14 +46,53 @@ export const discoverLanes = ({ worktrees, agentNames, sprintLanes }: LaneSource
   return [...lanes, ...helpersOf(lanes, worktrees, agentNames)].sort()
 }
 
+/** What `resolveLaneWorktrees` reads: the agents, the board's lane rows, the existing worktree directory names, the absolute worktree directory. */
+export type ResolutionSources = {
+  agents: readonly AgentPlace[]
+  sprintLanes: readonly string[]
+  worktrees: readonly string[]
+  worktreeDirectory: string
+}
+
+/** An agent named after a board lane that has no worktree of that name, running in a directory of another one. */
+const lacksWorktreeOfItsName = (
+  name: string,
+  directory: string,
+  { sprintLanes, worktrees }: ResolutionSources,
+): boolean => directory !== name && sprintLanes.includes(name) && !worktrees.includes(name)
+
+/**
+ * The worktree of each board lane that has none of its own name, from where its agent runs: lane name to directory name.
+ * A lane resolves when its agents (named like the lane) all run in the one existing worktree below `worktreeDirectory`
+ * and that directory is no board lane's own name and no other lane's choice. Several directories, a directory of another lane or one that does not
+ * exist leave the lane out: the lane stays unwatched and `misplacedLanes` names it.
+ */
+export const resolveLaneWorktrees = (sources: ResolutionSources): Record<string, string> => {
+  const { agents, sprintLanes, worktrees, worktreeDirectory } = sources
+  const directories = new Map<string, Set<string>>()
+  for (const { name, cwd } of agents) {
+    const directory = cwd === null ? null : laneDirectoryOf(cwd, worktreeDirectory)
+    if (directory !== null && lacksWorktreeOfItsName(name, directory, sources))
+      directories.set(name, (directories.get(name) ?? new Set()).add(directory))
+  }
+  const claims = [...directories].flatMap(([lane, found]) => {
+    const [directory] = found
+    const usable = found.size === 1 && worktrees.includes(directory) && !sprintLanes.includes(directory)
+    return usable ? [[lane, directory] as const] : []
+  })
+  return Object.fromEntries(
+    claims.filter(([, directory]) => claims.filter(([, other]) => other === directory).length === 1),
+  )
+}
+
 /** An agent named after a board lane that nobody watches, running in a worktree that carries another name. */
 const isMisplaced = (name: string, worktree: string, sprintLanes: readonly string[], watched: readonly string[]) =>
   worktree !== name && sprintLanes.includes(name) && !watched.includes(name)
 
 /**
- * The board lanes no discovery can find: an agent named after a lane row runs in a worktree whose directory carries
- * another name, as after taking over a worktree started for something else. Every reader derives a lane's worktree
- * from its name (`worktreeOf`), so such a lane is not watched; a lane watched anyway is left out.
+ * The board lanes that stay unwatched: an agent named after a lane row runs in a worktree whose directory carries
+ * another name and `resolveLaneWorktrees` could not tell which one is the lane's (several, another lane's, none). A lane
+ * watched anyway is left out.
  */
 export const misplacedLanes = ({
   agents,

package/src/plans/lane-worktrees.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parseSprintLanes } from '../plan-format'
+import { laneStatusSourceFor } from '../terminal'
+import { worktreeNames } from './git'
+import { type AgentPlace, resolveLaneWorktrees } from './lane-discovery'
+import type { PlansSettings } from './settings'
+
+/** The settings that place the lanes by where their agents run, and the worktree names discovery counts. */
+export type PlacedLanes = { settings: PlansSettings; worktrees: string[] }
+
+/**
+ * Places the lanes whose worktree carries another name (`resolveLaneWorktrees`): `settings` answers `worktreeOf` with
+ * it, and `worktrees` holds the directories that exist plus those lanes' names, which discovery counts as worktrees.
+ */
+export const placeLanes = (
+  root: string,
+  settings: PlansSettings,
+  agents: readonly AgentPlace[],
+  sprintLanes: readonly string[],
+): PlacedLanes => {
+  const worktreeDirectory = join(root, settings.worktreeDirectory)
+  const worktrees = worktreeNames(worktreeDirectory)
+  const laneWorktrees = resolveLaneWorktrees({ agents, sprintLanes, worktrees, worktreeDirectory })
+  return { settings: { ...settings, laneWorktrees }, worktrees: [...worktrees, ...Object.keys(laneWorktrees)] }
+}
+
+const agentsOf = (settings: PlansSettings): AgentPlace[] => {
+  try {
+    return laneStatusSourceFor(settings.adapter).listAgents()
+  } catch {
+    return []
+  }
+}
+
+/** The names of the lanes the board file lists, none when it cannot be read. */
+const boardLaneNamesOf = (settings: PlansSettings, boardFile: string): string[] => {
+  try {
+    return parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.boardLanguage).map(({ name }) => name)
+  } catch {
+    return []
+  }
+}
+
+/** The settings of a command that reads the terminal's agents itself: a terminal that does not answer places no lane. */
+export const settingsPlacingLanes = (root: string, settings: PlansSettings, lanes: readonly string[]): PlansSettings =>
+  placeLanes(root, settings, agentsOf(settings), lanes).settings
+
+/** `settingsPlacingLanes` for the lanes of the board `boardFile` and `lane`: a worktree that is another board lane's is never taken for `lane`. */
+export const settingsPlacingBoardLanes = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  lane: string | null,
+): PlansSettings =>
+  settingsPlacingLanes(root, settings, [...boardLaneNamesOf(settings, boardFile), ...(lane === null ? [] : [lane])])

package/src/plans/sent-files.ts

@@ -3,7 +3,7 @@ import { clockText, DAY_MS } from '../plan-format/clock'
 import { terminalSafe } from '../plan-format/terminal-text'
 import { WAITING_KIND, type WaitingItem } from '../plan-format/waiting'
 import { isRecordId } from './record-id'
-import { laneDirectoryOf } from './unlisted-lanes'
+import { type LaneWorktrees, laneOfCwd } from './unlisted-lanes'
 import { isStillWaiting } from './waiting-window'
 
 /** The record of a send of files to the user, as the kit hook `sent-file` writes it to `.jackherd/sent/`. */
@@ -66,10 +66,14 @@ export const isSentFileRecord = (value: unknown): value is SentFileRecord => {
  * The lane a send belongs to: the worktree of the first file below `worktreeDirectory`, else the worktree of the
  * directory it was sent from; null for the coordinator.
  */
-export const sentLaneOf = ({ files, cwd }: SentFileRecord, worktreeDirectory: string): string | null =>
+export const sentLaneOf = (
+  { files, cwd }: SentFileRecord,
+  worktreeDirectory: string,
+  placed: LaneWorktrees = {},
+): string | null =>
   files
-    .map((file) => (isAddress(file) ? null : laneDirectoryOf(file, worktreeDirectory)))
-    .find((lane) => lane !== null) ?? laneDirectoryOf(cwd, worktreeDirectory)
+    .map((file) => (isAddress(file) ? null : laneOfCwd(file, worktreeDirectory, placed)))
+    .find((lane) => lane !== null) ?? laneOfCwd(cwd, worktreeDirectory, placed)
 
 /** The records without an earlier send of the same first file: an artifact updated each round is one send, the newest. */
 export const latestPerFile = (records: readonly SentFileRecord[]): SentFileRecord[] =>
@@ -83,13 +87,14 @@ export const sentChipsByLane = (
   records: readonly SentFileRecord[],
   worktreeDirectory: string,
   now: number,
+  placed: LaneWorktrees = {},
 ): Map<string | null, SentChip[]> => {
   const lanes = new Map<string | null, SentChip[]>()
   const recent = latestPerFile([...records].sort((left, right) => left.sentAt - right.sentAt))
     .filter(({ sentAt }) => now - sentAt <= DAY_MS)
     .sort((left, right) => right.sentAt - left.sentAt)
   for (const record of recent) {
-    const lane = sentLaneOf(record, worktreeDirectory)
+    const lane = sentLaneOf(record, worktreeDirectory, placed)
     const chips = lanes.get(lane) ?? []
     for (const file of record.files) chips.push({ url: addressOf(file), label: labelOf(file, record.caption) })
     lanes.set(lane, chips.slice(0, SHOWN_PER_LANE))

package/src/plans/settings.ts

@@ -23,6 +23,8 @@ export type PlansSettings = Pick<
   minFreeGb: number
   /** The port `jh lane port` starts from (`lanes.basePort`). */
   basePort: number
+  /** The ignored paths `jh lane close` deletes with a worktree without asking (`lanes.disposable`). */
+  disposablePaths: JackherdConfig['lanes']['disposable']
   /** The command `jh lane dev` starts a lane's dev server with (`lanes.devCommand`); undefined when none is set. */
   devCommand: string | undefined
   /** The shared backend of the lanes (`lanes.backend`); undefined when none is set. */
@@ -43,6 +45,8 @@ export type PlansSettings = Pick<
   sourceLabels: Record<string, string>
   /** The tone of each role in the herd. */
   tones: JackherdConfig['plans']['tones']
+  /** The lanes whose worktree directory carries another name, lane name to directory name (`resolveLaneWorktrees`); none from a config. */
+  laneWorktrees: Readonly<Record<string, string>>
 }
 
 /** What the herd draws of the watcher's sources: from the watcher's state when it keeps them, else from the config. */
@@ -73,6 +77,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   adapter: config.terminal.adapter,
   minFreeGb: config.lanes.minFreeGb ?? DEFAULT_MIN_FREE_GB,
   basePort: config.lanes.basePort ?? DEFAULT_BASE_PORT,
+  disposablePaths: config.lanes.disposable,
   devCommand: config.lanes.devCommand,
   backend: config.lanes.backend,
   fetchIntervalMinutes: config.plans.fetchIntervalMinutes,
@@ -81,6 +86,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   context: config.plans.context,
   ...herdSourceSettingsOf(config.watch.sources.map(watchedSourceOf)),
   tones: config.plans.tones,
+  laneWorktrees: {},
 })
 
 /** The herd's slice of `.jackherd/config.json`, validated by the shared schema. */
@@ -100,8 +106,13 @@ export const boardRepoPathOf = (root: string, settings: PlansSettings, file: str
   return path.startsWith(prefix) ? path.slice(prefix.length).split('/').slice(1).join('/') : path
 }
 
+/** The worktree of a lane: its adopted directory, else the one carrying its name. The one place a lane name becomes a path. */
 export const worktreeOf = (root: string, settings: PlansSettings, laneName: string): string =>
-  join(root, settings.worktreeDirectory, laneName)
+  join(
+    root,
+    settings.worktreeDirectory,
+    Object.hasOwn(settings.laneWorktrees, laneName) ? settings.laneWorktrees[laneName] : laneName,
+  )
 
 /** The remote whose base branch the view reads plans and the board from. */
 export const BASE_REMOTE = 'origin'

package/src/plans/snapshot.ts

@@ -55,6 +55,7 @@ import {
 } from './lane-plans'
 import { laneSummary } from './lane-summary'
 import { boardRowTexts, laneTicketsOf, withoutTicketLinks } from './lane-tickets'
+import { placeLanes } from './lane-worktrees'
 import type { LaneView } from './layout'
 import { extractLinkChips } from './link-chips'
 import type { Options } from './options'
@@ -368,7 +369,9 @@ const laneView = async (
         phases: phasesByHref,
         activity,
         guesses: taskSignalsOf(Object.values(phasesByHref).flat(), workText(sources, lane.name, agent), now),
-        reported: sources.signals.filter(({ cwd }) => laneOfDirectory(cwd, sources.worktrees) === lane.name),
+        reported: sources.signals.filter(
+          ({ cwd }) => laneOfDirectory(cwd, sources.worktrees, sources.source.settings.laneWorktrees) === lane.name,
+        ),
         subagents: laneSubagents?.phaseRuns ?? [],
         subagentTasks: laneSubagents?.taskDescriptions ?? [],
         phaselessReviews: laneSubagents?.phaselessReviews ?? [],
@@ -446,7 +449,7 @@ const readSignals = async (
 const coordinatorOf = (sources: LaneSources): { view: CoordinatorView; shown: TaskSignal | null } | null => {
   const agent = coordinatorAgentOf(sources.agents, basename(sources.source.root))
   if (!agent) return null
-  const shown = coordinatorTaskOf(sources.signals, sources.worktrees)
+  const shown = coordinatorTaskOf(sources.signals, sources.worktrees, sources.source.settings.laneWorktrees)
   const report = contextOfAgent(agent, sources.readLog, coordinatorSettings(sources.source.settings.context))
   const view = {
     name: agent.name,
@@ -463,7 +466,7 @@ const unplacedOf = (sources: LaneSources, lanes: readonly SprintLane[], onlyLane
   if (onlyLane) return []
   const listed = new Set(lanes.map((lane) => lane.name))
   const rest = sources.signals.filter(({ cwd }) => {
-    const lane = laneOfDirectory(cwd, sources.worktrees)
+    const lane = laneOfDirectory(cwd, sources.worktrees, sources.source.settings.laneWorktrees)
     return lane === null || !listed.has(lane)
   })
   return assignSignals([], rest).unplanned
@@ -486,7 +489,10 @@ const readSubagents = async (
 ): Promise<Map<string, LaneSubagents>> => {
   try {
     if (read) return read(root, worktrees)
-    return await readSubagentActivitySliced(subagentSourceOf(root, worktrees, settings.skillPrefix), gate.pass)
+    return await readSubagentActivitySliced(
+      subagentSourceOf(root, worktrees, settings.skillPrefix, settings.laneWorktrees),
+      gate.pass,
+    )
   } catch {
     return new Map()
   }
@@ -586,8 +592,15 @@ const laneSetOf = async (
   const { base, baseCommit, board, sprintDirectory, worktrees, cache, gate } = context
   await gate.pass()
   const { agents, errors } = await readAgents(source)
+  const { settings } = placeLanes(
+    source.root,
+    source.settings,
+    agents,
+    board.lanes.map((lane) => lane.name),
+  )
+  const placedSource = { ...source, settings }
   const isWanted = ({ name }: { name: string }) => !source.options.lane || name === source.options.lane
-  const subagents = await readSubagents(source, worktrees, gate)
+  const subagents = await readSubagents(placedSource, worktrees, gate)
   const signals = await readSignals(source, { worktrees, now, gate, cache })
   const planPulls = planPullRequests([...pullRequests.byBranch.values()].flat(), source.settings.planDirectory)
   const headCommits = planPulls.length > 0 ? await refCommits(source.root, PULL_HEAD_NAMESPACE) : new Map()
@@ -596,7 +609,7 @@ const laneSetOf = async (
     lanes: board.lanes.filter(isWanted),
     unlisted: unlistedLanes(agents, listed, worktrees, new Set(subagents.keys())).filter(isWanted),
     sources: {
-      source,
+      source: placedSource,
       base,
       sprintDirectory,
       agents,
@@ -763,7 +776,7 @@ export const loadSnapshot = async (
     waitingItemsOf(liveBoard, settings.boardLanguage, waitingRecords, now),
     sourceSettings.sourceLabels,
   )
-  const sentChips = sentChipsByLane(waitingRecords.sent, worktrees, now)
+  const sentChips = sentChipsByLane(waitingRecords.sent, worktrees, now, laneSet.sources.source.settings.laneWorktrees)
   const notice = fallbacks.length > 0 ? fallbackNotice(fallbacks, baseRef, refExists(root, baseRef)) : null
   const unknownLaneTitle =
     options.lane && results.length === 0 ? boardTexts(settings.board.term).laneNotListed(options.lane) : null
@@ -776,7 +789,9 @@ export const loadSnapshot = async (
     sprintDirectory,
     sentChips,
     restNoteOf: (lane) =>
-      restNote(readLaneReport(laneReportPath(worktreeOf(root, settings, lane), lane))?.text ?? null),
+      restNote(
+        readLaneReport(laneReportPath(worktreeOf(root, laneSet.sources.source.settings, lane), lane))?.text ?? null,
+      ),
   })
   await gate.pass()
   const planned = await plannedOf(source, results, {