jackherd 1.19.0 → 1.21.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.21.0
+
+- **`jh init` and `jh sync` prepare the main checkout for the herdr plugin `zerodice0.worktree-bootstrap`.** When herdr lists the plugin as enabled, they write `.herdr/worktree-copy.list` from `lanes.copy`, `.herdr/worktree-setup.json` with `commands.install` (run with the Node version of `.nvmrc` when the checkout has one) and `/.herdr/` into the git exclude file. A second run rewrites nothing. A `lanes.copy` path git does not ignore is named in a warning, since the plugin skips it. Without herdr or the plugin nothing is written. The orchestrate lane setup also names the plugin's `sync` for a worktree that existed before. Run `jh sync` to get the skill text.
+
+## 1.20.0
+
+- **`jh lane port` picks a lane's dev-server port.** It prints the lowest port from 3100 that nothing listens on and that no running lane holds in the port column of the board (`--board <board.md>` names the board, else it is picked as for `jh herd`). Rows of cleaned-up lanes reserve nothing, so ports no longer climb. `lanes.basePort` in `.jackherd/config.json` moves the start. Run `jh sync` to get the skill text.
+
 ## 1.19.0
 
 - **The coordinator clears its context at quiet moments.** The watcher prints `coordinator clear <n>k` once your coordinator's context reaches `plans.context.coordinator.clearTokens` (250 000 by default), or `clearAfterMergeTokens` (150 000) after a merge with the board written afterwards, and only when no dialog is open, nothing unread waits, no lane is blocked or has a question not yet shown, no approval waits and no PR with self-merge is open. Without your own `clearTokens` a lower `warnTokens` moves it just below that; one you set at or above `warnTokens` is refused. `coordinator warn` now points to clearing, and the hand-over with a note stays for `coordinator alert`. Run `jh sync` to get the skill texts.

package/README.md

@@ -1,9 +1,9 @@
 <p>
-<img alt="jackherd: a black and white Shih Tzu in a turquoise bandana, three lanes running from him to three agent nodes" src="https://unpkg.com/jackherd@1.19.0/assets/branding/jackherd-logo-outline.svg" width="340">
+<img alt="jackherd: a black and white Shih Tzu in a turquoise bandana, three lanes running from him to three agent nodes" src="https://unpkg.com/jackherd@1.21.0/assets/branding/jackherd-logo-outline.svg" width="340">
 <br>
 </p>
 
-[![npm](https://img.shields.io/npm/v/jackherd)](https://www.npmjs.com/package/jackherd) [![license: MIT](https://img.shields.io/npm/l/jackherd)](https://www.npmjs.com/package/jackherd) [![2 dependencies](https://img.shields.io/badge/dependencies-2-brightgreen)](https://www.npmjs.com/package/jackherd?activeTab=dependencies) [![macOS](https://img.shields.io/badge/macOS-supported-brightgreen?logo=apple)](https://unpkg.com/jackherd/INSTALL.md) [![Linux](https://img.shields.io/badge/Linux-supported-brightgreen?logo=linux&logoColor=white)](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.19.0/assets/icons/space.svg">
+[![npm](https://img.shields.io/npm/v/jackherd)](https://www.npmjs.com/package/jackherd) [![license: MIT](https://img.shields.io/npm/l/jackherd)](https://www.npmjs.com/package/jackherd) [![2 dependencies](https://img.shields.io/badge/dependencies-2-brightgreen)](https://www.npmjs.com/package/jackherd?activeTab=dependencies) [![macOS](https://img.shields.io/badge/macOS-supported-brightgreen?logo=apple)](https://unpkg.com/jackherd/INSTALL.md) [![Linux](https://img.shields.io/badge/Linux-supported-brightgreen?logo=linux&logoColor=white)](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.21.0/assets/icons/space.svg">
 
 # Jack herds your coding agents.
 
@@ -15,29 +15,29 @@ For developers who'd rather decide than supervise.
 curl -fsSL https://unpkg.com/jackherd/install.sh | sh
 ```
 
-Then `/jh-start` in a repository, and Jack offers your first plan. → [Quickstart](#quickstart)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.19.0/assets/icons/space.svg">
+Then `/jh-start` in a repository, and Jack offers your first plan. → [Quickstart](#quickstart)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.21.0/assets/icons/space.svg">
 
 <p>
-<img src="https://unpkg.com/jackherd@1.19.0/docs/workflow-dark.svg" width="720" alt="jackherd in herdr: a lane hits a question, Jack asks you as a choice, you pick, and the lane works on while the herd view counts its progress.">
+<img src="https://unpkg.com/jackherd@1.21.0/docs/workflow-dark.svg" width="720" alt="jackherd in herdr: a lane hits a question, Jack asks you as a choice, you pick, and the lane works on while the herd view counts its progress.">
 <br>
-<sub>Jack and his lanes in <a href="https://herdr.dev/">herdr</a>, a terminal for coding agents (recommended). Without it, one Claude Code session builds with subagents.</sub><br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.19.0/assets/icons/space.svg">
+<sub>Jack and his lanes in <a href="https://herdr.dev/">herdr</a>, a terminal for coding agents (recommended). Without it, one Claude Code session builds with subagents.</sub><br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.21.0/assets/icons/space.svg">
 </p>
 
-<p><img src="https://unpkg.com/jackherd@1.19.0/assets/icons/lanes.svg" width="24" height="34" align="middle" alt=""> <b>Parallel where it pays.</b><br>Phases that don't collide run side by side, each lane on its own branch and worktree. Jack keeps the merge order and has the others rebase.</p>
+<p><img src="https://unpkg.com/jackherd@1.21.0/assets/icons/lanes.svg" width="24" height="34" align="middle" alt=""> <b>Parallel where it pays.</b><br>Phases that don't collide run side by side, each lane on its own branch and worktree. Jack keeps the merge order and has the others rebase.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.19.0/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Commits, pushes and merges wait for your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours. The guards catch mistakes, not intent; a hard boundary takes branch protection.</p>
+<p><img src="https://unpkg.com/jackherd@1.21.0/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Commits, pushes and merges wait for your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours. The guards catch mistakes, not intent; a hard boundary takes branch protection.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.19.0/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A lane gets stuck, a check goes red, a decision needs you: Jack steps in and brings you only what's yours to decide. The herd view shows where every lane stands.</p>
+<p><img src="https://unpkg.com/jackherd@1.21.0/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A lane gets stuck, a check goes red, a decision needs you: Jack steps in and brings you only what's yours to decide. The herd view shows where every lane stands.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.19.0/assets/icons/skills.svg" width="24" height="34" align="middle" alt=""> <b>Works with your skills.</b><br>Keep your own skills: a lane builds with whichever one you pick. Plans written elsewhere run too, once Jack fills in what they're missing.</p>
+<p><img src="https://unpkg.com/jackherd@1.21.0/assets/icons/skills.svg" width="24" height="34" align="middle" alt=""> <b>Works with your skills.</b><br>Keep your own skills: a lane builds with whichever one you pick. Plans written elsewhere run too, once Jack fills in what they're missing.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.19.0/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments on a lane's pull request go back to that lane, which fixes them with a test. <code>/jh-follow</code> brings in anything a CLI or an API can read as JSON: tickets, error logs, status pages.</p>
+<p><img src="https://unpkg.com/jackherd@1.21.0/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments on a lane's pull request go back to that lane, which fixes them with a test. <code>/jh-follow</code> brings in anything a CLI or an API can read as JSON: tickets, error logs, status pages.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.19.0/assets/icons/model.svg" width="24" height="34" align="middle" alt=""> <b>The right model for each phase.</b><br>Every phase names its model: the stronger one where a mistake is expensive (data, security, a migration), the cheaper one for the rest. Lanes start on it, and a hook refuses to start a phase's subagent on a weaker one.</p>
+<p><img src="https://unpkg.com/jackherd@1.21.0/assets/icons/model.svg" width="24" height="34" align="middle" alt=""> <b>The right model for each phase.</b><br>Every phase names its model: the stronger one where a mistake is expensive (data, security, a migration), the cheaper one for the rest. Lanes start on it, and a hook refuses to start a phase's subagent on a weaker one.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.19.0/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>A crash or a full context doesn't cost you the work.</b><br>Plan, board and a hand-over file hold the state, not the chat: the next session picks up where the last one stopped.</p>
+<p><img src="https://unpkg.com/jackherd@1.21.0/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>A crash or a full context doesn't cost you the work.</b><br>Plan, board and a hand-over file hold the state, not the chat: the next session picks up where the last one stopped.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.19.0/assets/icons/plan.svg" width="24" height="34" align="middle" alt=""> <b>Lives in your repository.</b><br>Plans, board and every decision are Markdown, reviewed like code. <code>jh init</code> gives your team the same setup.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.19.0/assets/icons/space.svg"></p>
+<p><img src="https://unpkg.com/jackherd@1.21.0/assets/icons/plan.svg" width="24" height="34" align="middle" alt=""> <b>Lives in your repository.</b><br>Plans, board and every decision are Markdown, reviewed like code. <code>jh init</code> gives your team the same setup.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.21.0/assets/icons/space.svg"></p>
 
 ## Quickstart
 
@@ -68,22 +68,22 @@ Then `/jh-start` in a repository, and Jack offers your first plan. → [Quicksta
    /jh-orchestrate docs/plans/board-<name>/board.md
    ```
 
-Linux and macOS are supported (Windows through WSL); the requirements are in [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md). By hand (Bun 1.3+): `bun add -g jackherd` or `npm install -g jackherd`, then `jh init --global` for yourself, or `jh init` in a repository to give your team the same skills and guard hooks.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.19.0/assets/icons/space.svg">
+Linux and macOS are supported (Windows through WSL); the requirements are in [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md). By hand (Bun 1.3+): `bun add -g jackherd` or `npm install -g jackherd`, then `jh init --global` for yourself, or `jh init` in a repository to give your team the same skills and guard hooks.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.21.0/assets/icons/space.svg">
 
 ## Follow anything you can query
 
 Tickets, error logs, status pages: if a command or an API call can read it as JSON with your login, Jack can watch it. Recipes cover Jira, Linear, GitHub issues and Projects, Sentry, Google Calendar and status pages; for anything else, `/jh-follow` writes the command with you. One yes, and every change shows up like this:
 
-<img src="https://unpkg.com/jackherd@1.19.0/docs/follow-dark.svg" width="720" alt="A source (ticket, error log or status page) has a new or changed entry; jh watch reports it to Jack; Jack puts a row into Your turn, prefixed with the source's label; its [ask] button makes Jack ask you, and then a lane works it.">
+<img src="https://unpkg.com/jackherd@1.21.0/docs/follow-dark.svg" width="720" alt="A source (ticket, error log or status page) has a new or changed entry; jh watch reports it to Jack; Jack puts a row into Your turn, prefixed with the source's label; its [ask] button makes Jack ask you, and then a lane works it.">
 
-The herd sums up your sources in one `Sources` line: new entries per source, or its last run, red while it fails; opened, a click opens an entry. One that needs you lands in Your turn under the source's label, [ask] has Jack look at it, and a ticket shows on the lane that works it.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.19.0/assets/icons/space.svg">
+The herd sums up your sources in one `Sources` line: new entries per source, or its last run, red while it fails; opened, a click opens an entry. One that needs you lands in Your turn under the source's label, [ask] has Jack look at it, and a ticket shows on the lane that works it.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.21.0/assets/icons/space.svg">
 
 ## In detail
 
 <details>
 <summary><b>What Jack does on his own, and what waits for you</b></summary>
 
-<img src="https://unpkg.com/jackherd@1.19.0/docs/lanes-dark.svg" alt="Jack prompts two lanes and asks you for decisions and approvals; the lanes send questions back as text; jh watch reads lane state, pull requests and checks and wakes Jack.">
+<img src="https://unpkg.com/jackherd@1.21.0/docs/lanes-dark.svg" alt="Jack prompts two lanes and asks you for decisions and approvals; the lanes send questions back as text; jh watch reads lane state, pull requests and checks and wakes Jack.">
 
 | On his own | After your approval | Never |
 | --- | --- | --- |
@@ -118,7 +118,7 @@ The guards catch mistakes, not intent; for that, use branch protection. The hook
 
 A **plan** is Markdown with phases, checkbox tasks, a model and a review gate per phase. A **board** lists the lanes of one or more plans: which phases each lane builds, on which model, after what. A **lane** is one agent session in its own git worktree (a second checkout of your repository), and **Jack** is the session in the main checkout that runs `/jh-orchestrate` on a board.
 
-<img src="https://unpkg.com/jackherd@1.19.0/docs/skills-dark.svg" alt="Your own plan or an issue is adopted (Jack adds what is missing, you see the diff) and goes to /jh-orchestrate; /jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement, which your own skill can replace; /jh-implement ends in /jh-pre-commit, which runs the reviewers; /jh-diagnose hands a red command to /jh-implement.">
+<img src="https://unpkg.com/jackherd@1.21.0/docs/skills-dark.svg" alt="Your own plan or an issue is adopted (Jack adds what is missing, you see the diff) and goes to /jh-orchestrate; /jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement, which your own skill can replace; /jh-implement ends in /jh-pre-commit, which runs the reviewers; /jh-diagnose hands a red command to /jh-implement.">
 
 | Skill | Does |
 | --- | --- |

package/dist/config.d.ts

@@ -120,6 +120,7 @@ declare const jackherdConfigSchema: z.ZodObject<{
         copy: z.ZodDefault<z.ZodArray<z.ZodString>>;
         lockFile: z.ZodOptional<z.ZodString>;
         minFreeGb: z.ZodOptional<z.ZodNumber>;
+        basePort: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     models: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
         review: "review";

package/dist/config.js

@@ -706,7 +706,9 @@ var jackherdConfigSchema = z2.strictObject({
     /** The dependency lock file a rebase takes from the base branch and regenerates, never merges by hand; detected from the repository when left out. */
     lockFile: lockFilePath.optional(),
     /** Free gigabytes the disk must hold before `jh lane space` lets a new lane install its dependencies; 5 when left out. */
-    minFreeGb: z2.number().positive().optional()
+    minFreeGb: z2.number().positive().optional(),
+    /** The port `jh lane port` starts counting from when it picks a lane's dev-server port; 3100 when left out. */
+    basePort: z2.number().int().min(1).max(65535).optional()
   }).prefault({}),
   models: z2.record(z2.enum(Object.values(MODEL_ROLE)), modelId).default(DEFAULT_MODELS),
   terminal: z2.strictObject({ adapter: z2.enum(Object.values(TERMINAL_ADAPTER)).default(TERMINAL_ADAPTER.none) }).prefault({}),

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.19.0"
+version = "1.21.0"
 min_herdr_version = "0.8.2"
 description = "Show the herd, the state of a board's lanes, in a herdr pane"
 platforms = ["linux", "macos"]

package/install.sh

@@ -9,7 +9,7 @@ set -eu
 
 # The default is the version this file ships with. The release bump changes it together with
 # package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
-JACKHERD_VERSION="${JACKHERD_VERSION:-1.19.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.21.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/workflow/skills/orchestrate/references/lane-setup.md

@@ -16,6 +16,11 @@ changes nothing. Decide by what you find:
   marker of step 4; that command is the check, not a look for a directory such as `node_modules/<package>`.
   If the command fails, do the step below yourself;
   if that fails too, report it.
+- **Plugin enabled, but its hook never ran for this worktree** (taken over, or made before the plugin was set
+  up): inside the worktree, run
+  `env -u HERDR_PLUGIN_CONTEXT_JSON -u HERDR_PLUGIN_EVENT_JSON python3 <plugin_root>/worktree_bootstrap.py sync`
+  (`plugin_root` is in `herdr plugin list --json`; without `env -u` the script takes the context workspace).
+  It copies the env files only: then `cmp -s` per file, and step 4 stays.
 - **Plugin missing, disabled, or its file absent:** do the step as written below.
 
 ## Step 3: env files

package/kit/workflow/skills/orchestrate/references/start-lane.md

@@ -32,7 +32,7 @@ column and the plan's dependency table are met and step 1 finds nothing.
 4. **Dependencies**, installed in the worktree's pane: the same file.
 5. **Agent with the plan's model:**
    `herdr agent start <lane> --kind claude --pane <pane> --timeout 120000 -- --model <model-id>`.
-   - **The lane's row comes first** in the board's `## {{kit.heading.lanes}}` table: lane, port, plan,
+   - **The lane's row comes first** in the board's `## {{kit.heading.lanes}}` table: lane, port (from `jh lane port`), plan,
      phases, starts after, model. The phases cell starts with the phase id (`P10c …`), also for a sub-phase, and
      the plan column links the plan once it exists, in the row of every lane that implements one of its
      phases. Without the `lane-start-guard` hook, `grep -F "| \`<lane>\`" <board>` must print the row.
@@ -63,5 +63,5 @@ herdr pane run <new-pane> "PORT=<port> {{kit.command.dev}}"
 ```
 
 The new pane starts in the lane's worktree; check with `/proc/<pid>/cwd` (macOS: `lsof -p <pid>`) that the server runs
-there, and before stopping one by PID. Stop only a server you started; a port held by
-another server goes to the user.
+there, and before stopping one by PID. Stop only a server you started; another's port
+goes to the user.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "keywords": [
     "claude-code",
     "coding-agents",

package/schemas/jackherd.schema.json

@@ -147,6 +147,11 @@
         "minFreeGb": {
           "type": "number",
           "exclusiveMinimum": 0
+        },
+        "basePort": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535
         }
       },
       "additionalProperties": false

package/src/check/skill-budget-defaults.ts

@@ -57,7 +57,7 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   '.claude/skills/orchestrate/references/lane-handover.md': 360,
   // Ending the agent names `herdr agent prompt <lane> /exit`, the form the merge guard passes (+25).
   '.claude/skills/orchestrate/references/lane-session.md': 285,
-  '.claude/skills/orchestrate/references/lane-setup.md': 380,
+  '.claude/skills/orchestrate/references/lane-setup.md': 440,
   // Open up: an adopted plan is committed like a missing one, and a tracked copy is restored after the merge.
   // Core cut: the question of § 2 step 0 (the adoption's diff round, the approval it is, `<topic>`, a no) (+60).
   // Prose cut, round 2: the question itself moved here from § 2 step 0; measured size plus 5 %.

package/src/config/schema.ts

@@ -603,6 +603,8 @@ export const jackherdConfigSchema = z.strictObject({
       lockFile: lockFilePath.optional(),
       /** Free gigabytes the disk must hold before `jh lane space` lets a new lane install its dependencies; 5 when left out. */
       minFreeGb: z.number().positive().optional(),
+      /** The port `jh lane port` starts counting from when it picks a lane's dev-server port; 3100 when left out. */
+      basePort: z.number().int().min(1).max(65535).optional(),
     })
     .prefault({}),
   models: z.record(z.enum(Object.values(MODEL_ROLE)), modelId).default(DEFAULT_MODELS),

package/src/lane/command.ts

@@ -4,6 +4,7 @@ import { startLaneHintFor } from './start-lane-hint'
 
 const CLOSE = 'close'
 const SPACE = 'space'
+const PORT = 'port'
 const SEND = 'send'
 const BASE = 'base'
 
@@ -15,12 +16,13 @@ const withStartLaneHint = (code: number, args: readonly string[], cwd: string):
 }
 
 /**
- * `jh lane close …` closes a lane, `jh lane space …` checks the disk for a new one, `jh lane send …` sends its prompt
+ * `jh lane close …` closes a lane, `jh lane space …` checks the disk for a new one, `jh lane port …` names its dev-server port, `jh lane send …` sends its prompt
  * file, `jh lane base …` names the ref its worktree starts from, everything else is `jh lane prompt …`. `close` must
  * come first; `jh lane --board b.md close x` reaches the prompt parser and is refused there.
  */
 export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
   if (args[0] === SPACE) return (await import('./space-command')).run(args.slice(1), cwd)
+  if (args[0] === PORT) return (await import('./port-command')).run(args.slice(1), cwd)
   if (args[0] === SEND) return (await import('./send-command')).run(args.slice(1), cwd)
   if (args[0] === BASE)
     return withStartLaneHint(await (await import('./base-command')).run(args.slice(1), cwd), args.slice(1), cwd)

package/src/lane/port-command.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { parseSprintLanes } from '../plan-format'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { boardFor } from '../plans/board-pick'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { isPortListening } from '../plans/port-listening'
+import { readSettings } from '../plans/settings'
+import { asksForHelp } from '../preview/options'
+import { freePortNotListening, LANE_PORT_USAGE, MAX_PORT, parsePortOptions, portsOfRunningLanes } from './port'
+
+/**
+ * `jh lane port [--board <board.md>]`: prints the dev-server port for a new lane, the lowest from `lanes.basePort` that
+ * nothing listens on and no running lane of the board holds. Exit 0 printed, 1 on a wrong line, an unreadable board or
+ * no free port.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(LANE_PORT_USAGE)
+    return 0
+  }
+  try {
+    const { boardPath } = parsePortOptions(args)
+    const root = mainCheckout(cwd)
+    const settings = readSettings([root, worktreeRoot(cwd)])
+    const board = boardFor(boardPath === null ? null : resolve(cwd, boardPath), [root], settings, () => [])
+    if (board.notice) console.error(terminalSafe(board.notice))
+    const reserved = portsOfRunningLanes(parseSprintLanes(readFileSync(board.file, 'utf8'), settings.planLanguage))
+    const port = await freePortNotListening(settings.basePort, reserved, MAX_PORT, isPortListening)
+    if (port === null) throw new Error(`no free port from ${settings.basePort} to ${MAX_PORT}`)
+    console.log(port)
+    return 0
+  } catch (error) {
+    console.error(terminalSafe(error instanceof Error ? error.message : String(error)))
+    return 1
+  }
+}

package/src/lane/port.ts

@@ -0,0 +1,56 @@
+import type { SprintLane } from '../plan-format'
+import { CLI_NAME } from '../version/release'
+
+/** The port the first lane's dev server gets when the config names none (`lanes.basePort`). */
+export const DEFAULT_BASE_PORT = 3100
+
+/** The highest port a machine has. */
+export const MAX_PORT = 65535
+
+/** `boardPath` is null where `--board` was left out: the board is then picked as for `jh herd`. */
+export type PortOptions = { boardPath: string | null }
+
+const BOARD = '--board'
+
+export const LANE_PORT_USAGE = `usage: ${CLI_NAME} lane port [${BOARD} <board.md>]
+
+Prints the dev-server port for a new lane: the lowest port from lanes.basePort of the config (default ${DEFAULT_BASE_PORT})
+that nothing listens on and no lane still running holds in the port column of the board. Rows of cleaned-up lanes
+reserve nothing. Exit 1 and one line when no port up to ${MAX_PORT} is free.`
+
+/** The lowest port from `base` up to `max` (both included) that is not in `taken`; null when there is none. */
+export const firstFreePort = (base: number, taken: ReadonlySet<number>, max: number): number | null => {
+  for (let port = base; port <= max; port += 1) if (!taken.has(port)) return port
+  return null
+}
+
+/**
+ * The lowest port from `base` that is neither in `reserved` nor accepts a connection according to `isListening`; the
+ * probe is asked only for ports the board does not already hold. Null when none is free up to `max`.
+ */
+export const freePortNotListening = async (
+  base: number,
+  reserved: ReadonlySet<number>,
+  max: number,
+  isListening: (port: number) => Promise<boolean>,
+): Promise<number | null> => {
+  const taken = new Set(reserved)
+  for (let port = firstFreePort(base, taken, max); port !== null; port = firstFreePort(port, taken, max)) {
+    if (!(await isListening(port))) return port
+    taken.add(port)
+  }
+  return null
+}
+
+/** The ports the board's lanes that are not cleaned up hold; a lane without a port in its row reserves none. */
+export const portsOfRunningLanes = (lanes: readonly SprintLane[]): Set<number> =>
+  new Set(lanes.flatMap(({ port, closed }) => (closed || port === null ? [] : [port])))
+
+/** Reads `[--board <file>]`; throws with the usage on anything else. */
+export const parsePortOptions = (args: readonly string[]): PortOptions => {
+  if (args.length === 0) return { boardPath: null }
+  const [option, value, ...rest] = args
+  if (option !== BOARD || value === undefined || value.startsWith('--') || rest.length > 0)
+    throw new Error(LANE_PORT_USAGE)
+  return { boardPath: value }
+}

package/src/plans/settings.ts

@@ -4,6 +4,7 @@ import { type JackherdConfig, parseJackherdConfig } from '../config'
 import { PROJECT_CONFIG_PATH } from '../config/location'
 import { readConfig } from '../config/read-config'
 import type { ToneName } from '../config/tones'
+import { DEFAULT_BASE_PORT } from '../lane/port'
 import { DEFAULT_MIN_FREE_GB } from '../lane/space'
 import type { TicketSource } from '../watch/plan-badges'
 import type { SourceShow } from '../watch/sources'
@@ -18,6 +19,8 @@ export type PlansSettings = Pick<
   adapter: JackherdConfig['terminal']['adapter']
   /** Free gigabytes a new lane needs on the disk (`lanes.minFreeGb`). */
   minFreeGb: number
+  /** The port `jh lane port` starts from (`lanes.basePort`). */
+  basePort: number
   fetchIntervalMinutes: number
   /** Whether the running task of a folded lane shimmers; `NO_COLOR` keeps it still whatever this says. */
   shimmer: boolean
@@ -62,6 +65,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   skillPrefix: config.skillPrefix,
   adapter: config.terminal.adapter,
   minFreeGb: config.lanes.minFreeGb ?? DEFAULT_MIN_FREE_GB,
+  basePort: config.lanes.basePort ?? DEFAULT_BASE_PORT,
   fetchIntervalMinutes: config.plans.fetchIntervalMinutes,
   shimmer: config.plans.shimmer,
   linkKinds: config.plans.linkKinds,

package/src/sync/command-context.ts

@@ -10,6 +10,7 @@ import { type KitLocation, locateKit, readKitSource } from './kit-source'
 import { driftExitCodeOf, exitCodeOf, formatReport, SYNC_EXIT } from './report'
 import type { SyncResult } from './sync-result'
 import { detectTools, INSTALLERS, type InstallerName, spawnTool, type ToolPresence } from './tools'
+import { bootstrapHerdrWorktreesFrom } from './worktree-bootstrap'
 
 export type CommandContext = {
   projectRoot: string
@@ -21,6 +22,8 @@ export type CommandContext = {
   log: (line: string) => void
   /** Hooks the herdr plugin in and returns the line to print, if any. Must not throw: a failure is a line, not an error. */
   linkHerdrPlugin: (roots: { packageRoot: string; projectRoot: string }) => string | null
+  /** Prepares the main checkout for the herdr worktree plugin and returns the lines to print; none without herdr or the plugin. Must not throw. */
+  bootstrapWorktrees: (projectRoot: string) => string[]
   /** A yes/no question to the user; null when there is no terminal to ask in. */
   ask: (question: string) => Promise<boolean | null>
   /** A choice among fixed answers; Enter takes `fallback`; null when there is no terminal to ask in. */
@@ -96,6 +99,7 @@ export const defaultContext = (): CommandContext => ({
   locate: () => locateKit(),
   log: (line) => console.log(line),
   linkHerdrPlugin: linkHerdrPluginFrom,
+  bootstrapWorktrees: bootstrapHerdrWorktreesFrom,
   ask: askOnTerminal,
   choose: chooseOnTerminal,
   detectTools: () => detectTools(process.env, process.platform, spawnTool(process.env)),

package/src/sync/command.ts

@@ -111,7 +111,8 @@ const syncProject = (context: CommandContext, accept: string[], dryRun: boolean)
       const foreignLines = foreignSkillLines(result, readForeignSkills(context.projectRoot))
       const foreign = foreignLines.length > 0 ? [foreignLines.join('\n')] : []
       const dryRunNote = dryRun ? [`${CLI_NAME} sync ${CHECK_FLAG}: nothing is written`] : []
-      return { notes: [...dryRunNote, ...foreign], result }
+      const bootstrap = dryRun ? [] : context.bootstrapWorktrees(context.projectRoot)
+      return { notes: [...dryRunNote, ...foreign, ...bootstrap], result }
     },
     dryRun,
   )

package/src/sync/init-command.ts

@@ -201,7 +201,11 @@ const initProjectCommand = async (context: CommandContext, answer: boolean | und
     })
     finished = { init, version: kit.version }
     return {
-      notes: [...configNotes(init.configCreated, PROJECT_CONFIG_PATH, setup), ...notes],
+      notes: [
+        ...configNotes(init.configCreated, PROJECT_CONFIG_PATH, setup),
+        ...notes,
+        ...context.bootstrapWorktrees(context.projectRoot),
+      ],
       result: init.sync,
     }
   })

package/src/sync/worktree-bootstrap.ts

@@ -0,0 +1,150 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { readResolvedConfig } from '../config/read-config'
+import { mainCheckoutOrNull } from '../plans/git'
+import { CLI_NAME } from '../version/release'
+import { herdrBinary, type RunTool, spawnTool } from './tools'
+
+/** The herdr plugin that copies files into a new worktree and runs a setup command there. */
+export const BOOTSTRAP_PLUGIN_ID = 'zerodice0.worktree-bootstrap'
+
+export const BOOTSTRAP_COPY_LIST = '.herdr/worktree-copy.list'
+
+export const BOOTSTRAP_SETUP = '.herdr/worktree-setup.json'
+
+/** The line `.git/info/exclude` gets: the plugin's files belong to this machine, not to the repository. */
+export const BOOTSTRAP_EXCLUDE_LINE = '/.herdr/'
+
+const NODE_VERSION_FILE = '.nvmrc'
+
+const SETUP_TIMEOUT_SECONDS = 900
+
+const COPY_LIST_HEADER = `# Generated by ${CLI_NAME} from lanes.copy in .jackherd/config.json; change the config, not this file.`
+
+export type BootstrapInput = {
+  /** The main checkout: the plugin reads its files there. */
+  mainRoot: string
+  /** `lanes.copy` of the config. */
+  copy: readonly string[]
+  /** `commands.install` of the config, undefined when the project has none. */
+  install: string | undefined
+  herdr: string
+  run: RunTool
+}
+
+/** Whether a `herdr plugin list --json` answer lists the bootstrap plugin as enabled; false for any other shape. */
+export const isBootstrapPluginEnabled = (json: string): boolean => {
+  try {
+    const plugins = (JSON.parse(json) as { result?: { plugins?: unknown } }).result?.plugins
+    return (
+      Array.isArray(plugins) &&
+      plugins.some((plugin) => plugin?.plugin_id === BOOTSTRAP_PLUGIN_ID && plugin.enabled === true)
+    )
+  } catch {
+    return false
+  }
+}
+
+/** The plugin's copy list: one path per line below a header comment. */
+export const copyListContent = (paths: readonly string[]): string => `${[COPY_LIST_HEADER, ...paths].join('\n')}\n`
+
+/** The install command run with the Node version `.nvmrc` names; assumes nvm in `$HOME/.nvm`. */
+export const withNodeVersion = (install: string): string => `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && ${install}`
+
+/** The plugin's setup file: the one command that installs a new worktree's dependencies. */
+export const setupContent = (script: string): string =>
+  `${JSON.stringify(
+    {
+      version: 1,
+      commands: [
+        { name: 'Install dependencies', argv: ['bash', '-c', script], timeout_seconds: SETUP_TIMEOUT_SECONDS },
+      ],
+    },
+    null,
+    2,
+  )}\n`
+
+/** The exclude file with `line` added at its end, or null when it already holds that line. */
+export const withExcludeLine = (current: string, line: string): string | null => {
+  if (current.split('\n').some((each) => each.trim() === line)) return null
+  const separator = current === '' || current.endsWith('\n') ? '' : '\n'
+  return `${current}${separator}${line}\n`
+}
+
+/** The warning for copy paths git does not ignore, which the plugin skips; null when there are none. */
+export const notIgnoredWarning = (paths: readonly string[]): string | null =>
+  paths.length === 0
+    ? null
+    : `The herdr plugin ${BOOTSTRAP_PLUGIN_ID} copies only git-ignored paths and skips: ${paths.join(', ')}. Ignore them or take them off lanes.copy.`
+
+const readOrEmpty = (path: string): string => (existsSync(path) ? readFileSync(path, 'utf8') : '')
+
+/** Writes `content` unless the file already holds it; true when it wrote. */
+const writeIfChanged = (path: string, content: string): boolean => {
+  if (readOrEmpty(path) === content) return false
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, content)
+  return true
+}
+
+const excludeFileOf = (mainRoot: string, run: RunTool): string | null => {
+  const answer = run('git', ['-C', mainRoot, 'rev-parse', '--path-format=absolute', '--git-common-dir'])
+  return answer.exitCode === 0 && answer.output !== '' ? join(answer.output, 'info', 'exclude') : null
+}
+
+const excludeHerdrDirectory = (mainRoot: string, run: RunTool): string[] => {
+  const file = excludeFileOf(mainRoot, run)
+  if (file === null) return []
+  const merged = withExcludeLine(readOrEmpty(file), BOOTSTRAP_EXCLUDE_LINE)
+  if (merged === null) return []
+  writeIfChanged(file, merged)
+  return [`Added ${BOOTSTRAP_EXCLUDE_LINE} to the git exclude file.`]
+}
+
+/** Exit 1 is git's "not ignored"; any other failure says nothing about the path and is not reported. */
+const notIgnored = ({ mainRoot, run }: BootstrapInput, path: string): boolean =>
+  run('git', ['-C', mainRoot, 'check-ignore', '-q', '--', path]).exitCode === 1
+
+const setupScript = (mainRoot: string, install: string): string =>
+  existsSync(join(mainRoot, NODE_VERSION_FILE)) ? withNodeVersion(install) : install
+
+const writeFiles = ({ mainRoot, copy, install }: BootstrapInput): string[] => {
+  const written: string[] = []
+  if (copy.length > 0 && writeIfChanged(join(mainRoot, BOOTSTRAP_COPY_LIST), copyListContent(copy)))
+    written.push(`Wrote ${BOOTSTRAP_COPY_LIST} from lanes.copy.`)
+  if (
+    install !== undefined &&
+    writeIfChanged(join(mainRoot, BOOTSTRAP_SETUP), setupContent(setupScript(mainRoot, install)))
+  )
+    written.push(`Wrote ${BOOTSTRAP_SETUP} from commands.install.`)
+  return written
+}
+
+/**
+ * Prepares the main checkout for the herdr plugin `zerodice0.worktree-bootstrap`: its copy list and setup command from
+ * the config, and the `.herdr/` directory in the git exclude file. Does nothing without herdr or with the plugin
+ * missing or disabled. A file that is already as it should be is not rewritten. Returns the lines to print.
+ */
+export const bootstrapHerdrWorktrees = (input: BootstrapInput): string[] => {
+  const listing = input.run(input.herdr, ['plugin', 'list', '--json'])
+  if (listing.missing || listing.exitCode !== 0 || !isBootstrapPluginEnabled(listing.output)) return []
+  const warning = notIgnoredWarning(input.copy.filter((path) => notIgnored(input, path)))
+  return [...writeFiles(input), ...excludeHerdrDirectory(input.mainRoot, input.run), ...(warning ? [warning] : [])]
+}
+
+/** `bootstrapHerdrWorktrees` for the project at `projectRoot` (also a lane's worktree), with the real herdr and git. */
+export const bootstrapHerdrWorktreesFrom = (projectRoot: string): string[] => {
+  const mainRoot = mainCheckoutOrNull(projectRoot) ?? projectRoot
+  try {
+    const { config } = readResolvedConfig([...new Set([projectRoot, mainRoot])])
+    return bootstrapHerdrWorktrees({
+      mainRoot,
+      copy: config.lanes.copy,
+      install: config.commands.install,
+      herdr: herdrBinary(process.env),
+      run: spawnTool(process.env),
+    })
+  } catch (err) {
+    return [`Could not prepare the herdr worktree plugin: ${err instanceof Error ? err.message : String(err)}`]
+  }
+}