@joshuafolkken/kit 1.921.0 → 1.947.0

package/ports/web-server.js

@@ -0,0 +1,73 @@
+// The command Playwright's `webServer` runs, built so no package manager stands between Playwright
+// and the server it starts.
+//
+// Playwright spawns the command detached and tears it down by signalling that process group. pnpm
+// 11.27.1+ moves a script it runs without a controlling terminal into a group of its own, so the
+// teardown reached pnpm alone and the dev / preview server survived holding Playwright's stdio pipes
+// open — a hang #2386 patched by relying on pnpm to relay SIGTERM. `node --run` executes the same
+// `package.json` script in the caller's process group, so the teardown signal reaches the server
+// itself and there is no relay left to depend on (#2392).
+//
+// The script names stay the interface rather than a hard-coded `vite` invocation: a consumer's
+// `preview` is not necessarily `vite preview` (wrangler serves the Cloudflare build), and each script
+// resolves its own port through `josh port`. What `node --run` does not do is run `pre<name>` hooks,
+// which a consumer can rely on — a `prepreview` applying local database migrations, say — so the hook
+// is chained explicitly here instead of being dropped without a word. `post<name>` is not: a server
+// script never ends on its own, so its post hook would never have run under pnpm either.
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { ports } from './index.js'
+
+const PACKAGE_FILE_NAME = 'package.json'
+const PRE_HOOK_PREFIX = 'pre'
+const STEP_SEPARATOR = ' && '
+
+/**
+ * The `scripts` of the project root's `package.json` — the same file `node --run` resolves from the
+ * working directory — or an empty record when there is none.
+ *
+ * @param {string} directory
+ * @returns {Record<string, unknown>}
+ */
+function read_scripts(directory) {
+	const file = path.join(ports.resolve_project_directory(directory), PACKAGE_FILE_NAME)
+	if (!existsSync(file)) return {}
+
+	const { scripts } = JSON.parse(readFileSync(file, 'utf8'))
+
+	return typeof scripts === 'object' && scripts !== null ? scripts : {}
+}
+
+/**
+ * @param {string} name
+ * @param {Record<string, unknown>} scripts
+ * @returns {string[]}
+ */
+function steps_for(name, scripts) {
+	const hook = `${PRE_HOOK_PREFIX}${name}`
+
+	return Object.hasOwn(scripts, hook) ? [hook, name] : [name]
+}
+
+/**
+ * Chain the named `package.json` scripts, each preceded by its `pre` hook when the project defines
+ * one, into a single shell command run through `node --run`.
+ *
+ * @param {string[]} names
+ * @param {string} [directory]
+ * @returns {string}
+ */
+function script_command(names, directory = process.cwd()) {
+	const scripts = read_scripts(directory)
+
+	return names
+		.flatMap((name) => steps_for(name, scripts))
+		.map((step) => `node --run ${step}`)
+		.join(STEP_SEPARATOR)
+}
+
+const web_server = {
+	script_command,
+}
+
+export { web_server }

package/prompts/collaboration-workflow/issue-template.md

@@ -76,7 +76,7 @@ Issue には次の要素を必ず含める。
 - **互換性を壊す変更は影響を本文で宣言する。** 既存の利用者、API、設定の契約を変える場合は、`## 背景` の直下に `- 互換性: 破壊的変更` を書き、廃止対象と影響を説明する。移行措置や事前案内があっても破壊的変更なら宣言する。`pnpm josh issue:lint <本文ファイル>` が `labels: breaking-change` を返したら、同じ作成呼び出しに `-f 'labels[]=breaking-change'` を付ける。互換性を保つ変更には付けない。影響が曖昧なら起票文案で対象の利用者と契約を明確にしてから分類する
 - **`issue:lint` が返す分類ラベルをすべて起票時に指定する。** `bug`、`enhancement`、`breaking-change` は組み合わせて表示されることがある。`depth`・`route` など既存のラベルを残し、`labels: none` のときは分類ラベルを付けない。Issue が `enhancement` と `breaking-change` の両方を持つとき、PR のリリース分類は `breaking-change` 一つにする。Issue の目的の分類と PR のリリース分類を区別する
 - **`## 発火点`** には、その規則が破れる瞬間に最初に呼ばれるツールコール名を 1 つ書く。名前は `prompts/collaboration-workflow/rule-delivery.md` の配送表に載る、フックで配送可能なツール（`Bash` / `Edit` / `Read` / `Write` / `AskUserQuestion`）と突き合わせる。**表に無い名前**（そもそもツールコール名でない）と**不一致**（既知のツールだが配送できない）は区別して印字され、joshuafolkken/kit#2201 の「規則は正しいが名指ししたコールが実際に破れるコールの 1 つ後ろ」を起票時に検出する
-- **`## ベースライン`** は **「コマンド + 値」** で書く。``- `<測定コマンド>` → <現在の値>`` の形に限り、自然文だけの測定説明は受け付けない（再実行できないため）。マージ後に `pnpm josh measure:rerun` が同じコマンドをやり直し、**before / after の対**を印字する。値が動かなかったとき、反証された前提として `docs/observations.md` に 1 行追記される（既存の append-only 台帳をそのまま使い、第 2 の台帳は作らない）
+- **`## ベースライン`** は **「コマンド + 値」** で書く。``- `<測定コマンド>` → <現在の値>`` の形に限り、自然文だけの測定説明は受け付けない（再実行できないため）。マージ後に `pnpm josh measure:rerun` が同じコマンドをやり直し、**before / after の対**を印字する。値が動かなかったとき、反証された前提として `docs/maintainers/observations.md` に 1 行追記される（既存の append-only 台帳を使い、別の台帳は作らない）
 - **`## 再現`** は **「コマンド + 実際の出力」** で書く。コマンドを backtick、出力をフェンス（``` または ~~~）で囲む。自然文の「確認した」は再実行できないため受け付けない（`## ベースライン` と同じ理由）。読みだけの起票を起票時に弾くためである
 - **検査は `pnpm josh issue:lint <path>` が行う。** 対象判定・3 見出しの有無・発火点の配送可否・ベースラインが「コマンド + 値」か・再現が「コマンド + 実際の出力」かと、起票時に必要な分類ラベルを、起票前の本文ファイルからまとめて答える（未リントの起票は `pnpm josh rule:guard` が拒否する）
 

package/scripts/agent/agent-role-profile.ts

@@ -201,6 +201,16 @@ function resolve_provider(environment: AgentEnvironment = process.env): Provider
 	return detected_provider(environment) ?? handed_provider(environment)
 }
 
+// Whether this session is woken when a background command it started completes
+// (joshuafolkken/kit#2653). Claude Code re-invokes the session at the completion; a Codex session is not
+// re-invoked, so a parent there can only wait by polling, each poll a model call over its whole context.
+// Only a resolved Codex session answers no — an unresolved one keeps the behavior it had before.
+function has_completion_callback(environment: AgentEnvironment = process.env): boolean {
+	const selected = resolve_provider(environment)
+
+	return selected.kind !== 'provider' || selected.provider !== OPENAI_PROVIDER
+}
+
 // The mark a detached launch sets on its child: the provider this session resolved, or nothing when it
 // resolved none — the child then fails the same way this session would have.
 function handoff_environment(
@@ -309,6 +319,7 @@ const agent_role_profile = {
 	WORKER,
 	describe,
 	handoff_environment,
+	has_completion_callback,
 	is_safe_value,
 	parse,
 	phase_effort,

package/scripts/ci/pr-classification.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
+import { execaSync } from 'execa'
 import { z } from 'zod'
 
 const BUGFIX = 'bugfix'
@@ -19,9 +20,10 @@ const LEGACY_LABELS: ReadonlySet<string> = new Set(['semver-major', 'semver-mino
 
 const LABEL = z.object({ name: z.string() })
 const USER = z.object({ login: z.string() })
-const PULL_REQUEST = z.object({ user: USER, labels: z.array(LABEL) })
+const PULL_REQUEST = z.object({ number: z.number(), user: USER })
 const EVENT = z.object({
 	pull_request: PULL_REQUEST,
+	repository: z.object({ full_name: z.string() }),
 })
 
 function classification_error(labels: ReadonlyArray<string>, author: string): string | undefined {
@@ -83,13 +85,32 @@ function select_issue_classification(issue_json: string): ReleaseClassification
 	return label
 }
 
-function check_event(event_path: string): string | undefined {
+// The labels as they stand when the check runs, not as the event carried them. `josh pr` opens the
+// pull request and labels it in a second call, so the `opened` event carries none; judged from the
+// payload, that run fails, and when it lands in the newer check suite GitHub keeps its red result —
+// a rerun replays the same payload and fails again (joshuafolkken/kit#2712).
+function fetch_current_labels(repository: string, pull_number: number): ReadonlyArray<string> {
+	const result = execaSync(
+		'gh',
+		['api', `repos/${repository}/issues/${String(pull_number)}/labels`, '--jq', '.[].name'],
+		{ reject: false },
+	)
+
+	if (result.exitCode !== 0) {
+		throw new Error(`Could not read the pull request labels: ${result.stderr}`)
+	}
+
+	return result.stdout.split('\n').filter((name) => name !== '')
+}
+
+function check_event(
+	event_path: string,
+	read_labels: typeof fetch_current_labels = fetch_current_labels,
+): string | undefined {
 	const event = EVENT.parse(JSON.parse(readFileSync(event_path, 'utf8')))
+	const labels = read_labels(event.repository.full_name, event.pull_request.number)
 
-	return classification_error(
-		event.pull_request.labels.map((label) => label.name),
-		event.pull_request.user.login,
-	)
+	return classification_error(labels, event.pull_request.user.login)
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

package/scripts/document/document-byte-budget.ts

@@ -82,7 +82,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/rule-residency.md', bytes: 24_576 },
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
-	{ path: 'docs/josh-commands.md', bytes: 163_840 },
+	{ path: 'docs/josh-commands.md', bytes: 167_936 },
 	{ path: 'prompts/agent-rules.md', bytes: 4096 },
 	{ path: 'prompts/coding-standards.md', bytes: 16_384 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },

package/scripts/gate/hook-gate-reuse.ts

@@ -53,7 +53,7 @@ function is_force_requested(force_environment: string): boolean {
 // nothing" for "git could not be asked". Every predicate below treats the two differently.
 //
 // **The observation ledger is dropped from the reading, and it is the one line that may be**
-// (joshuafolkken/kit#1756). Since that issue `pnpm josh git` excludes `docs/observations.md` from
+// (joshuafolkken/kit#1756). Since that issue `pnpm josh git` excludes the ledger from
 // what it stages, so a parent's appended line sits modified-but-never-staged for the whole interval
 // between the append and the next `pnpm josh observations:flush` — and every condition below reads a
 // non-empty status as "this operation carries a tree no check has read". Left in, one ledger line

package/scripts/gate/project-checks.ts

@@ -2,6 +2,7 @@ import { existsSync, globSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { SKIP_MARKER } from '#scripts/test/skip-marker'
+import { z } from 'zod'
 
 const PACKAGE_JSON = 'package.json'
 const IGNORED_DIRS = new Set([
@@ -36,6 +37,8 @@ const CSPELL_CONFIGS = [
 	'cspell.yaml',
 ]
 const TYPE_CONFIGS = ['tsconfig.json', 'jsconfig.json']
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies']
+const object_schema = z.record(z.string(), z.unknown())
 
 function project_root(directory: string): string {
 	let current = directory
@@ -78,28 +81,77 @@ function is_static_manifest(manifest: unknown): boolean {
 	return josh.profile === 'static'
 }
 
-function is_static(directory: string): boolean {
+function read_manifest(directory: string): unknown {
 	try {
 		const manifest_path = path.join(project_root(directory), PACKAGE_JSON)
-		const manifest: unknown = JSON.parse(readFileSync(manifest_path, 'utf8'))
 
-		return is_static_manifest(manifest)
+		return JSON.parse(readFileSync(manifest_path, 'utf8'))
 	} catch {
-		return false
+		return undefined
 	}
 }
 
+function is_static(directory: string): boolean {
+	return is_static_manifest(read_manifest(directory))
+}
+
+function is_declared(directory: string, package_name: string): boolean {
+	const manifest = object_schema.safeParse(read_manifest(directory))
+	if (!manifest.success) return false
+
+	return DEPENDENCY_FIELDS.some((field) => {
+		const dependencies = object_schema.safeParse(manifest.data[field])
+
+		return dependencies.success && Object.hasOwn(dependencies.data, package_name)
+	})
+}
+
+// A tool the manifest lists but `node_modules` lacks is a project that has not run `pnpm install`
+// yet — typically right after `josh init` added it (joshuafolkken/kit#2709). Skipping it would pass a
+// check the configuration asks for without running it, so only an undeclared tool is skipped; a
+// declared one is run and fails until it is installed.
+function missing_tool_reason(
+	directory: string,
+	package_name: string,
+	bin_name: string,
+): string | undefined {
+	if (has_bin(directory, bin_name) || is_declared(directory, package_name)) return undefined
+
+	return `${package_name} is not installed`
+}
+
 function skip_notice(check: string, reason: string): string {
 	return `josh ${check}: ${reason} ${SKIP_MARKER} ${check}.`
 }
 
+// Shared by `josh check` and the gate's type-check step, so neither reaches `tsc` on a static
+// project that has nothing to type-check (joshuafolkken/kit#2709).
 function type_check_skip_reason(directory: string): string | undefined {
 	if (!is_static(directory)) return undefined
 	if (!has_files(directory, TYPE_FILES)) return 'no TypeScript files were found'
 	if (!has_config(directory, TYPE_CONFIGS)) return 'no TypeScript configuration was found'
-	if (!has_bin(directory, 'tsc')) return 'typescript is not installed'
 
-	return undefined
+	return missing_tool_reason(directory, 'typescript', 'tsc')
+}
+
+// Shared by `josh lint`, `josh lint:related` and `josh format`, so a static project without Web
+// files — a Python or Rust project, which `josh init` gives no Prettier — is skipped for the same
+// reason by all three (joshuafolkken/kit#2606, joshuafolkken/kit#2709).
+function prettier_skip_reason(directory: string): string | undefined {
+	if (!is_static(directory)) return undefined
+	if (!has_files(directory, WEB_FILES)) return 'no HTML, CSS or JavaScript files were found'
+
+	return missing_tool_reason(directory, 'prettier', 'prettier')
+}
+
+// Shared by `josh lint`, `josh lint:related` and `josh format`, so a static project without ESLint
+// is skipped for the same reason by all three (joshuafolkken/kit#2693, joshuafolkken/kit#2709).
+function eslint_skip_reason(directory: string): string | undefined {
+	if (!is_static(directory)) return undefined
+	if (!has_files(directory, SCRIPT_FILES)) return 'no JavaScript or TypeScript files were found'
+	if (!has_config(directory, ESLINT_CONFIGS)) return 'no ESLint configuration was found'
+
+	return missing_tool_reason(directory, 'eslint', 'eslint')
 }
 
 const project_checks = {
@@ -109,10 +161,12 @@ const project_checks = {
 	TYPE_CONFIGS,
 	TYPE_FILES,
 	WEB_FILES,
+	eslint_skip_reason,
 	has_bin,
 	has_config,
 	has_files,
 	is_static,
+	prettier_skip_reason,
 	project_root,
 	skip_notice,
 	type_check_skip_reason,

package/scripts/gate/type-check-command.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { TS_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { execa } from 'execa'
+import { project_checks } from './project-checks'
+
+// `josh check` — the project-wide TypeScript check. It used to be a bare `tsc --noEmit` shell entry,
+// so on a static project with nothing to type-check it failed with `Command "tsc" not found` while
+// the gate, which asks `type_check_skip_reason` first, skipped the same step
+// (joshuafolkken/kit#2709). Both now read that one decision.
+
+const ARGV_OFFSET = 2
+const FAIL_EXIT_CODE = 1
+const TSC_ARGS = ['exec', 'tsc', '--noEmit', ...TS_CACHE_FLAGS] as const
+
+async function run_type_check(
+	command_arguments: ReadonlyArray<string>,
+	directory: string,
+): Promise<number> {
+	const reason = project_checks.type_check_skip_reason(directory)
+
+	if (reason !== undefined) {
+		console.info(project_checks.skip_notice('check', reason))
+
+		return 0
+	}
+
+	const result = await execa('pnpm', [...TSC_ARGS, ...command_arguments], {
+		cwd: directory,
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return result.exitCode ?? FAIL_EXIT_CODE
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run_type_check(process.argv.slice(ARGV_OFFSET), process.cwd())
+}
+
+const type_check_command = { run_type_check }
+
+export { TSC_ARGS, type_check_command }

package/scripts/git/constants.ts

@@ -9,6 +9,9 @@ const GIT_COMMAND_UNIX = '/usr/bin/git'
 // here rather than beside either of them because `status` and `worktree_list` now sit in different
 // modules (joshuafolkken/kit#1640) and a copy in each is a second answer to one question.
 const PORCELAIN_FLAG = '--porcelain'
+// The untracked-files mode every porcelain status reading passes (`git-command.ts` carries why it is
+// passed and why it is `all`), shared so `run-carry-flush.ts`'s own reading cannot drift from it.
+const UNTRACKED_FILES_FLAG = '--untracked-files=all'
 
 function get_git_command(): string {
 	if (platform() === 'win32') {
@@ -37,5 +40,6 @@ export {
 	UNTRACKED_FILE_PREFIX,
 	SEPARATOR_LINE,
 	PORCELAIN_FLAG,
+	UNTRACKED_FILES_FLAG,
 	git_utilities,
 }

package/scripts/git/git-command.ts

@@ -1,4 +1,4 @@
-import { PORCELAIN_FLAG } from './constants'
+import { PORCELAIN_FLAG, UNTRACKED_FILES_FLAG } from './constants'
 import { git_push_transport } from './git-push-transport'
 import { git_spawn } from './git-spawn'
 
@@ -6,15 +6,21 @@ async function branch(): Promise<string> {
 	return await git_spawn.read(['rev-parse', '--abbrev-ref', 'HEAD'])
 }
 
-// **`--untracked-files=normal` is passed rather than inherited** (joshuafolkken/kit#1381). Every
+// **The untracked-files mode is passed rather than inherited** (joshuafolkken/kit#1381). Every
 // reader of this output depends on the `??` lines being there: `git-staging.ts` stages exactly those,
 // and `hook-gate-reuse.ts` reads an empty output as "this push carries the recorded tree". A person
 // with `status.showUntrackedFiles=no` in their git config — a common setting on large repositories —
 // gets porcelain output with those lines silently absent, so untracked files go unstaged and the
-// pre-push hook reuses a record for a commit that does not contain them. Naming git's own default
-// makes the reading answer to this codebase rather than to whoever ran it.
+// pre-push hook reuses a record for a commit that does not contain them. Naming the mode makes the
+// reading answer to this codebase rather than to whoever ran it.
+//
+// **`all` rather than `normal`, so a new file is named even inside an untracked directory**
+// (joshuafolkken/kit#2724). `normal` collapses it to `?? docs/maintainers/`, and every reader that
+// 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=normal'])
+	return await git_spawn.read(['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/git/git-gh-pr-rollup.ts

@@ -29,7 +29,9 @@ const check_runs_page_schema = z.looseObject({
 	// answer an empty rollup — which `git-pr-followup.ts` reports as "this branch has no checks".
 	check_runs: z.array(rollup_element_schema),
 })
-const check_run_app_schema = z.object({ id: z.number() })
+
+// Both `app` and `check_suite` are objects carrying a numeric `id`, and so is a check run itself.
+const id_holder_schema = z.object({ id: z.number() })
 
 const status_page_schema = z.looseObject({
 	statuses: z.array(rollup_element_schema),
@@ -51,37 +53,75 @@ function read_pages<T>(raw_json: string, schema: z.ZodType<T>, message: string):
 	return pages
 }
 
+const NO_SUITE = -1
+
+interface RunRank {
+	suite: number
+	run: number
+}
+
+function read_id(value: unknown): number | undefined {
+	const parsed = id_holder_schema.safeParse(value)
+
+	return parsed.success ? parsed.data.id : undefined
+}
+
 function check_run_group_key(run: RollupElement): string | undefined {
-	const { name, app: raw_app } = run
+	const { name, app } = run
 	if (typeof name !== 'string') return undefined
-	const app = check_run_app_schema.safeParse(raw_app)
 
-	return JSON.stringify([name, app.success ? app.data.id : undefined])
+	return JSON.stringify([name, read_id(app)])
+}
+
+function read_rank(run: RollupElement): RunRank | undefined {
+	const id = read_id(run)
+	if (id === undefined) return undefined
+
+	return { suite: read_id(run['check_suite']) ?? NO_SUITE, run: id }
+}
+
+// **The newest check suite decides a name, not the newest check run** — the rule GitHub's merge box
+// applies. The endpoint's default `filter=latest` already keeps only the newest run of each name
+// *within* a suite (a re-run job lands in the suite it re-runs), so what is left is one run per
+// suite. Across suites GitHub takes the one from the newer suite: PR #2717's cancelled suite was the
+// older one and GitHub read the pull request `CLEAN`, while PR #2698's cancelled suite was the newer
+// one and GitHub held it `BLOCKED`. Ranking by run id alone (joshuafolkken/kit#2644) picked #2698's
+// older, successful suite — its jobs had queued later — so `followup` read green beside a `BLOCKED`
+// pull request and waited out its whole budget (joshuafolkken/kit#2700).
+function is_ranked_above(candidate: RunRank, current: RunRank): boolean {
+	if (candidate.suite !== current.suite) return candidate.suite > current.suite
+
+	return candidate.run > current.run
+}
+
+function should_replace(previous: RollupElement | undefined, rank: RunRank): boolean {
+	const previous_rank = previous === undefined ? undefined : read_rank(previous)
+
+	return previous_rank === undefined || is_ranked_above(rank, previous_rank)
 }
 
-function remember_newest_run(run: RollupElement, latest_ids: Map<string, number>): void {
+function remember_newest_run(run: RollupElement, newest: Map<string, RollupElement>): void {
 	const key = check_run_group_key(run)
-	const { id } = run
-	if (key === undefined || typeof id !== 'number') return
-	const previous_id = latest_ids.get(key)
-	if (previous_id === undefined || id > previous_id) latest_ids.set(key, id)
+	const rank = read_rank(run)
+	if (key === undefined || rank === undefined) return
+	if (should_replace(newest.get(key), rank)) newest.set(key, run)
 }
 
-function is_newest_run(run: RollupElement, latest_ids: Map<string, number>): boolean {
+// A run with no name or id cannot be ranked, so it is kept rather than guessed to be superseded.
+function is_newest_run(run: RollupElement, newest: Map<string, RollupElement>): boolean {
 	const key = check_run_group_key(run)
-	const { id } = run
-	if (key === undefined || typeof id !== 'number') return true
+	if (key === undefined || read_rank(run) === undefined) return true
 
-	return id === latest_ids.get(key)
+	return newest.get(key) === run
 }
 
 function to_check_run_items(check_runs_json: string): Array<RollupElement> {
 	const pages = read_pages(check_runs_json, check_runs_page_schema, NOT_A_CHECK_RUNS_LISTING)
 	const runs = pages.flatMap((page) => page.check_runs)
-	const latest_ids = new Map<string, number>()
-	for (const run of runs) remember_newest_run(run, latest_ids)
+	const newest = new Map<string, RollupElement>()
+	for (const run of runs) remember_newest_run(run, newest)
 
-	return runs.filter((run) => is_newest_run(run, latest_ids))
+	return runs.filter((run) => is_newest_run(run, newest))
 }
 
 function to_status_context_items(status_json: string): Array<RollupElement> {

package/scripts/git/git-staging.ts

@@ -1,6 +1,6 @@
 import {
 	observation_ledger,
-	OBSERVATION_LEDGER_PATH,
+	OBSERVATION_LEDGER_PATHS,
 } from '#scripts/observations/observation-ledger'
 import { git_command } from './git-command'
 import { git_prompt } from './git-prompt'
@@ -73,10 +73,12 @@ async function stage_untracked_files(files: ReadonlyArray<string>): Promise<void
 // entirely — a diff a reviewer has no reason to question. Excluding it here covers every entry
 // point, because this is the one staging step all of them go through;
 // `pnpm josh observations:flush` is what commits it, on a branch of its own.
-const PATHS_EXCLUDED_FROM_STAGING: ReadonlyArray<string> = [OBSERVATION_LEDGER_PATH]
+// Both of its paths are excluded (joshuafolkken/kit#2724): a run on the old code still appends at
+// the old one until `observation-ledger-migrate.ts` moves it.
+const PATHS_EXCLUDED_FROM_STAGING: ReadonlyArray<string> = OBSERVATION_LEDGER_PATHS
 
 function is_stageable(file_path: string): boolean {
-	return !PATHS_EXCLUDED_FROM_STAGING.includes(file_path)
+	return !observation_ledger.is_ledger_path(file_path)
 }
 
 // **Said out loud, because the alternative is an unexplained failure.** With the ledger the only
@@ -84,7 +86,7 @@ function is_stageable(file_path: string): boolean {
 // step dies on git's empty index with `Failed to commit changes` — a message naming nothing that
 // caused it. This line is what turns that into a diagnosis.
 //
-// **The paths are parsed rather than matched as substrings**: `docs/observations.md.bak` contains the
+// **The paths are parsed rather than matched as substrings**: `docs/maintainers/observations.md.bak` contains the
 // ledger's path, and a hint naming a file the exclusion never touched is a hint that teaches the
 // reader to ignore it.
 function report_excluded_paths(status_output: string): void {

package/scripts/git/git-stash.ts

@@ -14,6 +14,12 @@ const FIELD_SEPARATOR = '\u{0}'
 // stash pushed with `-m`); `%x00` emits the NUL the fields are split on.
 const LIST_FORMAT = '--format=%gd%x00%gs'
 const SUBJECT_MESSAGE_SEPARATOR = ': '
+// `%H` is the entry's commit hash; the second format pairs it with the position a drop needs.
+const HASH_FORMAT = '--format=%H%x00%gs'
+const HASH_POSITION_FORMAT = '--format=%H%x00%gd'
+const NAME_ONLY_FLAG = '--name-only'
+const ADDED_PREFIX = '+'
+const FILE_HEADER_PREFIX = '+++'
 
 interface StashEntry {
 	selector: string
@@ -84,7 +90,7 @@ async function pop(selector: string, directory?: string): Promise<void> {
 // by the unmerged paths it leaves: `--diff-filter=U` lists exactly those, empty on any other failure.
 async function has_conflict(directory?: string): Promise<boolean> {
 	const unmerged = await git_spawn.read(
-		git_args(directory, ['diff', '--name-only', '--diff-filter=U']),
+		git_args(directory, ['diff', NAME_ONLY_FLAG, '--diff-filter=U']),
 	)
 
 	return unmerged !== ''
@@ -102,6 +108,68 @@ async function push(message: string, directory?: string): Promise<void> {
 	await git_spawn.read(git_args(directory, ['stash', 'push', '-u', '-m', message]))
 }
 
+// The stack keyed by commit rather than position (joshuafolkken/kit#2701): a sweep that reads the
+// stack, asks GitHub about each entry and only then drops one would drop whatever another lane pushed
+// on top in the meantime if it kept the `stash@{n}` it read first. The `selector` of each entry here is
+// its commit hash, which never moves.
+async function list_by_hash(directory?: string): Promise<Array<StashEntry>> {
+	return parse_entries(await git_spawn.read(git_args(directory, ['stash', 'list', HASH_FORMAT])))
+}
+
+// The paths an entry carries, untracked files included — `push` stashes with `-u`.
+async function changed_paths(hash: string, directory?: string): Promise<Array<string>> {
+	const raw = await git_spawn.read(
+		git_args(directory, ['stash', 'show', '--include-untracked', NAME_ONLY_FLAG, hash]),
+	)
+
+	return raw === '' ? [] : raw.split(ENTRY_SEPARATOR)
+}
+
+// A path untracked when the entry was pushed with `-u` lives in its third parent, not in its diff, so
+// every line of it is an added one; a path absent from that parent reads as none.
+async function untracked_lines(
+	hash: string,
+	file: string,
+	directory?: string,
+): Promise<Array<string>> {
+	try {
+		const raw = await git_spawn.read(git_args(directory, ['show', `${hash}^3:${file}`]))
+
+		return raw === '' ? [] : raw.split(ENTRY_SEPARATOR)
+	} catch {
+		return []
+	}
+}
+
+// The lines an entry adds to one path, as a unified diff against the commit it was pushed on — or, for
+// a path that was untracked then, the whole file.
+async function added_lines(hash: string, file: string, directory?: string): Promise<Array<string>> {
+	const diff = await git_spawn.read(git_args(directory, ['diff', `${hash}^1`, hash, '--', file]))
+
+	if (diff === '') return await untracked_lines(hash, file, directory)
+
+	return diff
+		.split(ENTRY_SEPARATOR)
+		.filter((line) => line.startsWith(ADDED_PREFIX) && !line.startsWith(FILE_HEADER_PREFIX))
+		.map((line) => line.slice(ADDED_PREFIX.length))
+}
+
+// The position is resolved from the hash immediately before the drop, so an entry pushed since the
+// sweep's read cannot be dropped in its place; an entry already gone answers `false` rather than
+// throwing. Sweeps are serialized by `stash-sweep-lock`, but a plain `git stash push` or `pop` from
+// another command landing between the resolve and the drop still shifts the position — that window is
+// the length of two local git calls.
+async function drop_by_hash(hash: string, directory?: string): Promise<boolean> {
+	const raw = await git_spawn.read(git_args(directory, ['stash', 'list', HASH_POSITION_FORMAT]))
+	const entry = parse_entries(raw).find((candidate) => candidate.selector === hash)
+
+	if (entry === undefined) return false
+
+	await git_spawn.read(git_args(directory, ['stash', 'drop', entry.subject]))
+
+	return true
+}
+
 // The message uncommitted work is pushed with, keyed on the issue so `josh stash:pop` can target it and
 // on the occasion so two pushes for one issue — a lane close and an `already-done` read — stay apart.
 function work_message(issue: string, occasion: string): string {
@@ -109,9 +177,13 @@ function work_message(issue: string, occasion: string): string {
 }
 
 const git_stash = {
+	added_lines,
+	changed_paths,
+	drop_by_hash,
 	has_changes,
 	has_conflict,
 	list,
+	list_by_hash,
 	matches,
 	parse_entries,
 	pop,