jackherd 1.26.1 → 1.26.3

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,7 +16,7 @@ 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, misplacedLinesOf } from '../watch/lane-watch'
+import { agentPlacesOf, type HerdrAgent, misplacedLinesOf } from '../watch/lane-watch'
 import { annotateEach, REFERENCE, referenceLine } from '../watch/reference-paths'
 import {
   type CoordinatorStateInput,
@@ -102,22 +103,21 @@ const readPullRequestsSafely = async (
 const sprintLanesOf = ({ settings }: Place, board: string | null): string[] =>
   board === null ? [] : parseSprintLanes(board, settings.boardLanguage).map((lane) => lane.name)
 
-const lanesOf = ({ root, settings }: Place, sprintLanes: string[], agents: readonly HerdrAgent[] | null): string[] =>
-  discoverLanes({
-    worktrees: worktreeNames(join(root, settings.worktreeDirectory)),
-    agentNames: (agents ?? []).flatMap((agent) => agent.name ?? []),
-    sprintLanes,
-  })
+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 sprintLanes = sprintLanesOf(place, board)
-  const lanes = lanesOf(place, sprintLanes, 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,

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.`

package/src/sync/if-changed.ts

@@ -2,7 +2,8 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { LEGACY_MANIFEST_PATH } from '../config/legacy-names'
 import { MANIFEST_FILE, TOOL_DIRECTORY } from '../config/location'
-import { CLI_NAME, isNewerVersion, PACKAGE_NAME } from '../version/release'
+import { REGISTRY_TIMEOUT_MS, registryUrl } from '../version/registry'
+import { CLI_NAME, isNewerVersion } from '../version/release'
 import { parseManifest } from './manifest'
 import { FILE_MODE } from './plan-file'
 import { assertOwnDirectoriesInProject, writeFileSafely } from './project-fs'
@@ -18,8 +19,6 @@ export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
 /** How soon npm is asked again after it gave no answer: an hour, so an offline morning does not cost the day. */
 export const UPDATE_RETRY_INTERVAL_MS = 60 * 60 * 1000
 
-const REGISTRY_LATEST = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`
-const REGISTRY_TIMEOUT_MS = 3_000
 const UPDATE_STATE_FILE = 'update-check.json'
 
 /**
@@ -55,9 +54,9 @@ const versionOfLock = async (path: string): Promise<string | null> => {
   return parsed.ok ? parsed.manifest.kitVersion : null
 }
 
-/** The kit version the global lock was written by, under its old name while the global sync has not moved it. */
-export const lockedVersion = async (home: string): Promise<string | null> =>
-  (await versionOfLock(join(home, TOOL_DIRECTORY, MANIFEST_FILE))) ?? versionOfLock(join(home, LEGACY_MANIFEST_PATH))
+/** The kit version the lock under `root` (the home directory or a project) was written by, under its old name while a sync has not moved it. */
+export const lockedVersion = async (root: string): Promise<string | null> =>
+  (await versionOfLock(join(root, TOOL_DIRECTORY, MANIFEST_FILE))) ?? versionOfLock(join(root, LEGACY_MANIFEST_PATH))
 
 const readUpdateState = async (path: string): Promise<UpdateState | null> => {
   const raw = await readJson(path)
@@ -107,7 +106,7 @@ export const dailyUpdateNotice = async (home: string, installed: string, check:
 /** Asks the npm registry for the `latest` tag; null on any failure, after a few seconds at most. */
 const registryLatestVersion = async (): Promise<string | null> => {
   try {
-    const response = await fetch(REGISTRY_LATEST, { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) })
+    const response = await fetch(registryUrl('latest'), { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) })
     if (!response.ok) return null
     const { version } = (await response.json()) as { version?: unknown }
     return typeof version === 'string' ? version : null

package/src/update/command.ts

@@ -13,9 +13,11 @@ import { findProjectRoot } from '../config/location'
 import { defaultUpdateCheck, lockedVersion } from '../sync/if-changed'
 import { locateKit } from '../sync/kit-source'
 import { readInstalledVersion } from '../version/installed-version'
+import { REGISTRY_TIMEOUT_MS, registryUrl } from '../version/registry'
 import { CLI_NAME } from '../version/release'
 import { rewriteConfigShares } from './config-shares'
 import { detectPackageManager, legacyPackageRoot, shellHostedGlobalRoot } from './package-manager'
+import { VERSION_AVAILABILITY, type VersionAvailability } from './registry-wait'
 import { runUpdate, UPDATE_EXIT, type UpdateAdapters } from './update'
 
 const USAGE = `Usage: ${CLI_NAME} update`
@@ -35,6 +37,19 @@ const runInherited = async (argv: readonly string[], cwd: string): Promise<numbe
   }
 }
 
+const NOT_FOUND = 404
+
+/** Asks the registry for one exact version: 404 is `missing`, any other failure `unknown`. */
+const registryAvailability = async (version: string): Promise<VersionAvailability> => {
+  try {
+    const response = await fetch(registryUrl(version), { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) })
+    if (response.ok) return VERSION_AVAILABILITY.available
+    return response.status === NOT_FOUND ? VERSION_AVAILABILITY.missing : VERSION_AVAILABILITY.unknown
+  } catch {
+    return VERSION_AVAILABILITY.unknown
+  }
+}
+
 const adaptersFor = async (): Promise<UpdateAdapters> => {
   const { version, packageRoot } = await locateKit()
   const home = homedir()
@@ -44,6 +59,8 @@ const adaptersFor = async (): Promise<UpdateAdapters> => {
     installedVersion: version,
     manager: detectPackageManager(realRoot),
     latestVersion: defaultUpdateCheck().latestVersion,
+    versionAvailability: registryAvailability,
+    sleep: (ms) => Bun.sleep(ms),
     installedVersionOnDisk: () => readInstalledVersion(targetRoot),
     kitCli: [process.execPath, join(targetRoot, 'src', 'cli.ts')],
     run: runInherited,

package/src/update/registry-wait.ts

@@ -0,0 +1,44 @@
+/** What the registry says about one exact version; `unknown` when it did not answer, which never blocks an install. */
+export const VERSION_AVAILABILITY = { available: 'available', missing: 'missing', unknown: 'unknown' } as const
+
+export type VersionAvailability = (typeof VERSION_AVAILABILITY)[keyof typeof VERSION_AVAILABILITY]
+
+/** How long `jh update` waits for a version the registry has not distributed yet. */
+export type RetryPolicy = {
+  /** Probes after the first one; the number of waits. */
+  retries: number
+  firstDelayMs: number
+  factor: number
+  maxDelayMs: number
+}
+
+export type WaitOutcome = { settled: VersionAvailability; waitedMs: number }
+
+/** About a minute and a half in total: a fresh publish reaches the registry's mirrors well within it. */
+export const DISTRIBUTION_WAIT: RetryPolicy = { retries: 6, firstDelayMs: 2_000, factor: 2, maxDelayMs: 30_000 }
+
+/** The waits between the probes, growing by `factor` and capped at `maxDelayMs`; empty for no retries. */
+export const retryDelays = (policy: RetryPolicy): number[] =>
+  Array.from({ length: Math.max(0, policy.retries) }, (_, index) =>
+    Math.min(policy.maxDelayMs, Math.round(policy.firstDelayMs * policy.factor ** index)),
+  )
+
+/**
+ * Probes until the registry stops answering `missing`, sleeping the policy's delays in between; the sleep is an
+ * argument, so a test runs it without time passing. Settles on `available`, on `unknown` (the install decides),
+ * or on `missing` once the delays are used up: a version that never appears waits `sum(delays)` and no longer.
+ */
+export const waitForAvailability = async (
+  probe: () => Promise<VersionAvailability>,
+  sleep: (ms: number) => Promise<void>,
+  policy: RetryPolicy,
+): Promise<WaitOutcome> => {
+  let waitedMs = 0
+  for (const delay of retryDelays(policy)) {
+    const settled = await probe()
+    if (settled !== VERSION_AVAILABILITY.missing) return { settled, waitedMs }
+    await sleep(delay)
+    waitedMs += delay
+  }
+  return { settled: await probe(), waitedMs }
+}

package/src/update/update.ts

@@ -1,5 +1,6 @@
 import { CLI_NAME, isNewerVersion, isRelease, PACKAGE_NAME } from '../version/release'
 import { installCommand, LEGACY_PACKAGE_NAME, type PackageManager, removeCommand } from './package-manager'
+import { DISTRIBUTION_WAIT, VERSION_AVAILABILITY, type VersionAvailability, waitForAvailability } from './registry-wait'
 
 export const UPDATE_EXIT = { ok: 0, error: 1 } as const
 
@@ -9,6 +10,10 @@ export type UpdateAdapters = {
   /** The manager that installed the kit globally, or null when it is not a global install. */
   manager: PackageManager | null
   latestVersion: () => Promise<string | null>
+  /** Asks the registry whether this exact version can be installed yet; `unknown` when it did not answer. */
+  versionAvailability: (version: string) => Promise<VersionAvailability>
+  /** Waits `ms` milliseconds; a test passes one that returns at once. */
+  sleep: (ms: number) => Promise<void>
   /** The version in the package on disk now, after the install; null when it cannot be read. */
   installedVersionOnDisk: () => string | null
   /** The words that start this very package's CLI (runtime, then `src/cli.ts`), so a sync runs the code just installed and no `jh` found on the path. */
@@ -81,6 +86,23 @@ const installAndVerify = async (
   return UPDATE_EXIT.error
 }
 
+/**
+ * Waits while the registry answers 404 for `version`, which it does right after a publish until the release is
+ * distributed; false, with a line saying why, once the waits are used up and nothing was changed.
+ */
+const awaitDistribution = async (adapters: UpdateAdapters, version: string): Promise<boolean> => {
+  const { settled, waitedMs } = await waitForAvailability(
+    () => adapters.versionAvailability(version),
+    adapters.sleep,
+    DISTRIBUTION_WAIT,
+  )
+  if (settled !== VERSION_AVAILABILITY.missing) return true
+  adapters.log(
+    `${CLI_NAME} update: ${PACKAGE_NAME}@${version} is still not on the npm registry after ${Math.round(waitedMs / 1000)} seconds, so nothing was changed. Run \`${CLI_NAME} update\` again in a few minutes.`,
+  )
+  return false
+}
+
 /** Runs the syncs with the freshly installed code; the first that fails stops the rest and names its command. */
 const syncAfterInstall = async (adapters: UpdateAdapters, project: string | null): Promise<number> => {
   for (const { argv, cwd } of await syncSteps(adapters, project)) {
@@ -117,6 +139,7 @@ const updateToLatest = async (adapters: UpdateAdapters, manager: PackageManager)
     if (adapters.projectRoot && !installedProject(adapters)) logConfigShares(adapters, adapters.projectRoot)
     return UPDATE_EXIT.ok
   }
+  if (!(await awaitDistribution(adapters, latest))) return UPDATE_EXIT.error
   const installed = await installAndVerify(adapters, manager, latest)
   if (installed !== UPDATE_EXIT.ok) return installed
   const project = installedProject(adapters)

package/src/version/registry.ts

@@ -0,0 +1,8 @@
+import { PACKAGE_NAME } from './release'
+
+/** How long one question to the npm registry may take before it counts as unanswered. */
+export const REGISTRY_TIMEOUT_MS = 3_000
+
+/** The registry's document for a tag (`latest`) or for one exact version of this package. */
+export const registryUrl = (versionOrTag: string): string =>
+  `https://registry.npmjs.org/${PACKAGE_NAME}/${versionOrTag}`

package/src/watch/command.ts

@@ -56,6 +56,7 @@ import { ensurePlanPanes } from '../plans/ensure-panes'
 import { errorText } from '../plans/error-text'
 import { baseReaderOf, mainCheckout, worktreeNames, worktreeRoot } from '../plans/git'
 import { discoverLanes, isUnchanged, laneSetChange } from '../plans/lane-discovery'
+import { type PlacedLanes, placeLanes } from '../plans/lane-worktrees'
 import { readerOncePerRef } from '../plans/plan-heads'
 import { readQuestionRecords } from '../plans/questions-read'
 import { closeSentRecords, readSentRecords } from '../plans/sent-files-read'
@@ -172,6 +173,7 @@ import { branchOf, fetchBaseWhenMoved, fetchPlanHeadsWhenMoved, readMainCheckout
 import { type LaneStalledEvent, laneStalledEvents, STALLED_HEARTBEATS, type StallState } from './lane-stalled'
 import {
   advanceBaseline,
+  agentPlacesOf,
   armBaseline,
   baselineWithNewAgents,
   departedLanes,
@@ -302,6 +304,7 @@ type Watch = {
   boardNotice: string | null
   options: WatchOptions
   files: Files
+  /** Set at the start and again at every poll, once the lanes are placed by where their agents run (`placeLanes`). */
   settings: PlansSettings
   /** `watch.deploy`, `feedback`, `previews` and `checks` as read at the start; the loop reads them from `Watching.live`. */
   live: LiveValues
@@ -1158,13 +1161,16 @@ const readSprintLanes = (watch: Watch): SprintLane[] | null => {
 const sprintLaneNames = (watch: Watch, previous: string[]): string[] =>
   readSprintLanes(watch)?.map((lane) => lane.name) ?? previous
 
-const lanesFor = (watch: Watch, agents: readonly HerdrAgent[], sprintLanes: readonly string[]): string[] =>
-  watch.options.lanes ??
-  discoverLanes({
-    worktrees: worktreeNames(join(watch.root, watch.settings.worktreeDirectory)),
-    agentNames: agentNamesOf(agents),
-    sprintLanes,
-  })
+/** Places the lanes by where their agents run (`placeLanes`), named lanes included; the caller takes up `settings` into `watch.settings`. */
+const placeLanesOf = (watch: Watch, agents: readonly HerdrAgent[], sprintLanes: readonly string[]): PlacedLanes =>
+  placeLanes(watch.root, watch.settings, agentPlacesOf(agents), [...sprintLanes, ...(watch.options.lanes ?? [])])
+
+const lanesFor = (
+  watch: Watch,
+  agents: readonly HerdrAgent[],
+  sprintLanes: readonly string[],
+  worktrees: readonly string[],
+): string[] => watch.options.lanes ?? discoverLanes({ worktrees, agentNames: agentNamesOf(agents), sprintLanes })
 
 /** Prints the `lane <name> not watched` lines that are new since the last poll; named lanes are never discovered, so they have none. */
 const reportMisplaced = (watch: Watch, watching: Watching) => {
@@ -1203,7 +1209,9 @@ const keepBackendPane = async (watch: Watch, watching: Watching) => {
 const followLaneSet = (watch: Watch, watching: Watching): string[] => {
   if (watch.options.lanes !== null) return []
   watching.sprintLanes = sprintLaneNames(watch, watching.sprintLanes)
-  const lanes = lanesFor(watch, watching.agents, watching.sprintLanes)
+  const placed = placeLanesOf(watch, watching.agents, watching.sprintLanes)
+  watch.settings = placed.settings
+  const lanes = lanesFor(watch, watching.agents, watching.sprintLanes, placed.worktrees)
   const change = laneSetChange(watching.lanes, lanes)
   if (isUnchanged(change)) return []
   watching.departed = [...watching.departed, ...departedLanes(change.removed, watching.baseline, watching.current)]
@@ -1333,6 +1341,7 @@ const noTaskSignalEventsOf = (
     const signalled = signalledLanes(watching.lanes, {
       root: watch.root,
       worktreeDirectory: watch.settings.worktreeDirectory,
+      laneWorktrees: watch.settings.laneWorktrees,
       now,
     })
     const counts = currentPhaseCountsOf(progress)
@@ -1400,23 +1409,25 @@ const waitingObsoleteEventsOf = (
   if (!watch.inMainCheckout) return []
   try {
     const worktreeDirectory = join(watch.root, watch.settings.worktreeDirectory)
+    const { laneWorktrees } = watch.settings
     if (!existsSync(worktreeDirectory)) return []
     const sends = readSentRecords(watch.root)
     const questions = readQuestionRecords(watch.root)
     const boardText = readBoardText(watch)
     const board = boardText === null ? null : openWaitingItems(boardText, watch.settings.boardLanguage)
     const { missing, gone } = laneAbsenceOf(
-      waitingLanesOf({ sends, questions, board, worktreeDirectory }),
-      new Set(worktreeNames(worktreeDirectory)),
+      waitingLanesOf({ sends, questions, board, worktreeDirectory, laneWorktrees }),
+      new Set([...worktreeNames(worktreeDirectory), ...Object.keys(laneWorktrees)]),
       watching.waitingMissingLanes,
     )
-    const closings = closeObsoleteSends(watch.root, obsoleteSendsOf(sends, worktreeDirectory, gone), now)
+    const closings = closeObsoleteSends(watch.root, obsoleteSendsOf(sends, worktreeDirectory, gone, laneWorktrees), now)
     const closed = new Set(closings.map(({ id }) => id))
     const { events, state } = obsoleteProposalEvents(watching.waitingProposals, {
       sends: sends.filter(({ id }) => !closed.has(id)),
       questions,
       board,
       worktreeDirectory,
+      laneWorktrees,
       gone,
       ...proposalContextOf(watching),
     })
@@ -1477,10 +1488,10 @@ const subagentCountsOf = (watch: Watch, now: number): Record<string, number> =>
   try {
     const worktreeDirectory = join(watch.root, watch.settings.worktreeDirectory)
     const running = readRunningSubagents(
-      subagentSourceOf(watch.root, worktreeDirectory, watch.settings.skillPrefix),
+      subagentSourceOf(watch.root, worktreeDirectory, watch.settings.skillPrefix, watch.settings.laneWorktrees),
       now,
     )
-    return runningSubagentCountsOf(running, worktreeDirectory)
+    return runningSubagentCountsOf(running, worktreeDirectory, watch.settings.laneWorktrees)
   } catch {
     return {}
   }
@@ -1719,7 +1730,9 @@ const watchLanes = async (watch: Watch): Promise<boolean> => {
   const state = await readState(watch.files)
   const agents = listAgents()
   const sprintLanes = watch.options.lanes ? [] : sprintLaneNames(watch, [])
-  const lanes = lanesFor(watch, agents, sprintLanes)
+  const placed = placeLanesOf(watch, agents, sprintLanes)
+  watch.settings = placed.settings
+  const lanes = lanesFor(watch, agents, sprintLanes, placed.worktrees)
   const armed = toSnapshot(agents, lanes)
   const arm = armNotice(state.armed, lanes, armed, takeOver, relative(watch.root, watch.sprintFile))
   if (arm.line !== null)
@@ -1742,6 +1755,7 @@ const watchLanes = async (watch: Watch): Promise<boolean> => {
       process.env.HERDR_PANE_ID,
     ),
     laneModels: laneModelColumnsOf(watching.laneModelReadings),
+    laneWorktrees: { ...watch.settings.laneWorktrees },
   })
   resumeRecord.follow(armed, Date.now(), observed())
   process.on('SIGTERM', () => {

package/src/watch/obsolete-proposals.ts

@@ -4,7 +4,7 @@ import type { WaitingItem } from '../plan-format/waiting'
 import { CLOSE_REASON, closeReasonOf } from '../plans/close-reason'
 import { type QuestionRecord, questionTextOf } from '../plans/question-records'
 import { type SentFileRecord, sentLaneOf, sentTextOf } from '../plans/sent-files'
-import { laneDirectoryOf } from '../plans/unlisted-lanes'
+import { type LaneWorktrees, laneOfCwd } from '../plans/unlisted-lanes'
 import { isRecord } from '../shared/is-record'
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
 import { latestPullRequestOf, PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
@@ -33,6 +33,8 @@ export type ProposalInput = {
   /** Lane → branch, as the watcher keeps it after a lane was closed. */
   laneBranches: Readonly<Record<string, string>>
   worktreeDirectory: string
+  /** The lanes placed in worktrees of another name (`PlansSettings.laneWorktrees`). */
+  laneWorktrees?: LaneWorktrees
   /** The lanes whose directory was missing in two heartbeats in a row (`laneAbsenceOf`). */
   gone: ReadonlySet<string>
   /** The lanes known to have existed; a board row naming a lane that never had a worktree proposes nothing. */
@@ -64,13 +66,13 @@ export const textReferencesOf = (text: string): TextReferences => ({
 
 /** The lanes the open points name: a send's lane, a question's lane by its directory, a board row's lanes in its text. */
 export const waitingLanesOf = (
-  input: Pick<ProposalInput, 'sends' | 'questions' | 'board' | 'worktreeDirectory'>,
+  input: Pick<ProposalInput, 'sends' | 'questions' | 'board' | 'worktreeDirectory' | 'laneWorktrees'>,
 ): string[] => [
   ...input.sends.flatMap((record) =>
-    record.closedAt === null ? (sentLaneOf(record, input.worktreeDirectory) ?? []) : [],
+    record.closedAt === null ? (sentLaneOf(record, input.worktreeDirectory, input.laneWorktrees) ?? []) : [],
   ),
   ...input.questions.flatMap((record) =>
-    record.closedAt === null ? (laneDirectoryOf(record.cwd, input.worktreeDirectory) ?? []) : [],
+    record.closedAt === null ? (laneOfCwd(record.cwd, input.worktreeDirectory, input.laneWorktrees) ?? []) : [],
   ),
   ...(input.board ?? []).flatMap((row) => textReferencesOf(rowText(row)).lanes),
 ]
@@ -87,7 +89,7 @@ const laneRemovedReason = (lane: string): string => closeReasonOf(CLOSE_REASON.l
 
 const sendProposals = (input: ProposalInput): Proposal[] =>
   input.sends.flatMap((record) => {
-    const lane = sentLaneOf(record, input.worktreeDirectory)
+    const lane = sentLaneOf(record, input.worktreeDirectory, input.laneWorktrees)
     const branch = lane === null ? undefined : input.laneBranches[lane]
     const pullRequest = branch === undefined ? null : latestPullRequestOf(input.pullRequests ?? [], branch)
     return record.closedAt === null && pullRequest !== null && hasEnded(pullRequest)
@@ -96,7 +98,7 @@ const sendProposals = (input: ProposalInput): Proposal[] =>
   })
 
 const questionReasons = (record: QuestionRecord, input: ProposalInput): string[] => {
-  const lane = laneDirectoryOf(record.cwd, input.worktreeDirectory)
+  const lane = laneOfCwd(record.cwd, input.worktreeDirectory, input.laneWorktrees)
   const superseded = record.supersededBy ? [`${SUPERSEDED}: ${record.supersededBy.question}`] : []
   const ended = typeof record.sessionEndedAt === 'number' ? [SESSION_ENDED] : []
   return [...superseded, ...ended, ...(lane !== null && input.gone.has(lane) ? [laneRemovedReason(lane)] : [])]