jackherd 1.4.0 → 1.6.0

package/kit/hooks/hooks/merge-guard/run.ts

@@ -1,8 +1,9 @@
 import { readFileSync } from 'node:fs'
 import { isAbsolute, relative } from 'node:path'
 import { approvedBranches, parseTranscript } from './approval'
+import { allFilesMatch, changedFilesOf } from './check-free'
 import { decideBashCommand, type GuardPolicy, type MergeGuardDecision } from './decision'
-import { headBranchOf } from './pull-request'
+import { parseHeadBranch, parseRepositoryFacts, type RepositoryFacts, viewPullRequest } from './pull-request'
 import { type GuardSettings, readGuardSettings } from './settings'
 
 type HookInput = { tool_input?: { command?: unknown }; transcript_path?: unknown; cwd?: unknown }
@@ -25,13 +26,21 @@ const isInside = (directory: string, project: string): boolean => {
   return path === '' || (!path.startsWith('..') && !isAbsolute(path))
 }
 
+/** Every file of the pull request, as GitHub lists them, matches `merge.withoutChecks`. */
+const isCheckFree = (
+  pullRequest: number,
+  facts: RepositoryFacts | undefined,
+  withoutChecks: readonly string[],
+  directory: string,
+): boolean => facts !== undefined && allFilesMatch(changedFilesOf(pullRequest, directory, facts) ?? [], withoutChecks)
+
 const policyFor = (input: HookInput, label: string, projectDirectory: string): GuardPolicy => {
   const settings = readGuardSettings(projectDirectory)
   const directory = typeof input.cwd === 'string' && input.cwd !== '' ? input.cwd : projectDirectory
-  const headBranches = new Map<number, string | undefined>()
-  const headBranch = (pullRequest: number): string | undefined => {
-    if (!headBranches.has(pullRequest)) headBranches.set(pullRequest, headBranchOf(pullRequest, directory))
-    return headBranches.get(pullRequest)
+  const views = new Map<number, string | undefined>()
+  const viewOf = (pullRequest: number): string => {
+    if (!views.has(pullRequest)) views.set(pullRequest, viewPullRequest(pullRequest, directory))
+    return views.get(pullRequest) ?? ''
   }
   let approved: Set<string> | undefined
   return {
@@ -39,9 +48,14 @@ const policyFor = (input: HookInput, label: string, projectDirectory: string): G
     isMergeApproved: (pullRequest) => {
       if (!isInside(directory, projectDirectory)) return false
       const branches = (approved ??= approvedBranchesFrom(input.transcript_path, settings, label))
-      if (branches.size === 0) return false
-      const branch = headBranch(pullRequest)
-      return branch !== undefined && branches.has(branch)
+      if (branches.size === 0 && settings.withoutChecks.length === 0) return false
+      // The branch lookup also proves the pull request is open and from this repository; both paths need that.
+      const view = viewOf(pullRequest)
+      const branch = parseHeadBranch(view)
+      if (branch === undefined) return false
+      return (
+        branches.has(branch) || isCheckFree(pullRequest, parseRepositoryFacts(view), settings.withoutChecks, directory)
+      )
     },
   }
 }

package/kit/hooks/hooks/merge-guard/settings.ts

@@ -5,17 +5,30 @@ import { join } from 'node:path'
 export type GuardSettings = {
   commands: string[]
   selfMerge: { offer: boolean; approvalMinutes: number }
+  /** Path patterns of a pull request that is merged without checks; empty means every merge waits for them. */
+  withoutChecks: string[]
 }
 
 export const DEFAULT_SETTINGS: GuardSettings = {
   commands: ['gh pr merge', 'gh workflow run'],
   selfMerge: { offer: true, approvalMinutes: 180 },
+  withoutChecks: [],
 }
 
 const CONFIG_PATH = join('.jackherd', 'config.json')
 export const GUARDED_COMMAND = /^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*){1,3}$/
 export const MAX_MINUTES = 1440
 
+/** The same rules as `checkFreePattern` in the config schema, which the hook cannot import. */
+const isCheckFreePattern = (value: unknown): value is string =>
+  typeof value === 'string' &&
+  /^[A-Za-z0-9_.*/-]+$/.test(value) &&
+  !value.startsWith('/') &&
+  !value.split('/').includes('..') &&
+  value.split('/').some((segment) => /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(segment))
+
+const isPatternList = (value: unknown): value is string[] => Array.isArray(value) && value.every(isCheckFreePattern)
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
 
@@ -25,13 +38,13 @@ const isCommandList = (value: unknown): value is string[] =>
 const isMinutes = (value: unknown): value is number =>
   typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_MINUTES
 
-/** The `guard` section of the first config that exists; the hook has no schema library, `jh` validates the file. */
-const readGuardSection = (directories: string[]): Record<string, unknown> => {
+/** The first config that exists; the hook has no schema library, `jh` validates the file. */
+const readConfig = (directories: string[]): Record<string, unknown> => {
   const path = directories.map((directory) => join(directory, CONFIG_PATH)).find((candidate) => existsSync(candidate))
   if (!path) return {}
   try {
     const config: unknown = JSON.parse(readFileSync(path, 'utf8'))
-    return isRecord(config) && isRecord(config.guard) ? config.guard : {}
+    return isRecord(config) ? config : {}
   } catch {
     return {}
   }
@@ -42,7 +55,9 @@ const readGuardSection = (directories: string[]): Record<string, unknown> => {
  * malformed keeps its default, so a broken config guards more, never less; only an empty list switches the guard off.
  */
 export const readGuardSettings = (projectDirectory: string, home: string = homedir()): GuardSettings => {
-  const section = readGuardSection([projectDirectory, home])
+  const config = readConfig([projectDirectory, home])
+  const section = isRecord(config.guard) ? config.guard : {}
+  const merge = isRecord(config.merge) ? config.merge : {}
   const selfMerge = isRecord(section.selfMerge) ? section.selfMerge : {}
   return {
     commands: isCommandList(section.commands) ? section.commands : DEFAULT_SETTINGS.commands,
@@ -52,5 +67,6 @@ export const readGuardSettings = (projectDirectory: string, home: string = homed
         ? selfMerge.approvalMinutes
         : DEFAULT_SETTINGS.selfMerge.approvalMinutes,
     },
+    withoutChecks: isPatternList(merge.withoutChecks) ? merge.withoutChecks : DEFAULT_SETTINGS.withoutChecks,
   }
 }

package/kit/rules/rules/kit/code-style.md

@@ -17,6 +17,7 @@ The formatter and linter config is the authority; these are the conventions it e
 - **All code in English**: file names, identifiers, type and component names, comments. User-facing strings go through the project's i18n system.
 - **Commit messages in English**, subject and body. The subject is a Conventional Commit (`fix(scope): …`); the body explains cause and consequence in prose.
 - **Plans and ADRs** are written in {{kit.planLanguage}}.
+- **Replies to the user** are in {{kit.responseLanguage}}, addressing the user with {{kit.responseAddress}}. That holds for every answer, every question and every report to the user; it does not change what is written into code, commits or plans.
 
 ## Naming
 

package/kit/workflow/skills/follow/SKILL.md

@@ -6,7 +6,7 @@ argument-hint: 'What to follow, e.g. a ticket key, an issue or a query'
 
 If `.claude/project/follow.md` exists, read it first. It extends this skill for this project and wins where the two disagree.
 
-You add one entry to `watch.sources`, so that `jh watch` reports a new or changed entry of an external service as `=== source <name> …`. You run only reading commands; the one file you write is the project's `.jackherd/config.json` in the main checkout, and only after the user approved the entry. How sources work, their fields and limits: the kit's README, section **Source reports** and **Recipes**, in the installed package (`"$(dirname "$(readlink -f "$(command -v jh)")")/../README.md"`). Read those two sections; do not copy a recipe from memory.
+You add one entry to `watch.sources`, so that `jh watch` reports a new or changed entry of an external service as `=== source <name> …`. You run only reading commands; the one file you write is the project's `.jackherd/config.json` in the main checkout, and only after the user approved the entry. How sources work, their fields and limits: the jackherd README, section **Source reports** and **Recipes**, in the installed package (`"$(dirname "$(readlink -f "$(command -v jh)")")/../README.md"`). Read those two sections; do not copy a recipe from memory.
 
 ## 1. Ask
 
@@ -20,7 +20,7 @@ One `AskUserQuestion` round in {{kit.responseLanguage}}, only for what the argum
 
 ## 2. Check, read only
 
-- The tool: `command -v <tool>` for the recipe's program (`curl`, the service's CLI).
+- The tool: `command -v <tool>` for the recipe's program (`curl`, the service's CLI, and `bun` for a recipe with a script).
 - The login: the tool's own status command where it has one. For a token in an environment variable only whether it is set: `test -n "$<VARIABLE>" && echo set || echo missing`. Never print, echo or pass on a token's value, and never read a file that holds one.
 
 Anything missing goes to the user as the command to run themselves (`! <command>`); wait until they did, then check again.
@@ -29,7 +29,14 @@ Anything missing goes to the user as the command to run themselves (`! <command>
 
 Before filling, read the help of the installed CLI version for every command the recipe calls (`acli jira workitem search --help` and `workitem view --help`, `gh issue list --help`) and confirm that the fields and options the entry needs exist there. Read the provider's web documentation only when the help leaves it open or no recipe fits. A recipe is a starting point; the installed version decides.
 
-Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane` and `ignoreAuthors` where chosen. A recipe that needs a script (a token handed on stdin, or one call per item): write it to the scratchpad first, never into the repository before step 4.
+Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane` and `ignoreAuthors` where chosen. A recipe that needs a script (a token from the environment, or one call per item) gets TypeScript run by Bun: write it to the scratchpad first as `<name>.ts`, never into the repository before step 4, and let the entry's `command` be `["bun", "scripts/sources/<name>.ts"]`. The script:
+
+- bounds every request and every call of a tool with `AbortSignal.timeout(20_000)`, where a shell recipe would use `--max-time`;
+- reads a token only from `process.env`, and never prints it, passes it as an argument or writes it into an output;
+- ends with `process.exit(1)` when the token is missing, the answer is not 2xx (or carries an `errors` list, as GraphQL does with a 200) or a tool it calls fails, without printing the answer's body, so a failure is an exit code and never an empty list the watcher would take for a source with nothing new;
+- prints one JSON value on stdout and nothing else.
+
+A recipe that needs no script (`gh …`, `curl` on a public page, `curl --netrc`) stays a direct command. Write `bun` as the program, never an absolute path to it: the watcher starts a source without a shell and resolves `bun` to the Bun that runs the watcher, and a path in the config would differ from machine to machine.
 
 Write the entry as one JSON object to a draft file in the scratchpad and run, from the main checkout:
 

package/kit/workflow/skills/orchestrate/SKILL.md

@@ -122,7 +122,8 @@ stay approval-bound (§ 5, § 6).
    `git add <paths>`, `git commit -m "docs(plans): add the <topic> plan"` (English, like every commit
    message), `git push -u origin docs/plan-<topic>`, open the PR per `pull-requests.md`, `cd` back,
    and `git worktree remove {{kit.worktreeDirectory}}/docs-plan-<topic>`. The copies in the main
-   checkout stay until the PR is merged (§ 6). Answered no: no lane of these plans starts; say why,
+   checkout stay until the PR is merged (§ 6). When this PR is merged by self-merge, it needs no check wait if it qualifies under
+   **Merging without checks** (§ 5, **Self-merge**, step 2). Answered no: no lane of these plans starts; say why,
    and do not ask again in this run unless the user raises it.
 1. **Collision check.** Compare the lane's `{{kit.heading.writes}}` set and serial markers with every
    running lane. Shared paths run one after the other; migrations, database pushes and bumps of the
@@ -149,8 +150,12 @@ stay approval-bound (§ 5, § 6).
    - **Plugin in place:** `herdr plugin list` shows `zerodice0.worktree-bootstrap` as `enabled`,
      and the main checkout has `.herdr/worktree-copy.list` (for step 3) or
      `.herdr/worktree-setup.json` (for step 4). Skip the step the plugin's file covers. Before
-     step 5, check the result: `cmp -s` per env file, and the dependencies directory exists in the
-     worktree. Poll that check every 10 seconds for up to 2 minutes; if it still fails, do the step below yourself.
+     step 5, check the result: `cmp -s` per env file, and the dependencies are all there. Run
+     `{{kit.lanes.verifyInstall}}` in the worktree, as a pane command with the `-OK`/`-FAIL` marker of step 4.
+     It ends with an exit code, so there is nothing to poll; with bun, pnpm and yarn it returns quickly when nothing
+     is missing.
+     Never look for a directory such as `node_modules/<package>`: some package managers keep a workspace's
+     dependencies out of the root. If the command fails, do the step below yourself; if that fails too, report it.
    - **Plugin missing, disabled, or its file absent:** do the step as written below.
 
    Copy the untracked files every lane needs (`lanes.copy` in the jackherd config, else what
@@ -287,7 +292,9 @@ has no value, and `--coordinator <name>` names you. Without either the watcher l
 
 In a stream each report is printed in one piece, so it arrives as one message, and the watcher
 keeps running. The heartbeat there is one line, `=== heartbeat <time> · <lane> <status> · …`, due
-after that many minutes without a report. `lane added: <name>` and `lane removed: <name>` mark a
+after that many minutes without a report. A lane that is `working` carries its plan progress after a colon (`<lane> working: P12 7/12`, the current phase and its ticks)
+only when the count moved since the last heartbeat. Pass it on as it is. A working lane without a number
+has not moved (or has no plan): read its screen yourself when that lasts. `lane added: <name>` and `lane removed: <name>` mark a
 change of the found lanes. A lane's agent is watched from the state it shows when it first appears,
 so an agent that starts out idle does not fire; a lane whose agent exits fires as `no longer listed`,
 also when it leaves the found lanes with it.
@@ -518,16 +525,24 @@ When the user picked `"{{kit.guard.selfMergeLabel}}"` for a PR:
 1. Commit, push and open the PR as in step 4. Enter in the board's `{{kit.heading.history}}` that the
    user approved this PR with self-merge (time, lane, PR number), so the approval has a record outside
    the chat.
-2. Wait for the checks in the background, never in the foreground (§ 4): a Bash call
+2. **Merging without checks.** The paths a PR may carry to be merged without waiting for checks are
+   `{{kit.merge.withoutChecks}}` (`merge.withoutChecks` in the config; `none` means every merge waits).
+   Unless `none`, list the PR's files with `gh pr diff <n> --name-only` and compare each one with the
+   patterns yourself. When **every** file matches, go straight to step 4: no checks wait, because
+   the config says these paths need none. One file outside, an empty list, or a failed `gh` call:
+   go on with step 3. The merge guard reads the file list from GitHub itself and lets that
+   merge pass without a question only when it agrees; if it asks, the dialog is the user's (step 5).
+   This is the rule for the documents of a plan commit as well (§ 2 step 0).
+3. Wait for the checks in the background, never in the foreground (§ 4): a Bash call
    `gh pr checks <n> --watch` with `run_in_background: true`, then work on until it reports.
-3. Green: `gh pr merge <n> --squash --delete-branch`, with the plain PR number and without `-R`,
+4. Green (or a PR that qualified in step 2): `gh pr merge <n> --squash --delete-branch`, with the plain PR number and without `-R`,
    `--repo` or `--admin`. The merge guard lets exactly this command through for the approved branch,
    for `guard.selfMerge.approvalMinutes` after the answer. Red, or checks that never finish: do not
    merge, report to the user with the failing check and the lane's next step.
-4. When the guard asks anyway (the approval lapsed, the branch differs, the command carries an
+5. When the guard asks anyway (the approval lapsed, the branch differs, the command carries an
    option it does not cover), the dialog is the user's. Do not confirm it for them and do not look
    for a way around it: tell them what the PR waits for.
-5. After the merge, one line to the user (PR, merge commit, checks), then § 6 as for any merge.
+6. After the merge, one line to the user (PR, merge commit, checks or "no checks: all files match merge.withoutChecks"), then § 6 as for any merge.
 
 Self-merge never covers `gh workflow run` (a release, a deploy) or another PR: each of those asks
 the user every time.
@@ -573,7 +588,9 @@ After its last PR is merged and the user agreed:
    locked (`git worktree list --porcelain` shows `locked claude session`) needs `git worktree unlock`
    first; check the session has ended.
 4. Delete the local branch; the remote one is usually gone with the merge (`git ls-remote --heads`).
-5. Record the lane's end in the board's `{{kit.heading.history}}`.
+5. Record the lane's end in the board's `{{kit.heading.history}}`, and mark every row of the lane by appending
+   `, {{kit.word.laneClosed}} <date>` to its name cell, in the same documentation PR as the history entry. The plans view lists a lane without a worktree as waiting until its
+   name cell carries that word and its plan has open phases.
 
 Close only lanes you started or the user named.
 

package/package.json

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

package/schemas/jackherd.schema.json

@@ -13,6 +13,14 @@
         "en"
       ]
     },
+    "responseAddress": {
+      "default": "informal",
+      "type": "string",
+      "enum": [
+        "informal",
+        "formal"
+      ]
+    },
     "planLanguage": {
       "default": "en",
       "type": "string",
@@ -486,6 +494,21 @@
       },
       "additionalProperties": false
     },
+    "merge": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "withoutChecks": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.*/-]+$"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "hints": {
       "default": {},
       "type": "object",

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { pathToFileURL } from 'node:url'
+import { locateKit } from './sync/kit-source'
 import { CLI_NAME } from './version/release'
 
 export type CommandModule = { run: (args: string[]) => Promise<number> | number }
@@ -8,6 +9,7 @@ export type CommandTable = Record<string, () => Promise<CommandModule>>
 
 export type Resolution =
   | { kind: 'run'; name: string; args: string[] }
+  | { kind: 'version' }
   | { kind: 'usage'; exitCode: number; message: string }
 
 /** One line per command; each entry lazily imports the module that exports its `run`. */
@@ -25,14 +27,25 @@ export const COMMANDS: CommandTable = {
 export const resolveCommand = (argv: string[], table: CommandTable): Resolution => {
   const [name, ...args] = argv
   const names = Object.keys(table)
-  const usage = `Usage: ${CLI_NAME} <command> [args]\nCommands: ${names.length > 0 ? names.join(', ') : '(none yet)'}`
+  const usage = `Usage: ${CLI_NAME} <command> [args]\n       ${CLI_NAME} --version\nCommands: ${names.length > 0 ? names.join(', ') : '(none yet)'}`
+  if (name === '--version' || name === '-v') return { kind: 'version' }
   if (!name || name === '--help' || name === '-h') return { kind: 'usage', exitCode: name ? 0 : 1, message: usage }
   if (!names.includes(name)) return { kind: 'usage', exitCode: 1, message: `Unknown command: ${name}\n${usage}` }
   return { kind: 'run', name, args }
 }
 
-export const main = async (argv: string[], table: CommandTable = COMMANDS): Promise<number> => {
+const installedVersion = async (): Promise<string> => (await locateKit()).version
+
+export const main = async (
+  argv: string[],
+  table: CommandTable = COMMANDS,
+  readVersion: () => Promise<string> = installedVersion,
+): Promise<number> => {
   const resolution = resolveCommand(argv, table)
+  if (resolution.kind === 'version') {
+    console.log(await readVersion())
+    return 0
+  }
   if (resolution.kind === 'usage') {
     console.log(resolution.message)
     return resolution.exitCode

package/src/config/detect.ts

@@ -88,6 +88,21 @@ const DERIVED_COMMANDS: Record<PackageManager, DerivedCommands> = {
   },
 }
 
+/** The install command of each manager that stops at the lock file instead of changing it. */
+const FROZEN_INSTALL: Record<string, string> = {
+  [DERIVED_COMMANDS.bun.install]: 'bun install --frozen-lockfile',
+  [DERIVED_COMMANDS.yarn.install]: 'yarn install --immutable',
+  [DERIVED_COMMANDS.pnpm.install]: 'pnpm install --frozen-lockfile',
+  [DERIVED_COMMANDS.npm.install]: 'npm ci',
+}
+
+/**
+ * The check that a worktree's dependencies are all there: the manager's install with the lock file frozen, fast when
+ * nothing is missing, fetching what is, failing when the lock file and `package.json` disagree. An install command the
+ * project set itself is returned as it is, since its flags are not known.
+ */
+export const frozenInstallCommand = (install: string): string => FROZEN_INSTALL[install] ?? install
+
 /** The bun defaults of the schema, so a repository Bun runs and one detection skips agree. */
 export const BUN_COMMANDS = DERIVED_COMMANDS.bun
 

package/src/config/schema.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 import { checkConfigSchema } from '../check/schema'
 import { claudePath, WORKTREES_DIRECTORY } from '../claude/paths'
-import { PLAN_LANGUAGE } from '../vocabulary'
+import { PLAN_LANGUAGE, RESPONSE_ADDRESS } from '../vocabulary'
 import { SOURCE_FIELD } from '../watch/source-fields'
 import { isSourcePath } from '../watch/source-path'
 import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
@@ -192,6 +192,32 @@ const guardedCommand = z
   .string()
   .regex(/^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*){1,3}$/, 'a program and one to three plain words, such as gh pr merge')
 
+/**
+ * A path pattern for a pull request that needs no checks: plain path words with wildcards, at least one whole path
+ * segment without a wildcard that starts with a letter or digit (a docs folder, then wildcards, then a file ending, but
+ * not wildcards alone nor any pattern whose only literal is a dot), no `..`, not absolute. Braces, classes and
+ * negation stay out, so the hook, which has no schema library, reads exactly what this accepts.
+ */
+const checkFreePattern = z
+  .string()
+  .regex(/^[A-Za-z0-9_.*/-]+$/, 'path words with * and ** only, such as docs/**/*.md')
+  .refine(
+    (pattern) => !pattern.startsWith('/') && !pattern.split('/').includes('..'),
+    'a relative path that stays inside the repository',
+  )
+  .refine(
+    (pattern) => pattern.split('/').some((segment) => /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(segment)),
+    'a pattern with a whole path segment that is no wildcard, such as docs/**/*.md',
+  )
+
+const mergeSchema = z.strictObject({
+  /**
+   * Paths of pull requests that are merged without waiting for checks: when every file of the pull request matches one
+   * of them, `/orchestrate` merges at once and the merge guard does not ask. Empty means every merge waits for checks.
+   */
+  withoutChecks: z.array(checkFreePattern).default([]),
+})
+
 const guardSchema = z.strictObject({
   /**
    * The commands the merge guard hook asks the user about before they run, also behind options before the verb, a chain,
@@ -231,6 +257,8 @@ const contextSchema = z
 export const jackherdConfigSchema = z.strictObject({
   $schema: z.string().optional(),
   responseLanguage: language.default(PLAN_LANGUAGE.en),
+  /** Whether replies address the user with the familiar or the polite form where the language has both (German: du or Sie). */
+  responseAddress: z.enum(Object.values(RESPONSE_ADDRESS)).default(RESPONSE_ADDRESS.informal),
   planLanguage: language.default(PLAN_LANGUAGE.en),
   planDirectory: z.string().min(1).default('docs/plans'),
   /** Where the boards live and what the project calls them. */
@@ -307,6 +335,8 @@ export const jackherdConfigSchema = z.strictObject({
     .prefault({}),
   /** Read by the merge guard hook, which asks before the listed commands run, and by `/orchestrate`. */
   guard: guardSchema.prefault({}),
+  /** Read by `/orchestrate` and by the merge guard hook. */
+  merge: mergeSchema.prefault({}),
   /** Read by the `ask-hint` hook. */
   hints: hintsSchema.prefault({}),
   /** Read by `jh check`; validated here too, so a typo fails every command alike. */

package/src/plans/lane-standing.ts

@@ -0,0 +1,59 @@
+import type { LaneProgress, SprintLane } from '../plan-format'
+import { PLAN_VOCABULARY } from '../vocabulary'
+
+/**
+ * `active` lanes are drawn in full; `noAgent` is a worktree nobody works in, still listed; `waiting` has no
+ * worktree and still something to do; `closed` has nothing left and is not drawn.
+ */
+export const LANE_STANDING = { active: 'active', noAgent: 'no-agent', waiting: 'waiting', closed: 'closed' } as const
+export type LaneStanding = (typeof LANE_STANDING)[keyof typeof LANE_STANDING]
+
+type StandingInput = {
+  progress: Pick<LaneProgress, 'lane' | 'done' | 'total'>
+  status: { agent: string | null; branch: string | null }
+  pullRequests: readonly unknown[]
+}
+
+const NO_STARTS_AFTER = new Set(['', '-', '–', '—'])
+
+/** The starts-after cell of the lane's newest row that has one, trimmed. */
+const startsAfterOf = ({ steps }: SprintLane): string =>
+  steps
+    .map((step) => step.startsAfter.trim())
+    .reverse()
+    .find((cell) => !NO_STARTS_AFTER.has(cell)) ?? ''
+
+const STARTS_NOW = Object.values(PLAN_VOCABULARY).flatMap(({ startsNow }) => startsNow)
+
+/** Every language's word counts: the language a view answers in is not the language the board is written in. */
+const startsNow = (cell: string): boolean => {
+  const lowered = cell.toLowerCase()
+  return STARTS_NOW.some(
+    (word) => lowered === word || (lowered.startsWith(word) && /^\W/.test(lowered.slice(word.length))),
+  )
+}
+
+/** What a waiting lane waits for: its starts-after text as the board writes it; null when it may start at once. */
+export const waitingNote = (lane: SprintLane): string | null => {
+  const cell = startsAfterOf(lane)
+  return cell === '' || startsNow(cell) ? null : cell
+}
+
+const hasOpenWork = (progress: StandingInput['progress']): boolean => {
+  if (progress.total > 0) return progress.done < progress.total
+  return waitingNote(progress.lane) !== null
+}
+
+/**
+ * Where a lane stands on the board. The cleaned-up mark goes first: it closes a lane, unless an agent, a worktree
+ * or a pull request is still there, which keeps it listed. Then an agent or an open pull request makes a lane
+ * active and a worktree alone lists it. Without a worktree a lane waits while it has open work, else it is closed.
+ */
+export const laneStanding = (input: StandingInput): LaneStanding => {
+  const { progress, status, pullRequests } = input
+  const working = status.agent !== null || pullRequests.length > 0
+  if (progress.lane.closed) return working || status.branch !== null ? LANE_STANDING.noAgent : LANE_STANDING.closed
+  if (working) return LANE_STANDING.active
+  if (status.branch !== null) return LANE_STANDING.noAgent
+  return hasOpenWork(progress) ? LANE_STANDING.waiting : LANE_STANDING.closed
+}

package/src/plans/layout.ts

@@ -28,6 +28,7 @@ import {
   type WatchBadges,
   type WatchHealth,
 } from '../watch/plan-badges'
+import { LANE_STANDING, type LaneStanding, laneStanding, waitingNote } from './lane-standing'
 import { chipKey, type LinkChip } from './link-chips'
 import { type PlannedPlan, phaseList, plannedPhaseCount } from './planned'
 import { CHECKS, type ChecksState, type PullRequest, pullRequestKey } from './pull-requests'
@@ -753,18 +754,27 @@ const laneBlock = (
   return joinFrames([row, ...view.pullRequests.map((pullRequest) => pullRequestFrame(pullRequest, context)), content])
 }
 
-/** A closed lane, or one with no agent and no open pull request, has nothing to act on; it is listed in the closing block. */
-const isParked = ({ progress, status, pullRequests }: LaneView): boolean =>
-  progress.lane.closed || (status.agent === null && pullRequests.length === 0)
+const laneTally = ({ progress }: Pick<LaneView, 'progress'>): string =>
+  progress.total > 0 ? `${progress.lane.name} ${progress.done}/${progress.total}` : progress.lane.name
 
-const parkedItem = ({ progress }: LaneView): string => {
-  const { name, steps } = progress.lane
-  const hasPlan = steps.some((step) => step.planHref)
-  const label =
-    progress.total > 0 ? `${name} ${progress.done}/${progress.total}` : hasPlan ? name : `${name} (${TEXTS.noPlan})`
+const parkedItem = (view: Pick<LaneView, 'progress'>): string => {
+  const hasPlan = view.progress.lane.steps.some((step) => step.planHref)
+  const label = view.progress.total > 0 || hasPlan ? laneTally(view) : `${laneTally(view)} (${TEXTS.noPlan})`
   return label.replaceAll(' ', NON_BREAKING_SPACE)
 }
 
+/** `  name 2/5  after P1 gemergt`: one dimmed row per lane that waits, its wait cut at the pane's edge. */
+const waitingBlock = (lanes: LaneView[], width: number): string[] => {
+  if (lanes.length === 0) return []
+  const head = paint.dim(`${NO_AGENT_SYMBOL} ${TEXTS.waiting(lanes.length)}`)
+  const rows = lanes.map((lane) => {
+    const note = waitingNote(lane.progress.lane)
+    const item = laneTally(lane)
+    return paint.dim(fit(note === null ? `  ${item}` : `  ${item}  ${TEXTS.startsAfter(plain(note))}`, width))
+  })
+  return [head, ...rows]
+}
+
 /** `· no agent (6)  name 3/9 · other 1/4`: one wrapping block for every parked lane, each with its progress. */
 const parkedBlock = (lanes: LaneView[], width: number): string[] => {
   if (lanes.length === 0) return []
@@ -837,19 +847,29 @@ const laneColumnsOf = (lanes: LaneView[]): LaneColumns => ({
   right: Math.max(0, ...lanes.map((lane) => visibleLength(laneRight(lane)))),
 })
 
+/** The lanes by what the view does with them; closed lanes are in none of the three groups. */
+const partitionLanes = (lanes: LaneView[]): Record<'active' | 'waiting' | 'noAgent', LaneView[]> => {
+  const standing = (wanted: LaneStanding) => lanes.filter((lane) => laneStanding(lane) === wanted)
+  return {
+    active: standing(LANE_STANDING.active),
+    waiting: standing(LANE_STANDING.waiting),
+    noAgent: standing(LANE_STANDING.noAgent),
+  }
+}
+
 /**
  * Title and clock on top, the key hint at the bottom (with the legend after `?`), and in between one
  * block per lane: the lane line with its total bar, and for an open lane the phase rows. Folded lanes are
- * one line each, every lane block after the first is preceded by a dimmed rule, and lanes without an
- * agent share the closing block.
+ * one line each and every lane block after the first is preceded by a dimmed rule. Lanes that wait and
+ * lanes with a worktree but no agent each share a closing block; finished lanes are not drawn.
  */
 export const renderScreen = (
   { title, time, lanes, planned, watch, language = PLAN_LANGUAGE.en }: OverviewView,
   state: Selection,
   width: number,
 ): Screen => {
-  const active = lanes.filter((lane) => !isParked(lane))
-  const parked = parkedBlock(lanes.filter(isParked), width)
+  const { active, waiting, noAgent } = partitionLanes(lanes)
+  const parked = [...waitingBlock(waiting, width), ...parkedBlock(noAgent, width)]
   const columns = laneColumnsOf(active)
   const badgeTexts = BADGE_TEXTS[language]
   const blocks = active.map((lane) => laneBlock(lane, state, width, columns, badgeTexts))

package/src/plans/texts.ts

@@ -8,6 +8,8 @@ import { NO_AGENT_WORD, PHASE_COUNT } from './symbols'
  */
 export type PlanTexts = {
   noAgent: string
+  waiting: (lanes: number) => string
+  startsAfter: (wait: string) => string
   noPlan: string
   noWorktree: string
   noRow: string
@@ -70,6 +72,8 @@ export const boardTexts = (term: string) => ({
 
 export const TEXTS: PlanTexts = {
   noAgent: NO_AGENT_WORD,
+  waiting: (lanes) => `waiting (${lanes})`,
+  startsAfter: (wait) => `after ${wait}`,
   noPlan: 'no plan',
   noWorktree: 'no worktree',
   noRow: 'no row in lanes',
@@ -94,7 +98,7 @@ export const TEXTS: PlanTexts = {
   hint: '↑↓ select  →← open  a all  n notes  s html  q quit  ? help',
   legend: [
     'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a 📎 chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
-    '⚡ working · ❓ blocked, waits for you · 📨 done = the agent finished its answer, not the lane · ⏸ idle · · no agent · working and blocked lanes open by themselves, → ← overrule until the status changes',
+    '⚡ working · ❓ blocked, waits for you · 📨 done = the agent finished its answer, not the lane · ⏸ idle · · no agent = a worktree nobody works in · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · working and blocked lanes open by themselves, → ← overrule until the status changes',
     `n/m = m checkboxes of the phase, n ticked (the phase being worked on is yellow; ticked, not merged = all ticked in the worktree, not on the base branch yet) · ${PHASE_COUNT.allTicked} n/n all ticked · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · n shows or hides the notes of a lane · s opens every lane and plan as one HTML page · ⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main`,
   ],
 }

package/src/sync/emptied-directories.ts

@@ -0,0 +1,19 @@
+const ancestorsOf = (path: string): string[] => {
+  const segments = path.split('/').slice(0, -1)
+  return segments.map((_, index) => segments.slice(0, index + 1).join('/'))
+}
+
+const depth = (path: string): number => path.split('/').length
+
+const deepestFirst = (left: string, right: string): number => depth(right) - depth(left) || left.localeCompare(right)
+
+/**
+ * The directories a sync may clean up after it removed `removed`: every directory above those files, deepest first,
+ * except the ones a file in `kept` still lies in. The lock proves these directories were the kit's, since the kit
+ * wrote a file into each of them; whether one is really empty is for the file system to say.
+ */
+export const emptiedDirectories = (removed: readonly string[], kept: readonly string[]): string[] => {
+  const stillUsed = new Set(kept.flatMap(ancestorsOf))
+  const candidates = new Set(removed.flatMap(ancestorsOf))
+  return [...candidates].filter((directory) => !stillUsed.has(directory)).sort(deepestFirst)
+}