jackherd 1.26.0 → 1.26.2

package/src/plans/lane-discovery.ts

@@ -1,4 +1,5 @@
 import { terminalSafe } from '../plan-format/terminal-text'
+import { laneDirectoryOf } from './unlisted-lanes'
 
 /** What the watcher finds a lane by: the worktree directories, the herdr agent names, the sprint's lane rows. */
 export type LaneSources = {
@@ -9,6 +10,20 @@ export type LaneSources = {
 
 export type LaneSetChange = { added: string[]; removed: string[] }
 
+/** A herdr agent by its name and the directory it runs in, null when herdr gives none. */
+export type AgentPlace = { name: string; cwd: string | null }
+
+/** What `misplacedLanes` compares: the agents, the board's lane rows, the lanes watched now, the absolute worktree directory. */
+export type MisplacementSources = {
+  agents: readonly AgentPlace[]
+  sprintLanes: readonly string[]
+  watched: readonly string[]
+  worktreeDirectory: string
+}
+
+/** A board lane whose agent runs in a worktree named otherwise, `worktree` being that directory's name. */
+export type MisplacedLane = { lane: string; worktree: string }
+
 /**
  * The helper agents of the lanes: an agent named `<lane>-<purpose>` that a lane started in a pane of its own, such as
  * for a measurement. A name that is a worktree of its own is that lane, not a helper. The prefix only decides whether
@@ -31,6 +46,78 @@ 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 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,
+  sprintLanes,
+  watched,
+  worktreeDirectory,
+}: MisplacementSources): MisplacedLane[] => {
+  const byLane = new Map<string, string>()
+  for (const { name, cwd } of agents) {
+    const worktree = cwd === null ? null : laneDirectoryOf(cwd, worktreeDirectory)
+    if (worktree !== null && isMisplaced(name, worktree, sprintLanes, watched) && !byLane.has(name))
+      byLane.set(name, worktree)
+  }
+  return [...byLane]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([lane, worktree]) => ({ lane, worktree }))
+}
+
+/** `lane <name> not watched: its agent runs in worktree <dir>, not <name>`, one line per lane. */
+export const misplacedLaneLines = (lanes: readonly MisplacedLane[]): string[] =>
+  lanes.map(({ lane, worktree }) => {
+    const name = terminalSafe(lane)
+    return `lane ${name} not watched: its agent runs in worktree ${terminalSafe(worktree)}, not ${name}`
+  })
+
 /** The lanes that joined and left between two discoveries, each sorted. */
 export const laneSetChange = (previous: readonly string[], next: readonly string[]): LaneSetChange => ({
   added: next.filter((lane) => !previous.includes(lane)).sort(),

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

@@ -43,6 +43,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. */
@@ -81,6 +83,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 +103,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, {

package/src/plans/subagents-read.ts

@@ -14,6 +14,7 @@ import {
   type SubagentLog,
   subagentsByLane,
 } from './subagents'
+import type { LaneWorktrees } from './unlisted-lanes'
 
 export type SubagentSource = {
   projects: string
@@ -23,16 +24,24 @@ export type SubagentSource = {
   approvalsRoot: string
   /** The absolute worktree directory. */
   worktreeDirectory: string
+  /** The lanes placed in worktrees of another name (`PlansSettings.laneWorktrees`). */
+  laneWorktrees?: LaneWorktrees
   /** The project's `skillPrefix`, which its copies of the review agents carry; without it only the default one counts. */
   skillPrefix?: string
 }
 
 /** The source of the main checkout `root`: Claude Code's own session logs, the gate's requests in the checkout itself. */
-export const subagentSourceOf = (root: string, worktreeDirectory: string, skillPrefix?: string): SubagentSource => ({
+export const subagentSourceOf = (
+  root: string,
+  worktreeDirectory: string,
+  skillPrefix?: string,
+  laneWorktrees?: LaneWorktrees,
+): SubagentSource => ({
   projects: defaultProjectsDirectory(),
   root,
   approvalsRoot: root,
   worktreeDirectory,
+  laneWorktrees,
   skillPrefix,
 })
 
@@ -181,5 +190,11 @@ export const readSubagentActivitySliced = async (
     logs.push(...logsInSession(directory, now))
   }
   const running = runningOf(logs, source, now)
-  return withSubagentLines(subagentsByLane(running, source.worktreeDirectory), running, logs, source.worktreeDirectory)
+  return withSubagentLines(
+    subagentsByLane(running, source.worktreeDirectory, source.laneWorktrees),
+    running,
+    logs,
+    source.worktreeDirectory,
+    source.laneWorktrees,
+  )
 }

package/src/plans/subagents.ts

@@ -7,7 +7,7 @@ import { AGENT_STATUS, type AgentStatus } from '../terminal/types'
 import { activityTextOf } from './current-task'
 import { type PhaselessReview, type SubagentPhaseRun, subagentPhaseRunOf } from './subagent-phases'
 import type { DescribedSubagent } from './subagent-tasks'
-import { laneDirectoryOf } from './unlisted-lanes'
+import { type LaneWorktrees, laneOfCwd } from './unlisted-lanes'
 
 /** What the log files of one subagent say: its id, its `meta.json` as parsed, when the log was written, its last lines. */
 export type SubagentLog = { id: string; meta: unknown; modifiedAt: number; tail: readonly string[] }
@@ -156,11 +156,12 @@ const phaselessReviewOf = ({ phaseRun, description }: RunningSubagent): Phaseles
 export const subagentsByLane = (
   running: readonly RunningSubagent[],
   worktreeDirectory: string,
+  placed: LaneWorktrees = {},
 ): Map<string, SubagentActivity> => {
   const lanes = new Map<string, SubagentActivity>()
   for (const subagent of running) {
     const { cwd, status, description, activity } = subagent
-    const lane = cwd === null ? null : laneDirectoryOf(cwd, worktreeDirectory)
+    const lane = cwd === null ? null : laneOfCwd(cwd, worktreeDirectory, placed)
     if (lane === null) continue
     const known = lanes.get(lane)
     const runs = namedRunOf(subagent)

package/src/plans/unlisted-lanes.ts

@@ -14,6 +14,19 @@ export const laneDirectoryOf = (cwd: string, worktreeDirectory: string): string
   return below.split(sep)[0]
 }
 
+/** The lanes whose worktree directory carries another name, lane name to directory name (`PlansSettings.laneWorktrees`). */
+export type LaneWorktrees = Readonly<Record<string, string>>
+
+/** The inverse of `worktreeOf`'s naming: the lane that works in the worktree directory `directory`, which is `directory` itself unless a lane was placed there. */
+export const laneOfWorktree = (directory: string, placed: LaneWorktrees): string =>
+  Object.entries(placed).find(([, placedDirectory]) => placedDirectory === directory)?.[0] ?? directory
+
+/** The lane an agent or a record belongs to by the directory `cwd` lies in: `laneDirectoryOf`, read through the lanes placed in other worktrees. */
+export const laneOfCwd = (cwd: string, worktreeDirectory: string, placed: LaneWorktrees = {}): string | null => {
+  const directory = laneDirectoryOf(cwd, worktreeDirectory)
+  return directory === null ? null : laneOfWorktree(directory, placed)
+}
+
 /** An unlisted lane as a sprint lane: its name and nothing else, no port, no steps. */
 export const unlistedSprintLane = (name: string): SprintLane => ({ name, port: null, steps: [], closed: false })
 

package/src/resume/command.ts

@@ -174,7 +174,7 @@ const awaitCoordinator = async (ports: ResumePorts, decision: Resume): Promise<s
 const resumeLanes = async (ports: ResumePorts, decision: Resume, worktreeDirectory: string, text: string) => {
   const recipients = decision.interrupted.map((name) => ({
     name,
-    directory: join(decision.root, worktreeDirectory, name),
+    directory: join(decision.root, worktreeDirectory, decision.laneWorktrees[name] ?? name),
   }))
   const search = await awaitTargets(ports, decision.root, recipients, RESUME_LIMITS.lanes, (target) =>
     sendTo(ports, decision.root, target, text),

package/src/resume/coordinator-read.ts

@@ -6,8 +6,9 @@ import { parseSprintLanes } from '../plan-format'
 import { terminalSafe } from '../plan-format/terminal-text'
 import { boardFor, foundLanesOf } from '../plans/board-pick'
 import { errorText } from '../plans/error-text'
-import { mainCheckout, worktreeNames } from '../plans/git'
+import { mainCheckout } from '../plans/git'
 import { discoverLanes } from '../plans/lane-discovery'
+import { placeLanes } from '../plans/lane-worktrees'
 import { type PlansSettings, readSettings, worktreeOf } from '../plans/settings'
 import { recordWaitingItems } from '../plans/waiting-records'
 import { readApprovalRequests } from '../watch/approvals'
@@ -15,8 +16,8 @@ import { readGithub } from '../watch/github-read'
 import { listAgents } from '../watch/herdr'
 import { laneReportPath, readLaneReport, reportMtime } from '../watch/lane-report-file'
 import { branchOf } from '../watch/lane-sources'
-import type { HerdrAgent } from '../watch/lane-watch'
-import { REFERENCE, referenceLine } from '../watch/reference-paths'
+import { agentPlacesOf, type HerdrAgent, misplacedLinesOf } from '../watch/lane-watch'
+import { annotateEach, REFERENCE, referenceLine } from '../watch/reference-paths'
 import {
   type CoordinatorStateInput,
   coordinatorStateLines,
@@ -99,21 +100,24 @@ const readPullRequestsSafely = async (
   }
 }
 
-const lanesOf = ({ root, settings }: Place, board: string | null, agents: readonly HerdrAgent[] | null): string[] =>
-  discoverLanes({
-    worktrees: worktreeNames(join(root, settings.worktreeDirectory)),
-    agentNames: (agents ?? []).flatMap((agent) => agent.name ?? []),
-    sprintLanes: board === null ? [] : parseSprintLanes(board, settings.boardLanguage).map((lane) => lane.name),
-  })
+const sprintLanesOf = ({ settings }: Place, board: string | null): string[] =>
+  board === null ? [] : parseSprintLanes(board, settings.boardLanguage).map((lane) => lane.name)
+
+const lanesOf = (sprintLanes: string[], agents: readonly HerdrAgent[] | null, worktrees: readonly string[]): string[] =>
+  discoverLanes({ worktrees, agentNames: (agents ?? []).flatMap((agent) => agent.name ?? []), sprintLanes })
 
 /** `jh resume --coordinator`: prints what a cleared coordinator takes up, then the reference on it. Reads only. */
 export const printCoordinatorState = async (boardPath: string | null): Promise<void> => {
-  const place = placeOf(boardPath)
-  const { root, settings, boardFile } = place
+  const found = placeOf(boardPath)
+  const { root, boardFile } = found
   const now = Date.now()
   const board = readBoard(boardFile)
   const agents = readAgents()
-  const lanes = lanesOf(place, board, agents)
+  const sprintLanes = sprintLanesOf(found, board)
+  const placed = placeLanes(root, found.settings, agentPlacesOf(agents ?? []), sprintLanes)
+  const place = { ...found, settings: placed.settings }
+  const { settings } = place
+  const lanes = lanesOf(sprintLanes, agents, placed.worktrees)
   const lines = coordinatorStateLines({
     boardPath: relative(root, boardFile),
     board,
@@ -125,8 +129,14 @@ export const printCoordinatorState = async (boardPath: string | null): Promise<v
     records: recordWaitingItems(root, now),
     now,
   })
+  const misplaced = misplacedLinesOf(agents ?? [], {
+    sprintLanes,
+    watched: lanes,
+    worktreeDirectory: join(root, settings.worktreeDirectory),
+  })
+  const misplacedHint = misplaced.length === 0 ? '' : installedReferenceHint(root, REFERENCE.laneSession)
   const hint = installedReferenceHint(root, REFERENCE.coordinatorClear)
-  for (const line of [...lines, ...referenceLine(hint)]) console.log(line)
+  for (const line of [...lines, ...annotateEach(misplaced, misplacedHint), ...referenceLine(hint)]) console.log(line)
 }
 
 /** `jh resume --clear-line`: prints the first input of the chat after a clear, for the script's `--send`. */

package/src/resume/decision.ts

@@ -49,6 +49,8 @@ export type ResumeDecision =
       coordinatorIdentity: CoordinatorIdentity | null
       /** The interrupted lanes with a model column on record, each with that column made printable; only logged. */
       laneModels: Record<string, string>
+      /** Lane → worktree directory of the lanes placed in a directory of another name. */
+      laneWorktrees: Record<string, string>
       /** Lane names that are no single file name: never sent to, only logged. */
       unsafe: string[]
     }
@@ -119,6 +121,7 @@ export const resumeDecision = ({ record, now, watcherRunning, boardExists }: Res
     coordinator: record.coordinator,
     coordinatorIdentity: record.coordinatorIdentity ?? null,
     laneModels: modelsOf(record, interrupted),
+    laneWorktrees: record.laneWorktrees ?? {},
     interrupted,
     blocked: lanesWith(record.lanes, AGENT_STATUS.blocked),
     unsafe: Object.keys(record.lanes).filter((name) => !isSafeName(name)),

package/src/resume/record.ts

@@ -36,6 +36,8 @@ export type ResumeRecord = {
   lanes: Record<string, string>
   /** Lane → the model column of its board row as the watcher last read it; absent in older records. */
   laneModels?: Record<string, string>
+  /** Lane → the worktree directory of a lane whose directory carries another name (`PlansSettings.laneWorktrees`); absent in older records and while no lane is placed so. */
+  laneWorktrees?: Record<string, string>
   stoppedAt: number | null
   resumedAt: number | null
 }
@@ -70,6 +72,7 @@ export const isResumeRecord = (value: unknown): value is ResumeRecord =>
   isLaneStatuses(value.lanes) &&
   (value.coordinatorIdentity === undefined || isCoordinatorIdentity(value.coordinatorIdentity)) &&
   (value.laneModels === undefined || isLaneStatuses(value.laneModels)) &&
+  (value.laneWorktrees === undefined || isLaneStatuses(value.laneWorktrees)) &&
   'stoppedAt' in value &&
   isTimeOrNull(value.stoppedAt) &&
   'resumedAt' in value &&
@@ -129,8 +132,20 @@ export const withLaneModels = (record: ResumeRecord, laneModels: Record<string,
   return sameStatuses(record.laneModels ?? {}, merged) ? record : { ...record, laneModels: merged, savedAt: now }
 }
 
-/** What the watcher saw at one poll besides the lane statuses; both parts may be unknown. */
-export type Observed = { coordinator?: CoordinatorIdentity | null; laneModels?: Record<string, string> }
+/** The record with the lanes placed in worktrees of another name, as the watcher has them now; the same object when unchanged. */
+export const withLaneWorktrees = (
+  record: ResumeRecord,
+  laneWorktrees: Record<string, string>,
+  now: number,
+): ResumeRecord =>
+  sameStatuses(record.laneWorktrees ?? {}, laneWorktrees) ? record : { ...record, laneWorktrees, savedAt: now }
+
+/** What the watcher saw at one poll besides the lane statuses; the parts may be unknown. */
+export type Observed = {
+  coordinator?: CoordinatorIdentity | null
+  laneModels?: Record<string, string>
+  laneWorktrees?: Record<string, string>
+}
 
 /**
  * How often the watcher saves its record although no lane changed: once an hour, so a watcher that rests longer than
@@ -150,9 +165,13 @@ export const followedRecord = (
   observed: Observed = {},
 ): ResumeRecord =>
   refreshedRecord(
-    withLaneModels(
-      withIdentity(withLanes(record, lanes, now), observed.coordinator ?? null, now),
-      observed.laneModels ?? {},
+    withLaneWorktrees(
+      withLaneModels(
+        withIdentity(withLanes(record, lanes, now), observed.coordinator ?? null, now),
+        observed.laneModels ?? {},
+        now,
+      ),
+      observed.laneWorktrees ?? record.laneWorktrees ?? {},
       now,
     ),
     now,

package/src/sync/command.ts

@@ -10,6 +10,7 @@ import {
   runWithKit,
   usageError,
 } from './command-context'
+import { downgradeRefusal, isDowngrade } from './downgrade'
 import { errorMessage } from './error-message'
 import { readForeignSkills } from './foreign-skills'
 import { dailyUpdateNotice, defaultUpdateCheck, lockedVersion, syncNeeded, type UpdateCheck } from './if-changed'
@@ -102,8 +103,20 @@ const syncGlobalIfChanged = async (context: CommandContext, accept: string[], ch
   return exitCode
 }
 
-const syncProject = (context: CommandContext, accept: string[], dryRun: boolean): Promise<number> =>
-  runWithKit(
+/** The refusal line when the running kit is older than the one that wrote the project's lock; null otherwise, and when the kit cannot be located (the sync reports that itself). */
+const projectDowngradeRefusal = async (context: CommandContext): Promise<string | null> => {
+  try {
+    const [running, locked] = [(await context.locate()).version, await lockedVersion(context.projectRoot)]
+    return isDowngrade(running, locked) ? downgradeRefusal(running, locked) : null
+  } catch {
+    return null
+  }
+}
+
+const syncProject = async (context: CommandContext, accept: string[], dryRun: boolean): Promise<number> => {
+  const refusal = await projectDowngradeRefusal(context)
+  if (refusal) return usageError(context, refusal)
+  return runWithKit(
     context,
     'sync',
     async (kit) => {
@@ -116,6 +129,7 @@ const syncProject = (context: CommandContext, accept: string[], dryRun: boolean)
     },
     dryRun,
   )
+}
 
 export const runSyncCommand = async (
   args: string[],

package/src/sync/downgrade.ts

@@ -0,0 +1,9 @@
+import { CLI_NAME, isNewerVersion } from '../version/release'
+
+/** True when the repo's lock was written by a newer kit than the one running: a sync would turn its files back. */
+export const isDowngrade = (running: string, locked: string | null): locked is string =>
+  locked !== null && isNewerVersion(locked, running)
+
+/** The line a refused sync prints; only plain release versions reach it, since `isDowngrade` admits no other. */
+export const downgradeRefusal = (running: string, locked: string): string =>
+  `${CLI_NAME} sync: the repository was synced by ${CLI_NAME} ${locked}, but this ${CLI_NAME} is ${running}, so nothing was synced: it would turn newer kit files back. Update this ${CLI_NAME} with \`${CLI_NAME} update\`, then sync again.`