@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/scripts/propagate/propagate-run.ts

@@ -65,13 +65,17 @@ const SKIP_REASONS: Readonly<Record<string, string>> = {
 	missing_checkout: 'no local checkout at the mapped path — reported, not cloned',
 	unreadable: 'package.json could not be read',
 	not_selected: 'not the repository --target named',
+	carried_above: 'delivered by the propagation of a toolkit above this one',
 }
 
 // The reason text for a candidate that is not going to be processed. A missing local checkout is
 // reported rather than cloned: propagation writes to a working tree, and creating one nobody asked
 // for is not a step this command may take on its own.
 function skip_reason(target: PropagateTarget): string {
-	return SKIP_REASONS[target.state] ?? 'not eligible'
+	const reason = SKIP_REASONS[target.state] ?? 'not eligible'
+	if (target.carriers === undefined) return reason
+
+	return `${reason}: ${target.carriers.join(', ')}`
 }
 
 const LEFTOVER_NOTE = 'upgrade/sync changes left uncommitted'

package/scripts/propagate/propagate-steps.ts

@@ -3,6 +3,7 @@ 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 { error_text } from '#scripts/lib/error-message'
 import { build_upgrade_shell_command } from '#scripts/version/upgrade-shell-command'
 import { create_version_command_config } from '#scripts/version/version-command-config'
 import { execaSync } from 'execa'
@@ -87,13 +88,28 @@ function release_names(releases: ReadonlyArray<Release>): string {
 	return `${names.slice(0, -1).join(NAME_SEPARATOR)}${LAST_SEPARATOR}${last}`
 }
 
+// Each release with its own version, for a plan whose releases disagree on one — a toolkit's
+// propagation carries the base packages at the versions that toolkit was verified with
+// (joshuafolkken/kit#2879), so one shared "to <version>" would name a version most of them are not.
+function versioned_names(releases: ReadonlyArray<Release>): string {
+	const named = releases.map((release) => ({
+		...release,
+		package_name: `${release.package_name} to ${release.version}`,
+	}))
+
+	return `Upgrade ${release_names(named)}`
+}
+
 // One release reproduces `issue_title` exactly, which is what keeps a `propagate` run's issue title
 // unchanged by the generalization.
 function plan_title(releases: ReadonlyArray<Release>): string {
 	const [first] = releases
 	if (first === undefined) return EMPTY_PLAN_TITLE
+	const is_one_version = releases.every((release) => release.version === first.version)
 
-	return issue_title(release_names(releases), first.version)
+	return is_one_version
+		? issue_title(release_names(releases), first.version)
+		: versioned_names(releases)
 }
 
 function plan_body(plan: ReleasePlan): string {
@@ -235,7 +251,7 @@ function precheck_step(target: PropagateTarget, step: string): StepResult {
 // multi-line detail would print raw JSON as an unindented second line and glue that warning to the
 // end of it, where nobody reading the report would see it.
 function to_issue_detail(error: unknown): string {
-	const message = error instanceof Error ? error.message : String(error)
+	const message = error_text.message_of(error)
 
 	return message.replaceAll('\n', ' ').trim()
 }

package/scripts/propagate/propagate-targets.ts

@@ -20,9 +20,17 @@ const MANIFEST_NAME = 'package.json'
 const NODE_MODULES = 'node_modules'
 
 // Why a candidate is not going to be processed, or that it is. `not_selected` is the one state set
-// after classification: a candidate `--target` left out (joshuafolkken/kit#2755).
+// after classification: a candidate `--target` left out (joshuafolkken/kit#2755). `carried_above` is
+// the other: a consumer that installs a toolkit above the supplier, which that toolkit's own
+// propagation delivers instead (joshuafolkken/kit#2879).
 type TargetState =
-	'ready' | 'up_to_date' | 'not_downstream' | 'missing_checkout' | 'unreadable' | 'not_selected'
+	| 'ready'
+	| 'up_to_date'
+	| 'not_downstream'
+	| 'missing_checkout'
+	| 'unreadable'
+	| 'not_selected'
+	| 'carried_above'
 
 interface PropagateTarget {
 	repo: string
@@ -31,6 +39,9 @@ interface PropagateTarget {
 	// The range the consumer currently declares, when it declares one at all. Reported so a skip can
 	// say what it skipped rather than only that it did.
 	declared_range?: string
+	// The toolkits above the supplier this consumer installs, when it is `carried_above` — named in
+	// the skip so the report says which propagation will deliver it.
+	carriers?: ReadonlyArray<string>
 }
 
 // Only the fields propagation reads. `passthrough` is deliberate — a consumer manifest carries far

package/scripts/propagate/propagate.ts

@@ -2,17 +2,16 @@
 import { fileURLToPath } from 'node:url'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { refuse_unknown_flags } from '#scripts/lib/cli-flags'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { status_icons } from '#scripts/lib/status-icons'
-import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
-import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { derive_versions_endpoint } from '#scripts/version/version-command-config'
 import { version_targets } from '#scripts/version/version-targets'
 import { propagate_git } from './propagate-git'
+import { propagate_plan } from './propagate-plan'
 import { propagate_publish } from './propagate-publish'
 import { propagate_run } from './propagate-run'
 import { propagate_select, type TargetSelection } from './propagate-select'
-import { propagate_steps } from './propagate-steps'
+import { propagate_steps, type ReleasePlan } from './propagate-steps'
 import { propagate_targets, type PropagateTarget } from './propagate-targets'
 
 // `josh propagate` — carry the release this repository just published into every consumer checked
@@ -72,12 +71,14 @@ function parse_options(argv: ReadonlyArray<string>): RunOptions {
 		...(target !== undefined && { target }),
 	}
 	const usage =
-		target_usage ?? refuse_unknown_flags(rest, [...KNOWN_FLAGS, TARGET_USAGE], 'propagate')
+		target_usage ??
+		cli_flags.refuse_unknown_flags(rest, [...KNOWN_FLAGS, TARGET_USAGE], 'propagate')
 
 	return usage === undefined ? options : { ...options, usage }
 }
 
-// Propagation runs from the supplier's own repository, and only there.
+// Propagation runs from the supplier's own repository, and only there — kit's, or a toolkit's built
+// on it (joshuafolkken/kit#2879).
 //
 // This is also what decides who propagates when several sessions are running: in the
 // per-repository concurrency model there is one session per checkout, so the session standing in
@@ -85,13 +86,7 @@ function parse_options(argv: ReadonlyArray<string>): RunOptions {
 // convention enforced at the boundary, not a lock — two checkouts of the supplier would both pass,
 // which is why each consumer is additionally refused unless its working tree is clean.
 function refuse_outside_source_repository(project_root: string): string | undefined {
-	if (self_sync_guard.read_package_name(project_root) === KIT_PACKAGE_NAME) return undefined
-
-	return [
-		`Refusing to propagate: this is not ${KIT_PACKAGE_NAME}'s own repository.`,
-		'Propagation carries a published release outward, so it runs from the package that published it.',
-		`Run it from the ${KIT_PACKAGE_NAME} checkout instead.`,
-	].join('\n')
+	return propagate_plan.resolve_supplier(project_root).refusal
 }
 
 // The version to carry: this repository's own declared version, which is what the merge published.
@@ -143,10 +138,14 @@ function resolve_run_version(project_root: string, is_dry_run = false): RunVersi
 	return resolve_supplier_version(project_root, is_dry_run)
 }
 
-async function await_publish(target_version: string, is_skipped: boolean): Promise<boolean> {
+async function await_publish(
+	package_name: string,
+	target_version: string,
+	is_skipped: boolean,
+): Promise<boolean> {
 	if (is_skipped) return true
-	console.info(`Waiting for ${KIT_PACKAGE_NAME}@${target_version} to appear in the registry…`)
-	const endpoint = derive_versions_endpoint(KIT_PACKAGE_NAME)
+	console.info(`Waiting for ${package_name}@${target_version} to appear in the registry…`)
+	const endpoint = derive_versions_endpoint(package_name)
 	const result = await propagate_publish.wait_for_publish(endpoint, target_version)
 
 	if (result.state === 'published') {
@@ -178,49 +177,65 @@ function announce_run_version(resolved: RunVersion): string | undefined {
 
 interface RunPlan {
 	version: string
+	releases: ReleasePlan
 	targets: ReadonlyArray<PropagateTarget>
 }
 
 // The consumers this run will consider, narrowed by `--target`. Resolved before the publish wait so
-// a mistyped name fails at once instead of after minutes of polling the registry.
-function resolve_run_targets(version: string, target: string | undefined): TargetSelection {
+// a mistyped name fails at once instead of after minutes of polling the registry. A consumer that
+// installs a toolkit above the supplier is left to that toolkit's propagation (joshuafolkken/kit#2879).
+function resolve_run_targets(
+	releases: ReleasePlan,
+	version: string,
+	target: string | undefined,
+): TargetSelection {
 	const map = repo_discovery.discover_repositories(PROJECT_ROOT)
-	const targets = propagate_targets.resolve_targets(map, KIT_PACKAGE_NAME, version)
+	const supplier = propagate_plan.supplier_name(releases)
+	const targets = propagate_targets
+		.resolve_targets(map, supplier, version)
+		.map((candidate) => propagate_plan.mark_carried(candidate, releases))
 
 	return propagate_select.select_target(targets, target)
 }
 
-// The version and the consumers, or nothing once whatever stopped the run has been printed.
+// Print why the run stopped before any consumer was touched.
+function refuse_run(refusal: string): void {
+	console.error(refusal)
+	console.error(UNTOUCHED_NOTE)
+}
+
+interface PlanOutcome {
+	plan?: RunPlan
+	refusal?: string
+}
+
+// The releases and the consumers for a version already accepted, or the reason there are none.
+function plan_consumers(version: string, options: RunOptions): PlanOutcome {
+	const { plan: releases, refusal } = propagate_plan.build_plan(PROJECT_ROOT, version)
+	if (releases === undefined) return { refusal: refusal ?? UNTOUCHED_NOTE }
+	const selection = resolve_run_targets(releases, version, options.target)
+	if (selection.refusal !== undefined) return { refusal: selection.refusal }
+
+	return { plan: { version, releases, targets: selection.targets } }
+}
+
+// The version, the releases and the consumers, or nothing once whatever stopped the run has been
+// printed.
 function plan_run(options: RunOptions): RunPlan | undefined {
 	const version = announce_run_version(resolve_run_version(PROJECT_ROOT, options.is_dry_run))
 	if (version === undefined) return undefined
-	const selection = resolve_run_targets(version, options.target)
+	const { plan, refusal } = plan_consumers(version, options)
+	if (refusal !== undefined) refuse_run(refusal)
 
-	if (selection.refusal !== undefined) {
-		console.error(selection.refusal)
-		console.error(UNTOUCHED_NOTE)
-
-		return undefined
-	}
-
-	return { version, targets: selection.targets }
+	return plan
 }
 
 // Everything after the publish wait: run each consumer, print one report.
 function propagate_to_consumers(plan: RunPlan, is_dry_run: boolean): number {
-	const { version, targets } = plan
+	const { releases, targets } = plan
 	const step = is_dry_run
-		? propagate_steps.describe_step
-		: propagate_steps.create_step_runner({
-				releases: [
-					{
-						package_name: KIT_PACKAGE_NAME,
-						version,
-						bin_name: propagate_steps.JOSH_BIN,
-					},
-				],
-				origin: propagate_steps.PROPAGATE_ORIGIN,
-			})
+		? propagate_plan.create_step_describer(releases)
+		: propagate_steps.create_step_runner(releases)
 	const results = propagate_run.run_targets(
 		targets,
 		step,
@@ -235,8 +250,12 @@ function propagate_to_consumers(plan: RunPlan, is_dry_run: boolean): number {
 
 // A dry run never waits: the whole reason to ask for one is to see the target list, and a wait that
 // times out would end the run before the list was ever printed.
-async function resolve_publish(version: string, options: RunOptions): Promise<boolean> {
-	return await await_publish(version, options.is_dry_run || options.is_publish_wait_skipped)
+async function resolve_publish(plan: RunPlan, options: RunOptions): Promise<boolean> {
+	return await await_publish(
+		propagate_plan.supplier_name(plan.releases),
+		plan.version,
+		options.is_dry_run || options.is_publish_wait_skipped,
+	)
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
@@ -250,7 +269,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	const plan = plan_run(options)
 	if (plan === undefined) return FAILURE_EXIT_CODE
-	if (!(await resolve_publish(plan.version, options))) return FAILURE_EXIT_CODE
+	if (!(await resolve_publish(plan, options))) return FAILURE_EXIT_CODE
 
 	return propagate_to_consumers(plan, options.is_dry_run)
 }

package/scripts/refactor/import-graph.ts

@@ -1,5 +1,5 @@
-import { readFileSync } from 'node:fs'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 
 // The scope expansion `prompts/refactoring.md` §4.3 used to describe in prose (joshuafolkken/kit#2180):
 // from the seed files, follow imports both ways — the files a seed imports and the files that import a
@@ -67,11 +67,7 @@ function resolve_spec(
 }
 
 function read_source(file: string): string {
-	try {
-		return readFileSync(file, 'utf8')
-	} catch {
-		return ''
-	}
+	return file_reader.read_if_readable(file) ?? ''
 }
 
 function file_imports(file: string, root: string, known: ReadonlySet<string>): ReadonlySet<string> {

package/scripts/registry-migration/migrate-logic.ts

@@ -219,6 +219,7 @@ function plan(project_npmrc: string, user_npmrc: string, lockfile: string): Migr
 const migrate_logic = {
 	plan,
 	github_tarballs,
+	is_github_tarball,
 	rewrite_kit_lockfile,
 	registry_of,
 	scoped_packages,

package/scripts/registry-migration/migrate.ts

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { file_reader } from '#scripts/lib/read-file'
 import { execa } from 'execa'
 import { z } from 'zod'
 import { migrate_logic, type MigrationPlan } from './migrate-logic'
@@ -70,7 +71,7 @@ interface MigrationContext {
 }
 
 function read_file(file_path: string): string {
-	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
+	return file_reader.read_file_or_empty(file_path)
 }
 
 function has_registry_override(environment: NodeJS.ProcessEnv): boolean {

package/scripts/registry-migration/user-npmrc.ts

@@ -1,13 +1,13 @@
-import { existsSync, readFileSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 
 const NPMRC = '.npmrc'
 
 function read(home: string = os.homedir()): string {
 	const file = path.join(home, NPMRC)
 
-	return existsSync(file) ? readFileSync(file, 'utf8') : ''
+	return file_reader.read_file_or_empty(file)
 }
 
 const user_npmrc = { read }

package/scripts/release/github-release.ts

@@ -4,7 +4,7 @@ import { z } from 'zod'
 
 const API_URL = 'https://api.github.com/repos/joshuafolkken/kit/releases'
 const WORKFLOW_RUNS_URL =
-	'https://api.github.com/repos/joshuafolkken/kit/actions/workflows/publish.yml/runs?event=repository_dispatch&per_page=100'
+	'https://api.github.com/repos/joshuafolkken/kit/actions/workflows/publish.yml/runs?per_page=100'
 const WORKFLOW_JOBS_URL = 'https://api.github.com/repos/joshuafolkken/kit/actions/runs'
 const TAG_PATTERN = /^v\d+\.\d+\.\d+(?:[.-][0-9A-Za-z.-]+)?$/u
 const REQUEST_TIMEOUT_MS = 30_000

package/scripts/release/release-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_command } from '#scripts/git/git-command'
+import { error_text } from '#scripts/lib/error-message'
 import { release_history } from './release-history'
 import { release_plan, type ReleasePlan } from './release-plan'
 import { release_publish } from './release-publish'
@@ -76,7 +77,7 @@ async function main(): Promise<void> {
 	try {
 		process.exit(await run(is_dry_run_requested(process.argv)))
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(FAILURE_EXIT_CODE)
 	}
 }

package/scripts/repo/repo-setting.ts

@@ -1,7 +1,5 @@
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
-import { execaSync } from 'execa'
 
 // The shared half of every "report a GitHub repository setting kit cannot write" check.
 //
@@ -27,17 +25,21 @@ interface RepoApiResult {
 	stdout: string
 }
 
+const FAILED_EXIT_CODE = 1
+
 // One `gh api` call. Never throws and never propagates a non-zero exit: an unreadable answer is a
-// reported status, not a command failure.
+// reported status, not a command failure. Every failure reads as `FAILED_EXIT_CODE` with no output,
+// which `parse_payload` treats as unreadable whatever gh's own exit code was.
 function query_repo_api(api_path: string): RepoApiResult {
-	const result = execaSync('gh', ['api', api_path], {
-		...git_gh_exec.direct_environment(),
+	const stdout = git_gh_exec.read_gh_api_sync({
+		path: api_path,
 		cwd: PROJECT_ROOT,
-		reject: false,
-		timeout: GH_TIMEOUT_MS,
+		timeout_ms: GH_TIMEOUT_MS,
 	})
 
-	return { exit_code: result.exitCode ?? 1, stdout: read_spawn_stdout(result) }
+	return stdout === undefined
+		? { exit_code: FAILED_EXIT_CODE, stdout: '' }
+		: { exit_code: 0, stdout }
 }
 
 // The response body as an object, or nothing. A non-zero exit covers every case where the answer

package/scripts/review/review-attest.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from 'node:crypto'
+import { lstatSync } from 'node:fs'
 import { git_command } from '#scripts/git/git-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
@@ -240,6 +241,47 @@ function check(now: number = Date.now(), root?: string): AttestVerdict {
 	return verdict
 }
 
+function is_written_since(source: string, taken_at: string): boolean {
+	try {
+		const stats = lstatSync(source)
+
+		return stats.isFile() && stats.mtimeMs >= Date.parse(taken_at)
+	} catch {
+		return false
+	}
+}
+
+// **Whether the last briefed review of this branch finished** (joshuafolkken/kit#2945). A ship resumed
+// after a stop re-issues round 1, and without this answer it briefed the whole change again — the
+// files the finished review had just read, re-read at full cost. It is asked before `record_target`
+// mints the next nonce, since that call drops the record it reads. The branch must match: the pointer
+// is keyed on the root, and a lane root outlives the branch a previous run reviewed there.
+//
+// **An attestation alone is not a finished review.** The reviewer may attest and then die before it
+// reports — a timeout, a usage limit — and narrowing on that would call files nobody read "already
+// read". So the findings file, written only once the review has its verdict, must postdate the brief
+// this pointer names; one left from an earlier review is older than that brief and does not count.
+function is_reviewed_on(checkout: ReviewCheckout, findings_path: string, root?: string): boolean {
+	const pointer = read_pointer(root)
+
+	if (pointer === undefined) return false
+
+	const verdict = verdict_for(pointer.nonce)
+
+	if (verdict.status !== 'ok' || verdict.expected?.branch !== checkout.branch) return false
+
+	return is_written_since(findings_path, pointer.taken_at)
+}
+
+// Whether a record written at `written_at` belongs to the brief the pointer names rather than an earlier
+// one (joshuafolkken/kit#2945): that brief writes it right after minting the pointer. ISO timestamps
+// order as strings.
+function is_briefed_since(written_at: string, root?: string): boolean {
+	const pointer = read_pointer(root)
+
+	return pointer !== undefined && written_at >= pointer.taken_at
+}
+
 // The pointer is keyed on the repository root rather than on `process.cwd()`, which is what
 // `PROJECT_ROOT` is. `josh review:brief` records against the root it just asked git for, so the check
 // has to ask the same question: run the two from different directories — one from `scripts/`, one
@@ -303,6 +345,8 @@ const review_attest = {
 	clear_here,
 	EXPECT_PREFIX,
 	expect_path,
+	is_briefed_since,
+	is_reviewed_on,
 	MISMATCH_VERDICT,
 	MISSING_REASON,
 	POINTER_PREFIX,

package/scripts/review/review-brief-cli.ts

@@ -6,8 +6,13 @@ import { scoped_green } from '#scripts/gate/scoped-green'
 import { change_base } from '#scripts/git/change-base'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_command } from '#scripts/git/git-command'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { find_package_directory } from '#scripts/josh/josh-logic'
 import { path_decision } from '#scripts/josh/path-decision'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { openai_review_broker } from '#scripts/lane/openai-review-broker'
+import { run_ship_review } from '#scripts/run/run-ship-review'
 import { review_attest } from './review-attest'
 import { review_brief } from './review-brief'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
@@ -134,13 +139,54 @@ function record_round_one(
 // failed to record would hand the review a command that cannot succeed and the run a check that
 // answers `not-required` — the guard gone, silently, which is the shape this whole record exists to
 // remove.
-async function open_contract(): Promise<{ checkout: ReviewCheckout; nonce: string }> {
+//
+// **Whether this is a resume is read first** (joshuafolkken/kit#2945): `record_target` drops the
+// previous nonce's records, so asked afterwards the finished review would always read as absent. The
+// findings file is the ship's, keyed on `PROJECT_ROOT` as the ship keys it; a review run outside the
+// ship writes none, so it never reads as a resume and keeps the whole change.
+//
+// **The narrowing is measured from the tree that review was briefed on**, and only when that record
+// was written by the brief the pointer names: one left by an earlier brief is not the tree the
+// finished review read, so the resume reads the whole change instead.
+function attested_tree(checkout: ReviewCheckout): FileMapStamp | undefined {
+	const { findings } = openai_review_broker.review_paths(PROJECT_ROOT)
+	const briefed = review_stamps.briefed_stamp.read()
+
+	if (briefed === undefined || !review_attest.is_briefed_since(briefed.taken_at, checkout.root)) {
+		return undefined
+	}
+
+	const is_clean =
+		review_attest.is_reviewed_on(checkout, findings, checkout.root) &&
+		run_ship_review.is_clean_round_one(stamp_file.read_stamp_text(findings))
+
+	return is_clean ? briefed : undefined
+}
+
+async function open_contract(): Promise<{
+	checkout: ReviewCheckout
+	nonce: string
+	resumed_from: FileMapStamp | undefined
+}> {
 	const checkout = await review_checkout.read_checkout()
+	const resumed_from = attested_tree(checkout)
 
 	// Keyed on the root git just answered with, never on `process.cwd()`: the check made before the
 	// merge asks git the same question, and the two hash different keys the moment one of them runs
 	// from a subdirectory — a mismatch that would drop the guard with nothing printed.
-	return { checkout, nonce: review_attest.record_target(checkout, checkout.root) }
+	return { checkout, nonce: review_attest.record_target(checkout, checkout.root), resumed_from }
+}
+
+// Retaken on every round-1 brief, after the pointer it pairs with (joshuafolkken/kit#2945). Swallowed:
+// a record that failed to write predates the next pointer, so the resume widens rather than narrows.
+function record_briefed(round: number, tree: Record<string, string>, base?: string): void {
+	if (round !== FIRST_ROUND) return
+
+	try {
+		review_stamps.briefed_stamp.write(tree, undefined, base)
+	} catch {
+		/* no record widens the resume rather than narrowing it */
+	}
 }
 
 interface ComposeRequest {
@@ -252,6 +298,7 @@ async function run_review(round: number, reading: ChangeReading): Promise<number
 	if (resolved.kind === 'rejected') return report_error(resolved.note)
 	console.info(await compose_brief({ round, paths, tree, base, profile: resolved.profile }))
 	record_round_one(round, tree, commit)
+	record_briefed(round, tree, commit)
 
 	return 0
 }

package/scripts/review/review-brief.ts

@@ -357,6 +357,39 @@ function round_two_block(
 	return narrow_block(scope.recorded_at, scope, root, base)
 }
 
+// **A resumed round 1 reads what changed since the attested review, reusing round 2's reconciliation**
+// (joshuafolkken/kit#2945). A ship that stopped and was re-issued briefed the whole change again, so
+// the reviewer re-read every file the attested review had just read. The scope is the comparison round
+// 2 makes, measured from the tree that review was briefed on. Every reading that cannot narrow falls back to the whole
+// change: no record, a moved base, or an empty target. An empty target is included because a resumed
+// review that read nothing would report a clean verdict over the one already recorded.
+const RESUMED_HEADING =
+	'Resumed round 1 — a review of this branch was already attested, so this pass reads only what changed since the tree it read.'
+
+const RESUMED_QUESTION =
+	'Review these files in full against the rubric — they are the only code this pass has not already read.'
+
+function resumed_target(
+	snapshot: FileMapStamp | undefined,
+	tree: Record<string, string>,
+	root: string,
+	base: string,
+): string {
+	const scope = round_two_scope(snapshot, tree, base)
+
+	if (scope.recorded_at === undefined || scope.target.length === 0) {
+		return whole_change_target(root, base)
+	}
+
+	return [
+		RESUMED_HEADING,
+		`The attested review read the tree recorded at ${scope.recorded_at}.`,
+		`Target: only these files, which changed since that tree:\n${format_paths(root, scope.target)}`,
+		...reconciliation(root, base, scope),
+		RESUMED_QUESTION,
+	].join('\n')
+}
+
 interface BriefStamps {
 	gate: FileMapStamp | undefined
 	in_flight: FileMapStamp | undefined
@@ -377,12 +410,23 @@ interface BriefInput {
 	// The rubric's absolute path, resolved by the caller against the kit package rather than the review
 	// checkout, so it resolves in a consumer that ships no `prompts/` of its own (joshuafolkken/kit#2402).
 	rubric_path: string
+	// The tree a finished, clean review of this branch was briefed on, so round 1 is a resume
+	// (joshuafolkken/kit#2945). Absent, round 1 reads the whole change.
+	resumed_from?: FileMapStamp | undefined
 }
 
 const SECOND_ROUND = 2
 
+function round_one_target(input: BriefInput): string {
+	const { root } = input.checkout
+
+	if (input.resumed_from === undefined) return whole_change_target(root, input.base)
+
+	return resumed_target(input.resumed_from, input.tree, root, input.base)
+}
+
 function target_block(input: BriefInput): string {
-	if (input.round < SECOND_ROUND) return whole_change_target(input.checkout.root, input.base)
+	if (input.round < SECOND_ROUND) return round_one_target(input)
 
 	return round_two_block(input.stamps.round_one, input.tree, input.checkout.root, input.base)
 }
@@ -422,6 +466,7 @@ const review_brief = {
 	green_stamp,
 	in_flight_line,
 	live_marker,
+	RESUMED_HEADING,
 	matching_stamp,
 	no_snapshot_line,
 	NOTHING_LEFT_LINE,

package/scripts/review/review-finding-ledger.ts

@@ -1,9 +1,9 @@
 // The review-finding line's grammar, its category vocabulary and the aggregation over it — the single
 // place all three are defined (joshuafolkken/kit#2325). A `/code-review` round's findings evaporated
 // the moment they were fixed, so no one could say which category recurred. They now land in the same
-// append-only ledger the observation lines use (`docs/maintainers/observations.md`), under a distinct `- rf:`
-// prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger
-// file, one flush path, a second line *type* rather than a second ledger.
+// append-only ledger the observation lines use (`docs/maintainers/observations/`), under a distinct `- rf:`
+// prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger,
+// one commit path, a second line *type* rather than a second ledger.
 
 const FINDING_PREFIX = '- rf:'
 const FIELD_SEPARATOR = ' | '