@joshuafolkken/kit 1.998.0 → 1.1005.0

package/.claude/skills/workflow-commands/backlogrun-child.md

@@ -295,7 +295,7 @@ answer=$(pnpm josh run:hold 926)   # alias: josh rh ; one token on stdout, prose
 | --- | --- | --- |
 | `hold` | Nothing left behind; the tree is claimed | Start the child. This is the ordinary answer. |
 | `reclaim` | Uncommitted changes, or HEAD off the default branch | Run what stderr printed: `git stash push -u -m "run:hold reclaimed before #<N>"`, then `git switch <default> && git pull`. **`-u` is not optional** (a new `*.test.ts` is untracked). **Then record the stash on `#<N>` as a comment, and ask `run:hold` again** — the check is re-askable. |
-| `resume` | A branch for `#<N>`, or an open pull request, is still here | **Reuse it and run the whole verification gate from the start** — never only the part the interrupted run had not reached. The tools are idempotent; what was missing was that **nobody had verified what the dead run already committed**. |
+| `resume` | An open PR, or a `#<N>` branch with commits or a dirty lane | **Reuse it and run the whole verification gate from the start** — never only the part the interrupted run had not reached. The tools are idempotent; what was missing was that **nobody had verified what the dead run already committed**. |
 | `park` | The pull request for `#<N>` is **merged** or **closed** | **Park the child** — `needs-decision` plus a comment naming what was found — and continue. Carrying on over a merged PR duplicates work; over a closed one revives rejected work. Do not delete the branch, reopen the PR, or commit on top of it. |
 | `busy` | Another **live** run holds this tree | Stop before filing anything — `run:hold`'s own answer, unchanged. |
 | `unknown` | The tree could not be read | Stop the session and report. It is not "the tree is clean". |
@@ -314,6 +314,5 @@ stash reference where there was one.
 
 **It is not asked in a lane** — `run:hold` claimed inside a lane skips the check, and `lane:open`'s own
 answer covers an interrupted lane instead. **Asked in the primary checkout while a lane for that child
-is open, `run:hold` would read `resume`, which is correct** — the branch read
-`git branch --list '<N>-*'` matches `<N>-lane`. The loop never reaches it that way, because `epic:next`
-does not offer a child already carrying `in-progress`.
+is open, `run:hold` reads `resume` only if `<N>-lane` has a commit or a dirty tree** — a clean one
+at the default branch reads `hold`. The loop never gets there, because `epic:next` does not offer a child already carrying `in-progress`.

package/dist/hooks/{chunk-762BDXDU.js → chunk-6PSTVOLH.js}

@@ -36,7 +36,7 @@ import {
   run_watcher_guard,
   shell_segments,
   tail_commands
-} from "./chunk-7WAOP42A.js";
+} from "./chunk-EZLHXKJ6.js";
 import {
   find_local_bin_upwards
 } from "./chunk-3V37IID6.js";
@@ -3533,7 +3533,8 @@ import { execaSync as execaSync2 } from "execa";
 import { z as z8 } from "zod";
 var CLASSIFICATION_SET = new Set(RELEASE_CLASSIFICATION_NAMES);
 var ISSUE_BUG_LABEL = "bug";
-var DECLARATION = /^- リリース分類: (.+)$/gmu;
+var DECLARATION_PREFIX = "- \u30EA\u30EA\u30FC\u30B9\u5206\u985E: ";
+var DECLARATION = new RegExp(`^${DECLARATION_PREFIX}(.+)$`, "gmu");
 var LEGACY_LABELS = /* @__PURE__ */ new Set(["semver-major", "semver-minor"]);
 var LABEL = z8.object({ name: z8.string() });
 var USER = z8.object({ login: z8.string() });
@@ -3552,6 +3553,9 @@ function classification_error(labels, author) {
   if (selected.length === 1 || author.endsWith("[bot]")) return void 0;
   return `Choose one release classification: ${RELEASE_CLASSIFICATION_NAMES.join(", ")}`;
 }
+function declaration(label) {
+  return `${DECLARATION_PREFIX}${label}`;
+}
 function is_classification(value) {
   return CLASSIFICATION_SET.has(value);
 }
@@ -3577,7 +3581,7 @@ function select_issue_classification(issue_json) {
   const [label] = selected;
   if (label === void 0 || selected.length > 1) {
     throw new Error(
-      `Choose one release classification before opening the PR: ${RELEASE_CLASSIFICATION_NAMES.join(", ")}; found: ${selected.join(", ") || "none"}. Add "- \u30EA\u30EA\u30FC\u30B9\u5206\u985E: <label>" to the Issue body.`
+      `Choose one release classification before opening the PR: ${RELEASE_CLASSIFICATION_NAMES.join(", ")}; found: ${selected.join(", ") || "none"}. Add "${DECLARATION_PREFIX}<label>" to the Issue body.`
     );
   }
   return label;
@@ -3610,6 +3614,7 @@ if (process.argv[1] === fileURLToPath2(import.meta.url)) {
 var pr_classification = {
   classification_error,
   check_event,
+  declaration,
   is_classification,
   select_issue_classification
 };
@@ -5113,7 +5118,7 @@ var GH_PR_STATES = /* @__PURE__ */ new Map([
   ["MERGED", MERGED_PR],
   ["OPEN", OPEN_PR]
 ]);
-var CLEAN_REASON = "Nothing was left behind: the tree is clean, HEAD is on the default branch, and this issue has no branch or pull request.";
+var CLEAN_REASON = "Nothing was left behind: the tree is clean, HEAD is on the default branch, and this issue has no pull request and no branch holding work.";
 var CLEAN_ADVICE = "Start the child.";
 var RESUME_ADVICE = "Reuse the branch and run the whole verification gate from the start \u2014 refactor, `pnpm josh gate`, `/code-review` \u2014 never only the part the interrupted run had not reached. Nobody verified what it already committed.";
 var PARK_ADVICE = "Park the child: add `needs-decision` and comment what was found. Do not delete the branch, do not reopen the pull request, and do not commit on top of it.";
@@ -5228,19 +5233,51 @@ function to_head_branch(name) {
   const separator_index = name.indexOf(REMOTE_SEPARATOR);
   return separator_index === NOT_FOUND_INDEX ? name : name.slice(separator_index + 1);
 }
+function group_by_head(pairs) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const [name, reference] of pairs) groups.set(name, [...groups.get(name) ?? [], reference]);
+  return groups;
+}
 async function read_branch_candidates(issue) {
   const pattern = `${issue}${ISSUE_BRANCH_SUFFIX}`;
   const [local, remote] = await Promise.all([
     git_command.branch_names(pattern),
     git_command.branch_names_remote(`${ANY_REMOTE_PREFIX}${pattern}`)
   ]);
-  return [.../* @__PURE__ */ new Set([...local, ...remote.map((name) => to_head_branch(name))])];
+  return group_by_head([
+    ...local.map((name) => [name, name]),
+    ...remote.map((reference) => [to_head_branch(reference), reference])
+  ]);
+}
+async function has_commits_beyond(base, references) {
+  const counts = await Promise.all(
+    references.map(async (reference) => await git_command.commit_count_beyond(base, reference))
+  );
+  return counts.some((count) => count > 0);
+}
+async function is_held_dirty(name, lane) {
+  if (lane?.branch !== name || lane.is_stranded) return false;
+  return await run_hold.is_tree_dirty(lane.directory);
+}
+async function read_candidate(name, references, context) {
+  const state = await read_pr_of_branch(name);
+  if (state.pr_state !== NO_PR) return state;
+  if (await has_commits_beyond(context.base, references)) return state;
+  return await is_held_dirty(name, context.lane) ? state : void 0;
 }
 async function read_child_state(issue) {
   const candidates = await read_branch_candidates(issue);
-  return pick_child_state(
-    await Promise.all(candidates.map(async (name) => await read_pr_of_branch(name)))
+  if (candidates.size === 0) return NO_CHILD_WORK;
+  const [base, lane] = await Promise.all([
+    git_command.default_branch_reference(),
+    lane_registry.find_open_lane(issue)
+  ]);
+  const reads = await Promise.all(
+    [...candidates].map(
+      async ([name, references]) => await read_candidate(name, references, { base, lane })
+    )
   );
+  return pick_child_state(reads.filter((read2) => read2 !== void 0));
 }
 async function check2(issue) {
   require_issue_number(issue);

package/dist/hooks/{chunk-7WAOP42A.js → chunk-EZLHXKJ6.js}

@@ -264,8 +264,9 @@ var git_spawn = {
 async function branch() {
   return await git_spawn.read(["rev-parse", "--abbrev-ref", "HEAD"]);
 }
-async function status() {
-  return await git_spawn.read(["status", PORCELAIN_FLAG, UNTRACKED_FILES_FLAG]);
+async function status(directory) {
+  const location = directory === void 0 ? [] : ["-C", directory];
+  return await git_spawn.read([...location, "status", PORCELAIN_FLAG, UNTRACKED_FILES_FLAG]);
 }
 async function repository_root() {
   return await git_spawn.read(["rev-parse", "--show-toplevel"]);
@@ -607,9 +608,9 @@ function create_hold(target, issue, now = /* @__PURE__ */ new Date(), is_fullrun
 function create_halfrun_stop_hold(target, issue, now = /* @__PURE__ */ new Date()) {
   return stamp_file.create_stamp(target, { ...build_hold(issue, now), is_halfrun_stop: true });
 }
-async function is_tree_dirty() {
+async function is_tree_dirty(directory) {
   try {
-    const status2 = await git_command.status();
+    const status2 = await git_command.status(directory);
     return status2.trim() !== "";
   } catch {
     return true;

package/dist/hooks/codex-hook-adapter.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env tsx
 import {
   pretool_guard
-} from "./chunk-762BDXDU.js";
-import "./chunk-7WAOP42A.js";
+} from "./chunk-6PSTVOLH.js";
+import "./chunk-EZLHXKJ6.js";
 import {
   build_envelope,
   compose_context,

package/dist/hooks/pretool-guard.js

@@ -3,8 +3,8 @@ import {
   pretool_guard,
   pretool_outcome,
   pretool_outcome_async
-} from "./chunk-762BDXDU.js";
-import "./chunk-7WAOP42A.js";
+} from "./chunk-6PSTVOLH.js";
+import "./chunk-EZLHXKJ6.js";
 import "./chunk-3V37IID6.js";
 import "./chunk-A2H5I2VD.js";
 import "./chunk-KPZN42RT.js";

package/dist/hooks/stop-guard.js

@@ -19,7 +19,7 @@ import {
   run_hold,
   run_invocation,
   run_watcher_guard
-} from "./chunk-7WAOP42A.js";
+} from "./chunk-EZLHXKJ6.js";
 import {
   session_language
 } from "./chunk-6V5OPIUU.js";

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.998.0",
+  "version": "1.1005.0",
   "name": "@joshuafolkken/kit",
   "description": "Development toolkit for AI-assisted projects: formatting, AI assistant rules and a Git/GitHub Issue workflow for any repository, plus lint, type check, tests and hooks for Node projects",
   "keywords": [

package/scripts/ci/pr-classification.ts

@@ -12,7 +12,11 @@ import { z } from 'zod'
 
 const CLASSIFICATION_SET: ReadonlySet<string> = new Set(CLASSIFICATION_LABELS)
 const ISSUE_BUG_LABEL = 'bug'
-const DECLARATION = /^- リリース分類: (.+)$/gmu
+// The line an Issue body declares its release classification with. A body written by a script
+// (`josh propagate`'s upgrade issue) builds it with `declaration`, so the writer and this parser share
+// one format (joshuafolkken/kit#2858).
+const DECLARATION_PREFIX = '- リリース分類: '
+const DECLARATION = new RegExp(`^${DECLARATION_PREFIX}(.+)$`, 'gmu')
 const LEGACY_LABELS: ReadonlySet<string> = new Set(['semver-major', 'semver-minor'])
 
 const LABEL = z.object({ name: z.string() })
@@ -38,6 +42,10 @@ function classification_error(labels: ReadonlyArray<string>, author: string): st
 	return `Choose one release classification: ${CLASSIFICATION_LABELS.join(', ')}`
 }
 
+function declaration(label: ReleaseClassification): string {
+	return `${DECLARATION_PREFIX}${label}`
+}
+
 function is_classification(value: string): value is ReleaseClassification {
 	return CLASSIFICATION_SET.has(value)
 }
@@ -75,7 +83,7 @@ function select_issue_classification(issue_json: string): ReleaseClassification
 
 	if (label === undefined || selected.length > 1) {
 		throw new Error(
-			`Choose one release classification before opening the PR: ${CLASSIFICATION_LABELS.join(', ')}; found: ${selected.join(', ') || 'none'}. Add "- リリース分類: <label>" to the Issue body.`,
+			`Choose one release classification before opening the PR: ${CLASSIFICATION_LABELS.join(', ')}; found: ${selected.join(', ') || 'none'}. Add "${DECLARATION_PREFIX}<label>" to the Issue body.`,
 		)
 	}
 
@@ -125,6 +133,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 const pr_classification = {
 	classification_error,
 	check_event,
+	declaration,
 	is_classification,
 	select_issue_classification,
 }

package/scripts/git/git-command.ts

@@ -19,8 +19,11 @@ async function branch(): Promise<string> {
 // recognizes the observation ledger by its path then misses it: `git-staging.ts` stages the directory
 // — ledger included — into an unrelated pull request, and the flush refuses the directory as "other
 // changes".
-async function status(): Promise<string> {
-	return await git_spawn.read(['status', PORCELAIN_FLAG, UNTRACKED_FILES_FLAG])
+// `directory` reads another work tree of the repository — a lane — instead of this one.
+async function status(directory?: string): Promise<string> {
+	const location = directory === undefined ? [] : ['-C', directory]
+
+	return await git_spawn.read([...location, 'status', PORCELAIN_FLAG, UNTRACKED_FILES_FLAG])
 }
 
 // The absolute path every other git command's output is relative to. Asking git rather than reading

package/scripts/init/init-bootstrap.ts

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { z } from 'zod'
+import { init_basic } from './init-basic'
 import { init_install, type InstallStep } from './init-install'
 import { init_logic_workspace } from './init-logic-workspace'
 import { project_profile } from './project-profile'
@@ -73,6 +74,14 @@ function handoff_step(args: ReadonlyArray<string>): InstallStep {
 	}
 }
 
+// pnpm walks up to the nearest `package.json`, so without one here it installs kit into whatever
+// project an ancestor directory holds and rewrites that project's files (joshuafolkken/kit#2866).
+function ensure_project_manifest(project_root: string): void {
+	const manifest_path = path.join(project_root, PACKAGE_JSON)
+
+	if (!existsSync(manifest_path)) writeFileSync(manifest_path, init_basic.initial_manifest())
+}
+
 // Returns the failure to report, or undefined once the project-installed kit finished the setup.
 function hand_off(
 	package_directory: string,
@@ -83,6 +92,8 @@ function hand_off(
 	console.info('\n🚀 Installing @joshuafolkken/kit into the project, then running its josh init')
 	const template = readFileSync(path.join(package_directory, KIT_BUILDS_TEMPLATE), 'utf8')
 	const install = kit_install_step(has_kit_dependency(project_root), template)
+
+	ensure_project_manifest(project_root)
 	if (!init_install.did_step_succeed(install, project_root)) return `${install.label} failed`
 	if (!init_install.did_step_succeed(handoff_step(args), project_root)) return HANDOFF_FAILURE
 

package/scripts/lane/lane-leftover.ts

@@ -0,0 +1,143 @@
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, rmSync } from 'node:fs'
+import path from 'node:path'
+import { git_spawn } from '#scripts/git/git-spawn'
+
+// A lane directory git no longer registers as a work tree (joshuafolkken/kit#2857).
+//
+// **Nothing else can see it.** `lane:list` and `lane:prune` read `git worktree list`, so a directory
+// whose registration is gone is invisible to both, and `git worktree add` refuses its path for good —
+// the lane for that issue cannot be opened again until someone deletes it by hand. `lane:open` asks
+// here before it adds the tree.
+//
+// **The test for removing it is that removing it loses nothing**, not a list of names. Every file in
+// it has to be one the repository already holds with the same content, so it is a checkout git would
+// write again; the one exception is the `.git` file, a pointer to the registration that is gone. A
+// list of generated names would break the next time a file is generated, and would delete whatever
+// shares one of those names.
+
+// `git ls-tree -r -z`: `<mode> <type> <object>\t<path>`, entries separated by NUL — the `-z` form
+// leaves a path with an unusual character unquoted, so it can be compared to the path on disk.
+const TREE_ENTRY_PATTERN = /^\d+ blob (?<object>[\da-f]+)\t(?<path>.+)$/su
+const GIT_POINTER = '.git'
+const GITDIR_PREFIX = 'gitdir: '
+// The foreign paths a refusal names before it summarizes the rest as a count.
+const NAMED_PATH_LIMIT = 10
+
+// One blob entry as `[path, object id]`; a tree, a commit (a submodule) or the trailing empty entry is
+// none.
+function tree_entry(entry: string): Array<[string, string]> {
+	const { path: entry_path, object } = TREE_ENTRY_PATTERN.exec(entry)?.groups ?? {}
+
+	if (entry_path === undefined || object === undefined) return []
+
+	return [[entry_path, object]]
+}
+
+function parse_tree(listing: string): Map<string, string> {
+	return new Map(listing.split('\0').flatMap((entry) => tree_entry(entry)))
+}
+
+// The object id git gives this file — a symbolic link's is that of its target string, as git stores it.
+function blob_id(file: string): string {
+	const content = lstatSync(file).isSymbolicLink()
+		? Buffer.from(readlinkSync(file))
+		: readFileSync(file)
+
+	// SHA-1 because it is git's object id, compared rather than trusted — a repository on the SHA-256
+	// object format matches nothing here, so its leftovers are refused rather than removed.
+	// eslint-disable-next-line sonarjs/hashing -- git's object id, not a security digest
+	return createHash('sha1')
+		.update(`blob ${String(content.length)}\0`)
+		.update(content)
+		.digest('hex')
+}
+
+// Walked one level at a time because `readdirSync`'s `recursive` option descends into a symbolic link
+// to a directory, which would list the repository's own files under the link's path as foreign.
+function walk_files(directory: string, relative: string): Array<string> {
+	return readdirSync(path.join(directory, relative), { withFileTypes: true }).flatMap((entry) => {
+		const child = relative === '' ? entry.name : `${relative}/${entry.name}`
+
+		return entry.isDirectory() ? walk_files(directory, child) : [child]
+	})
+}
+
+// Every file under `directory` as a repository path, symbolic links included and never followed.
+function list_files(directory: string): Array<string> {
+	return walk_files(directory, '')
+}
+
+// The `.git` file is disposable only while the registration it points to is gone: one that still
+// resolves is a live work tree — a `lane:open` of the same issue may be checking it out right now.
+function is_dangling_pointer(directory: string): boolean {
+	const file = path.join(directory, GIT_POINTER)
+
+	if (!lstatSync(file).isFile()) return false
+
+	const pointer = readFileSync(file, 'utf8').trim()
+
+	if (!pointer.startsWith(GITDIR_PREFIX)) return false
+
+	return !existsSync(path.resolve(directory, pointer.slice(GITDIR_PREFIX.length)))
+}
+
+function is_reclaimable_file(
+	directory: string,
+	relative: string,
+	tracked: ReadonlyMap<string, string>,
+): boolean {
+	if (relative === GIT_POINTER) return is_dangling_pointer(directory)
+
+	return tracked.get(relative) === blob_id(path.join(directory, relative))
+}
+
+/**
+ * The paths under `directory` whose removal would lose something — empty when it holds nothing but
+ * the repository's own files and the `.git` pointer. A `.git` directory is a repository of its own,
+ * so it is foreign as a whole rather than walked.
+ */
+function foreign_paths(directory: string, tracked: ReadonlyMap<string, string>): Array<string> {
+	const pointer = lstatSync(path.join(directory, GIT_POINTER), { throwIfNoEntry: false })
+
+	if (pointer?.isDirectory() === true) return [GIT_POINTER]
+
+	return list_files(directory).filter(
+		(relative) => !is_reclaimable_file(directory, relative, tracked),
+	)
+}
+
+function refusal(directory: string, foreign: ReadonlyArray<string>): Error {
+	const named = foreign.slice(0, NAMED_PATH_LIMIT).join(', ')
+	const rest = foreign.length - NAMED_PATH_LIMIT
+	const more = rest > 0 ? ` and ${String(rest)} more` : ''
+
+	return new Error(
+		`${directory} already exists but git does not register it as a work tree, and it holds files the repository does not: ${named}${more}. It was left in place so nothing is lost — move those files out, delete the directory, and open the lane again.`,
+	)
+}
+
+/**
+ * Clear the way for `git worktree add` at `directory`, which the caller has found unregistered.
+ * Absent is nothing to do; holding only the repository's own files, it is removed; anything else is
+ * refused with the paths that would have been lost.
+ */
+async function reclaim(directory: string): Promise<void> {
+	if (!existsSync(directory)) return
+
+	const tracked = parse_tree(await git_spawn.read(['ls-tree', '-r', '-z', '--full-tree', 'HEAD']))
+	const foreign = foreign_paths(directory, tracked)
+
+	if (foreign.length > 0) throw refusal(directory, foreign)
+
+	rmSync(directory, { force: true, recursive: true })
+}
+
+const lane_leftover = {
+	blob_id,
+	foreign_paths,
+	parse_tree,
+	reclaim,
+}
+
+export { lane_leftover }

package/scripts/lane/lane-open.ts

@@ -5,6 +5,7 @@ import { git_worktree } from '#scripts/git/git-worktree'
 import { lane_cache } from './lane-cache'
 import { lane_environment } from './lane-environment'
 import { lane_install, type InstallResult } from './lane-install'
+import { lane_leftover } from './lane-leftover'
 import { lane_paths } from './lane-paths'
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_seed_policy } from './lane-seed'
@@ -234,6 +235,18 @@ async function materialize(plan: LanePlan, source_root: string): Promise<void> {
 	}
 }
 
+// Both refusals run before the seat is claimed, so neither leaves a lock behind. A directory at the
+// lane's path that git does not register is `lane_leftover`'s to remove or refuse
+// (joshuafolkken/kit#2857).
+async function clear_the_way(
+	root: string,
+	issue: string,
+	lanes: ReadonlyArray<LaneInfo>,
+): Promise<void> {
+	guard_unreadable(root, lanes)
+	await lane_leftover.reclaim(lane_paths.lane_directory(root, issue))
+}
+
 /**
  * Open the lane for `issue`, or say why it was not opened.
  *
@@ -253,7 +266,7 @@ async function open_lane(issue: string): Promise<OpenOutcome> {
 
 	const root = lane_paths.lane_root(repository_root)
 
-	guard_unreadable(root, lanes)
+	await clear_the_way(root, issue, lanes)
 
 	const plan = build_plan(repository_root, root, issue, lanes)
 

package/scripts/propagate/propagate-steps.ts

@@ -1,5 +1,7 @@
+import { pr_classification } from '#scripts/ci/pr-classification'
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
+import { OTHER_CHANGE_LABEL } from '#scripts/git/issue-labels'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { build_upgrade_shell_command } from '#scripts/version/upgrade-shell-command'
 import { create_version_command_config } from '#scripts/version/version-command-config'
@@ -62,6 +64,10 @@ const PROPAGATE_ORIGIN =
 	'Opened by `josh propagate` from the supplier repository after the release was published.'
 const RUN_NOTE =
 	'The upgrade, the managed-file sync and the verification gate have already run here.'
+// `josh git` refuses to open a pull request for an issue that declares no release classification
+// (joshuafolkken/kit#2666), so the upgrade issue declares one. A dependency upgrade changes no code of
+// the consumer's own, which is what `other-change` covers (joshuafolkken/kit#2858).
+const UPGRADE_CLASSIFICATION = OTHER_CHANGE_LABEL
 const EMPTY_PLAN_TITLE = 'Upgrade the installed toolkits'
 const LAST_SEPARATOR = ' and '
 const NAME_SEPARATOR = ', '
@@ -95,7 +101,14 @@ function plan_body(plan: ReleasePlan): string {
 		.map((release) => `\`${release.package_name}@${release.version}\``)
 		.join(NAME_SEPARATOR)
 
-	return [`Carry ${specs} into this repository.`, '', plan.origin, RUN_NOTE].join('\n')
+	return [
+		`Carry ${specs} into this repository.`,
+		'',
+		plan.origin,
+		RUN_NOTE,
+		'',
+		pr_classification.declaration(UPGRADE_CLASSIFICATION),
+	].join('\n')
 }
 
 function issue_body(package_name: string, version: string): string {

package/scripts/run/run-hold.ts

@@ -170,10 +170,10 @@ function create_halfrun_stop_hold(target: string, issue: string, now: Date = new
 // be chosen that covers a `halfrun` stop or a `needs-human-review` stop: those are held across a
 // person's latency rather than a run's, and the thing that must not be trampled is sitting in the
 // tree where anyone can see it. An unreadable status is dirty, for the reason every other unreadable
-// state here blocks.
-async function is_tree_dirty(): Promise<boolean> {
+// state here blocks. `directory` asks the same of another work tree — a lane — instead of this one.
+async function is_tree_dirty(directory?: string): Promise<boolean> {
 	try {
-		const status = await git_command.status()
+		const status = await git_command.status(directory)
 
 		return status.trim() !== ''
 	} catch {

package/scripts/run/run-preflight.ts

@@ -1,5 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_gh_pr_read } from '#scripts/git/git-gh-pr-read'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { z } from 'zod'
 import { run_hold } from './run-hold'
 import { run_issue_number } from './run-issue-number'
@@ -72,7 +73,7 @@ const GH_PR_STATES: ReadonlyMap<string, PrState> = new Map([
 ])
 
 const CLEAN_REASON =
-	'Nothing was left behind: the tree is clean, HEAD is on the default branch, and this issue has no branch or pull request.'
+	'Nothing was left behind: the tree is clean, HEAD is on the default branch, and this issue has no pull request and no branch holding work.'
 
 const CLEAN_ADVICE = 'Start the child.'
 
@@ -283,22 +284,91 @@ function to_head_branch(name: string): string {
 	return separator_index === NOT_FOUND_INDEX ? name : name.slice(separator_index + 1)
 }
 
-async function read_branch_candidates(issue: string): Promise<Array<string>> {
+function group_by_head(pairs: ReadonlyArray<[string, string]>): Map<string, Array<string>> {
+	const groups = new Map<string, Array<string>>()
+
+	for (const [name, reference] of pairs) groups.set(name, [...(groups.get(name) ?? []), reference])
+
+	return groups
+}
+
+// Each candidate keeps every ref it was found as — the local branch and each remote-tracking ref —
+// because either may be the one holding the commits: a local branch left at the default branch can
+// sit beside a remote one another machine pushed work to, and the stripped head name may not resolve.
+async function read_branch_candidates(issue: string): Promise<Map<string, Array<string>>> {
 	const pattern = `${issue}${ISSUE_BRANCH_SUFFIX}`
 	const [local, remote] = await Promise.all([
 		git_command.branch_names(pattern),
 		git_command.branch_names_remote(`${ANY_REMOTE_PREFIX}${pattern}`),
 	])
 
-	return [...new Set([...local, ...remote.map((name) => to_head_branch(name))])]
+	return group_by_head([
+		...local.map((name): [string, string] => [name, name]),
+		...remote.map((reference): [string, string] => [to_head_branch(reference), reference]),
+	])
+}
+
+async function has_commits_beyond(
+	base: string,
+	references: ReadonlyArray<string>,
+): Promise<boolean> {
+	const counts = await Promise.all(
+		references.map(async (reference) => await git_command.commit_count_beyond(base, reference)),
+	)
+
+	return counts.some((count) => count > 0)
+}
+
+// **A lane stopped mid-implementation holds its work uncommitted**, on a branch with no commit yet —
+// so the lane checked out on the candidate is asked whether its tree is dirty, read the way
+// `run_hold` reads this tree (an unreadable status is dirty). A lane on another branch, or whose
+// directory is gone, holds nothing for this candidate.
+async function is_held_dirty(name: string, lane: LaneInfo | undefined): Promise<boolean> {
+	if (lane?.branch !== name || lane.is_stranded) return false
+
+	return await run_hold.is_tree_dirty(lane.directory)
+}
+
+interface CandidateContext {
+	base: string
+	lane: LaneInfo | undefined
+}
+
+// **A branch with no pull request, no commit beyond the default branch and no uncommitted change in
+// its lane holds no work** (joshuafolkken/kit#2855). A lane that ended before implementing — an
+// operational issue with no code change — leaves exactly that behind, and reading its mere existence
+// as a partial implementation sent the next `fullrun #N` to `resume` over nothing. A branch with a
+// pull request is never counted: whatever its commits, the pull request is the state the verdict is
+// decided on.
+async function read_candidate(
+	name: string,
+	references: ReadonlyArray<string>,
+	context: CandidateContext,
+): Promise<ChildState | undefined> {
+	const state = await read_pr_of_branch(name)
+
+	if (state.pr_state !== NO_PR) return state
+	if (await has_commits_beyond(context.base, references)) return state
+
+	return (await is_held_dirty(name, context.lane)) ? state : undefined
 }
 
 async function read_child_state(issue: string): Promise<ChildState> {
 	const candidates = await read_branch_candidates(issue)
 
-	return pick_child_state(
-		await Promise.all(candidates.map(async (name) => await read_pr_of_branch(name))),
+	if (candidates.size === 0) return NO_CHILD_WORK
+
+	const [base, lane] = await Promise.all([
+		git_command.default_branch_reference(),
+		lane_registry.find_open_lane(issue),
+	])
+	const reads = await Promise.all(
+		[...candidates].map(
+			async ([name, references]) => await read_candidate(name, references, { base, lane }),
+		),
 	)
+
+	return pick_child_state(reads.filter((read): read is ChildState => read !== undefined))
 }
 
 // The child read is skipped where the tree already answers `reclaim`: a `gh` round trip buys nothing

package/scripts/run/run-progress-cli.ts

@@ -77,7 +77,12 @@ const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_MAX_
 // The repository name is only ever printed, never written against, so the bounded lookup is the right
 // one: a `gh` call that hangs would otherwise block the synchronous read at startup and leave the
 // watcher neither running nor saying so.
-const REPO_LOOKUP_TIMEOUT_MS = 10_000
+const REPO_LOOKUP_TIMEOUT_SECONDS = 10
+const REPO_LOOKUP_TIMEOUT_MS = REPO_LOOKUP_TIMEOUT_SECONDS * run_progress.MS_PER_SECOND
+// A lookup that timed out or failed is not an argument the caller got wrong, so it is told apart from
+// the usage error — read as one, it sent a person to fix arguments that were correct
+// (joshuafolkken/kit#2859).
+const REPO_UNRESOLVED_NOTICE = `The repository could not be resolved (\`gh\` did not answer within ${String(REPO_LOOKUP_TIMEOUT_SECONDS)}s or failed), so the progress watcher did not start. Pass \`--repo <owner/repo>\` and start it again.`
 
 const DECLINE_NOTICES: Readonly<Record<'idle' | 'unreadable', string>> = {
 	idle: IDLE_NOTICE,
@@ -141,6 +146,12 @@ function report_usage(): number {
 	return FAILURE_EXIT_CODE
 }
 
+function report_repo_unresolved(): number {
+	console.error(REPO_UNRESOLVED_NOTICE)
+
+	return FAILURE_EXIT_CODE
+}
+
 function report_disabled(): number {
 	console.error(DISABLED_NOTICE)
 
@@ -443,7 +454,7 @@ function to_options(values: ParsedValues): WatchOptions | undefined {
 async function run_watch(values: ParsedValues): Promise<number> {
 	const options = to_options(values)
 
-	if (options === undefined) return report_usage()
+	if (options === undefined) return report_repo_unresolved()
 	if (values.once === true) return await once(options)
 	if (values.wait === true) return await wait_once(options)
 
@@ -487,6 +498,7 @@ const run_progress_cli = {
 	IDLE_NOTICE,
 	LANE_CHILD_NOTICE,
 	MARKED_NOTICE,
+	REPO_UNRESOLVED_NOTICE,
 	TICK_SECONDS,
 	UNREADABLE_NOTICE,
 	USAGE,