@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/run/carry/run-carry-conversation.ts

@@ -25,7 +25,7 @@ import type { CarryOwner, RunCarry } from './run-carry'
 // How long after its last write a conversation whose process has gone still counts as continuing. It
 // bridges a restart and a resume — measured at eighteen seconds — with room for a person reopening a
 // window, and it is the order of the wake grace window, so a genuine crash is recovered no later than
-// a lost wake would be retried.
+// a lost wake would be retried. A headless owner is not given it (`run-carry.ts` → `is_owner_live`).
 const CONVERSATION_QUIET_MS = 600_000
 
 type Environment = Readonly<Record<string, string | undefined>>

package/scripts/run/carry/run-carry-ended.ts

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { durable_state } from '#scripts/josh/durable-state'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
@@ -17,7 +18,7 @@ import type { CarryRead } from './run-carry'
 // **One record, overwritten by the next `--end`**: the board keeps only the run before the next one, and
 // a run that begins replaces nothing here — its carry record is what the board reads while it runs.
 
-const ENDED_PREFIX = 'josh-run-ended-'
+const ENDED_PREFIX = durable_state.PREFIX.ENDED
 const TRANSCRIPT_SUFFIX = '.jsonl'
 
 const ended_run_schema = z.object({
@@ -32,7 +33,7 @@ type EndedRun = z.infer<typeof ended_run_schema>
 
 // Keyed on the common git directory, as the carry record is, so every lane reads the same one.
 function ended_path(git_directory: string): string {
-	return stamp_file.stamp_path(ENDED_PREFIX, git_directory)
+	return durable_state.path(ENDED_PREFIX, git_directory)
 }
 
 function session_of(transcript: string | undefined): string | undefined {

package/scripts/run/carry/run-carry.ts

@@ -1,4 +1,5 @@
 import { git_command } from '#scripts/git/git-command'
+import { durable_state } from '#scripts/josh/durable-state'
 import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
@@ -35,7 +36,7 @@ import { run_carry_conversation } from './run-carry-conversation'
 // reaches, so only a cut the run itself took is carried without anyone deciding. Everything else is
 // an explicit carry-or-discard: `--resume` adopts the standing record, `--end` discards it.
 
-const CARRY_PREFIX = 'josh-run-carry-'
+const CARRY_PREFIX = durable_state.PREFIX.CARRY
 const REPOSITORY_DIRECTORY_INDEX = 1
 const NO_INCREMENT = 0
 
@@ -212,7 +213,7 @@ const run_carry_schema = z.object({
 })
 
 function carry_path(git_directory: string): string {
-	return stamp_file.stamp_path(CARRY_PREFIX, git_directory)
+	return durable_state.path(CARRY_PREFIX, git_directory)
 }
 
 // The common git directory: `.git` in the main work tree and the same `.git` from inside a lane, so
@@ -323,11 +324,16 @@ function adopt_carry(
 // A live pid with no readable start token is conservatively held rather than replaced. The command
 // cannot prove its generation inside that sandbox, but a false `busy` stops for a person while a
 // false `standing` can put two parents on one budget. A record with no pid still resolves false.
-// A gone process whose conversation is still being continued is live (`run-carry-conversation.ts`).
-function is_owner_live(carry: RunCarry, now: Date = new Date()): boolean {
-	if (process_identity.is_same_process(carry.owner_pid, carry.owner_start) !== false) return true
+// A gone process whose conversation is still being continued is live (`run-carry-conversation.ts`);
+// a headless owner is never resumed into a new process, so its gone process is a gone owner.
+function is_owner_live(
+	carry: RunCarry,
+	now: Date = new Date(),
+	same_process: typeof process_identity.is_same_process = process_identity.is_same_process,
+): boolean {
+	if (same_process(carry.owner_pid, carry.owner_start) !== false) return true
 
-	return run_carry_conversation.is_conversation_live(carry, now)
+	return carry.is_owner_headless !== true && run_carry_conversation.is_conversation_live(carry, now)
 }
 
 function is_owned_by(carry: RunCarry, owner: CarryOwner): boolean {

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

@@ -4,19 +4,22 @@ import { agent_session_role } from '#scripts/agent/agent-session-role'
 import { cost_cli } from '#scripts/cost-runtime/cost-cli'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { session_cite } from '#scripts/issue/session-cite'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { openai_lane_supervisor } from '#scripts/lane/openai-lane-supervisor'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_cli_fault } from '#scripts/run/run-cli-fault'
-import { run_cut, type RunCut } from './run-cut'
+import { split_resolution } from '#scripts/split/split-resolution'
+import { run_cut } from './run-cut'
 import { run_cut_args, type Request } from './run-cut-args'
 import { run_cut_decline } from './run-cut-decline'
+import { run_cut_digest } from './run-cut-digest'
 import { run_cut_handoff } from './run-cut-handoff'
 import { run_cut_ready } from './run-cut-ready'
 import { run_cut_report } from './run-cut-report'
+import { run_cut_resume } from './run-cut-resume'
+import { run_cut_review } from './run-cut-review'
 
 // `josh run:cut` — the record that lets a lane child end its process before the gate and a fresh one
 // resume from it. `run:cut <N>` writes the record and relaunches a fresh
@@ -40,15 +43,13 @@ const {
 	FAILED_VERDICT,
 	FAILURE_EXIT_CODE,
 	FRESH_VERDICT,
-	HANDED_OFF_VERDICT,
 	HANDOFF_MISSING_NOTE,
 	HANDOFF_OVERFLOW_NOTE,
-	INCOMPLETE_VERDICT,
 	NOT_A_LANE_VERDICT,
 	OVER_VERDICT,
 	RESUME_IMPL_VERDICT,
 	RESUME_VERDICT,
-	STALE_VERDICT,
+	SPLIT_UNRESOLVED_VERDICT,
 	SUCCESS_EXIT_CODE,
 	UNDER_THRESHOLD_VERDICT,
 	UNREADY_VERDICT,
@@ -57,27 +58,33 @@ const {
 	report_bad_handoff,
 	report_busy,
 	report_fault,
-	report_handed_off,
 	report_held_cut,
-	report_incomplete,
-	report_over,
+	report_missing_supervisor,
 	report_relaunched_cut,
 	report_reviewer,
-	report_stale,
+	report_split_unresolved,
 	report_under_threshold,
 	report_unknown,
-	report_unreadable,
 } = run_cut_report
 
 // **The pre-gate cut is conditional on the same statistic the implementation-phase cut reads**.
-// `cost_cli.session_verdict` prices the newest request against `CONTEXT_CUT_THRESHOLD`, so no second
+// `cost_cli.session_verdict` prices the newest request against the `--cut` break-even, so no second
 // threshold is introduced — an `under` session skips the cut, and an unmeasurable one still cuts as
 // the safety net. Only the pre-gate phase is checked here; the implementation-phase caller gates its own
 // `--impl` cut on `pnpm josh cost --cut` before it is ever issued.
-function skips_pre_gate_cut(phase: string): boolean {
-	if (phase !== run_cut.PRE_GATE_PHASE) return false
+//
+// **A noticed Issue answers the split notice first** (joshuafolkken/kit#4695): the pre-gate cut is the
+// boundary the notice names, so a lane that neither split nor recorded why is refused whether or not
+// the cut itself would be taken. Returns the answer given without cutting, or `undefined`.
+async function pre_gate_answer(issue: string, phase: string): Promise<number | undefined> {
+	if (phase !== run_cut.PRE_GATE_PHASE) return undefined
+	const split_note = await split_resolution.ledger_refusal(Number(issue))
+
+	if (split_note !== undefined) return report_split_unresolved(split_note)
 
 	return cost_cli.session_verdict() === cost_verdict.UNDER_VERDICT
+		? report_under_threshold()
+		: undefined
 }
 
 // The exclusive create lost, so a cut is already in flight for this tree — the double-cut guard. The
@@ -103,18 +110,11 @@ function report_relaunch_failure(target: string, note: string): number {
 	return report(FAILED_VERDICT, FAILURE_EXIT_CODE)
 }
 
-function report_missing_supervisor(issue: string): number {
-	console.error(
-		`The OpenAI supervisor for ${session_cite.issue(issue)} is not live, so this nested process was not cut and can continue. Re-dispatch the lane to recover the supervisor.`,
-	)
-
-	return report(FAILED_VERDICT, FAILURE_EXIT_CODE)
-}
-
 // **The relaunched child is started at the effort of the phase it is resuming into**.
 // A pre-gate resume drives the gate, commit, PR and merge — the mechanical
 // ship/bookkeeping region, lowered — while an implementation resume keeps the role default. The
-// phase-aware profile is `agent_argv.resume_argv`'s; a person's `JOSH_WORKER_EFFORT` still wins over it.
+// phase-aware profile is `agent_argv.resume_argv`'s; a person's `JOSH_WORKER_EFFORT` still wins over it,
+// and a pre-gate resume moves to `JOSH_WORKER_SHIP_MODEL` when that is set.
 function relaunch(target: string, lane: LaneInfo, phase: string): number {
 	const notes: Array<string> = []
 	const result = lane_relaunch.resume(lane, phase, (note) => {
@@ -177,14 +177,18 @@ async function write_cut(target: string, request: CutRequest): Promise<number |
 	const loaded = run_cut_handoff.load_handoff(request.handoff_path, run_cut.MAX_HANDOFF_BYTES)
 	if (loaded.kind === 'bad') return report_bad_handoff(loaded.note)
 
-	const spec = {
+	const base = {
 		issue: request.issue,
 		branch: request.branch,
 		phase: request.phase,
 		handoff: loaded.handoff,
 	}
+	// The checkout, not `target`: the record lives in the temp root, and the transcript is filed by checkout.
+	const checkout = await run_cut.worktree_directory()
+	const spec = run_cut.with_digest(base, () => run_cut_digest.own_digest(checkout))
 
-	const spec_note = spec_refusal(spec)
+	const spec_note =
+		spec_refusal(spec) ?? (await run_cut_review.unrecorded_refusal(request, loaded.handoff))
 
 	if (spec_note !== undefined) return report_bad_handoff(spec_note)
 	if (run_cut.begin_cut(target, spec) === undefined) return report_cut_exists(target)
@@ -247,7 +251,9 @@ async function cut(
 		return await declined({ issue, phase }, state, refuse_unready(state))
 	}
 
-	if (skips_pre_gate_cut(phase)) return report_under_threshold()
+	const answered = await pre_gate_answer(issue, phase)
+
+	if (answered !== undefined) return answered
 
 	clear_expired(target)
 	if (!has_matching_supervisor(lane, issue)) return report_missing_supervisor(issue)
@@ -255,111 +261,6 @@ async function cut(
 	return await finish_cut(target, lane, { issue, branch: state.branch, phase, handoff_path })
 }
 
-// **The adoption is the resume-uniqueness guarantee**: it removes and creates exclusively, so of two
-// racing resumes only one wins the create and the loser is answered `busy`.
-// An implementation cut resumes back into implementation; a pre-gate one into the gate. The resuming
-// child is told which by the verdict rather than reconstructing it from the record.
-function resume_verdict_for(cut_record: RunCut): string {
-	return run_cut.resumes_into_implementation(cut_record.phase)
-		? RESUME_IMPL_VERDICT
-		: RESUME_VERDICT
-}
-
-// **An implementation resume removes the record; a pre-gate one marks it handed off**.
-// The cuts have different multiplicities sharing one record: the pre-gate cut fires once per lane, so
-// its record must survive to answer a second resume `handed-off`; the implementation cut is guarded by the run's
-// event stream rather than the cut record, so its record is cleared on resume — a lingering record
-// would keep the pre-gate guard, which reads `carried_cut_sync`, silent for the rest of the run. A double
-// cut stays impossible either way: `begin_cut`'s exclusive create is what prevents it.
-function take_over(target: string, cut_record: RunCut): RunCut | undefined {
-	if (!run_cut.resumes_into_implementation(cut_record.phase)) {
-		return run_cut.adopt_cut(target, cut_record)
-	}
-
-	run_cut.end_cut(target)
-
-	return cut_record
-}
-
-// The carried instruction and work state, printed to standard error so the resumed session continues
-// on what the run was told to do rather than on the tree alone. The record is cleared
-// on adoption, so this is where it reaches the fresh process.
-function announce_handoff(cut_record: RunCut): void {
-	if (cut_record.handoff !== undefined) {
-		console.error(run_cut_handoff.describe_handoff(cut_record.handoff))
-	}
-}
-
-// **An implementation resume appends a `resume` event**. It clears the record
-// the `cut` event stood for, so the stream is what moves `run:step` back to implementation; a pre-gate
-// resume keeps its record and appends nothing. Best-effort, as the cut's own append is.
-async function emit_resume_event(issue: string, verdict: string): Promise<void> {
-	if (verdict !== RESUME_IMPL_VERDICT) return
-
-	await run_event_stream_emit.emit(
-		run_event_stream.EVENT_KIND.RESUME,
-		`${issue_cite.plain(issue)} resumed`,
-	)
-}
-
-async function adopt(target: string, cut_record: RunCut): Promise<number> {
-	const taken = take_over(target, cut_record)
-
-	if (taken === undefined) return report_busy(cut_record)
-
-	announce_handoff(cut_record)
-
-	const verdict = resume_verdict_for(cut_record)
-
-	await emit_resume_event(cut_record.issue, verdict)
-
-	return report(verdict, SUCCESS_EXIT_CODE)
-}
-
-// A relaunched lane child and a fresh session both measure `under`, so only the session that took an
-// implementation cut resumes over the threshold; unmeasurable is not refused.
-function is_over_threshold_resume(cut_record: RunCut): boolean {
-	if (!run_cut.resumes_into_implementation(cut_record.phase)) return false
-
-	return cost_cli.session_verdict() === cost_verdict.OVER_VERDICT
-}
-
-async function verify_and_adopt(
-	target: string,
-	cut_record: RunCut,
-	issue: string,
-): Promise<number> {
-	const state = await run_cut.current_state()
-	const verdict = run_cut.classify_resume(cut_record, {
-		issue,
-		current_branch: state.branch,
-		is_dirty: state.is_dirty,
-		is_held: state.is_held,
-	})
-
-	if (verdict === HANDED_OFF_VERDICT) return report_handed_off(cut_record)
-
-	if (verdict === 'stale') return report_stale(cut_record)
-
-	if (verdict === INCOMPLETE_VERDICT) return report_incomplete(cut_record)
-
-	if (is_over_threshold_resume(cut_record)) return report_over()
-
-	return await adopt(target, cut_record)
-}
-
-async function resume(target: string, issue: string): Promise<number> {
-	const read = run_cut.read_cut(target)
-
-	if (read.kind === 'none') return report(FRESH_VERDICT, SUCCESS_EXIT_CODE)
-
-	if (read.kind === 'unreadable') return report_unreadable()
-
-	if (read.kind === 'expired') return report_stale(read.cut)
-
-	return await verify_and_adopt(target, read.cut, issue)
-}
-
 function read_json(target: string): number {
 	const read = run_cut.read_cut(target)
 	const cut_record = read.kind === 'carried' || read.kind === 'expired' ? read.cut : undefined
@@ -395,7 +296,7 @@ async function take_cut(target: string, request: CutCommand): Promise<number> {
 async function act(target: string, request: Request): Promise<number> {
 	if (request.kind === 'cut') return await take_cut(target, request)
 
-	if (request.kind === 'resume') return await resume(target, request.issue)
+	if (request.kind === 'resume') return await run_cut_resume.resume(target, request.issue)
 
 	if (request.kind === 'read') return read_json(target)
 
@@ -447,12 +348,11 @@ const run_cut_cli = {
 	ENDED_VERDICT,
 	FAILED_VERDICT,
 	FRESH_VERDICT,
-	HANDED_OFF_VERDICT,
 	NOT_A_LANE_VERDICT,
 	OVER_VERDICT,
 	RESUME_IMPL_VERDICT,
 	RESUME_VERDICT,
-	STALE_VERDICT,
+	SPLIT_UNRESOLVED_VERDICT,
 	UNDER_THRESHOLD_VERDICT,
 	UNREADY_VERDICT,
 	run,

package/scripts/run/cut/run-cut-digest.ts

@@ -0,0 +1,152 @@
+import path from 'node:path'
+import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+import { own_session } from '#scripts/cost-runtime/own-session'
+import { duplicate_reads } from '#scripts/delegation/duplicate-read-guard'
+import { json_value } from '#scripts/lib/json-value'
+import { transcript_record, type TranscriptRecord } from '#scripts/lib/transcript-record'
+import { time_spans } from '#scripts/time-runtime/time-spans'
+import { z } from 'zod'
+
+// What the cut session already read and decided, derived from its own transcript so the resumed
+// process does not spend minutes re-reading to rebuild it (joshuafolkken/kit#5040).
+//
+// **Derived, not written by the agent.** The reads are tool calls and the decisions are the
+// `Auto-decided:` lines the session already logs (`CLAUDE.md` → "Decision autonomy") — in its reply,
+// or in the Issue comment a tool call posts — so the cut takes both from the transcript: nothing to
+// forget, and no handoff key the refusal has to spell out.
+
+interface SessionDigest {
+	read: ReadonlyArray<string>
+	decisions: ReadonlyArray<string>
+}
+
+const session_digest_schema = z.object({
+	read: z.array(z.string()),
+	decisions: z.array(z.string()),
+})
+
+// The newest entries are kept: the record has a byte bound, and the last reads are the ones the
+// resumed work continues from.
+const MAX_READ_ENTRIES = 40
+const MAX_DECISIONS = 12
+const MAX_DECISION_CHARS = 240
+const DECISION_PREFIX = 'Auto-decided:'
+// A logged decision wherever it starts a line or follows a quote or `body=`; the space after the colon
+// keeps out the bare prefix a source file spells.
+const DECISION_LINE = /(?:^|[\s'"=])(Auto-decided: [^\n]+)/gu
+// The quote closing a `body='…'` argument.
+const TRAILING_QUOTES = /['"]$/u
+const ASSISTANT = 'assistant'
+const READ_LABEL = 'Already read before the cut — re-read only the lines you need'
+const DECISIONS_LABEL = 'Decided before the cut — do not reopen'
+
+function shown_path(target: string, cwd: string): string {
+	const relative = path.relative(cwd, path.resolve(cwd, target))
+
+	return relative.startsWith('..') ? target : relative
+}
+
+function newest_unique(entries: ReadonlyArray<string>, limit: number): Array<string> {
+	const unique = [...new Set(entries.toReversed())].toReversed()
+
+	return unique.slice(-limit)
+}
+
+function read_files_of(text: string, cwd: string): Array<string> {
+	const reads = time_spans
+		.parse_timeline(text)
+		.spans.filter((span) => duplicate_reads.is_successful_read(span))
+		.flatMap((span) => span.targets.map((target) => shown_path(target, cwd)))
+
+	return newest_unique(reads, MAX_READ_ENTRIES)
+}
+
+// Where a tool call carries an Issue comment: the Bash command posting it, or the body file a `Write`
+// prepared for it. An `Edit`'s strings are source text, so they are not read.
+const COMMENT_INPUT_KEYS = ['command', 'content']
+
+function input_strings(input: unknown): Array<string> {
+	if (!json_value.is_record(input)) return []
+
+	return COMMENT_INPUT_KEYS.map((key) => input[key]).filter((value) => typeof value === 'string')
+}
+
+// What the session wrote: its reply text and the inputs of its tool calls, where an Issue workflow's
+// decision comment travels.
+function assistant_texts(record: TranscriptRecord | undefined): Array<string> {
+	if (record?.type !== ASSISTANT) return []
+
+	return transcript_record
+		.blocks_of(record)
+		.flatMap((block) => [block.text ?? '', ...input_strings(block.input)])
+}
+
+function decisions_of(text: string): Array<string> {
+	const decisions = text
+		.split('\n')
+		.flatMap((line) => assistant_texts(transcript_record.parse(line)))
+		.flatMap((written) => [...written.matchAll(DECISION_LINE)].map((match) => match[1] ?? ''))
+		.map((line) => line.replace(TRAILING_QUOTES, '').slice(0, MAX_DECISION_CHARS))
+
+	return newest_unique(decisions, MAX_DECISIONS)
+}
+
+function digest_of(text: string, cwd: string): SessionDigest {
+	return { read: read_files_of(text, cwd), decisions: decisions_of(text) }
+}
+
+// The running session's own transcript, or `undefined`. Only a session that names itself is read: the
+// newest-file fallback could pick another session filed under the checkout (a Codex lane's reviewer).
+function own_transcript(cwd: string, environment: NodeJS.ProcessEnv): string | undefined {
+	if (own_session.session_id_of(environment) === undefined) return undefined
+
+	const files = cost_transcript.list_sessions_across(cost_transcript.transcript_directories(cwd))
+	const selection = own_session.select_own_session(files, environment)
+	if (selection.kind === 'absent') return undefined
+
+	const file = files[selection.index]
+
+	return file === undefined ? undefined : cost_transcript.read_optional(file)
+}
+
+// The running session's own digest, or `undefined` when its transcript cannot be found — a cut is
+// never refused for want of one.
+function own_digest(
+	cwd: string = process.cwd(),
+	environment: NodeJS.ProcessEnv = process.env,
+): SessionDigest | undefined {
+	const text = own_transcript(cwd, environment)
+
+	return text === undefined ? undefined : digest_of(text, cwd)
+}
+
+function describe_list(label: string, entries: ReadonlyArray<string>): Array<string> {
+	if (entries.length === 0) return []
+
+	const bullets = entries.map((entry) => `  - ${entry}`).join('\n')
+
+	return [`${label}:\n${bullets}`]
+}
+
+// The block the resume prints; nothing for a digest with neither list.
+function describe_digest(digest: SessionDigest | undefined): string | undefined {
+	if (digest === undefined) return undefined
+
+	const blocks = [
+		...describe_list(READ_LABEL, digest.read),
+		...describe_list(DECISIONS_LABEL, digest.decisions),
+	]
+
+	return blocks.length === 0 ? undefined : blocks.join('\n\n')
+}
+
+const run_cut_digest = {
+	DECISION_PREFIX,
+	describe_digest,
+	digest_of,
+	own_digest,
+	session_digest_schema,
+}
+
+export type { SessionDigest }
+export { run_cut_digest }

package/scripts/run/cut/run-cut-handoff.ts

@@ -25,6 +25,9 @@ interface Handoff {
 	completed: ReadonlyArray<string>
 	remaining: ReadonlyArray<string>
 	untouched: ReadonlyArray<string>
+	// An attested review round's findings not yet `review:record`ed — the conversation that held them is
+	// what the cut drops, so without this the resumed run reruns round 1 (joshuafolkken/kit#4868).
+	findings?: ReadonlyArray<string> | undefined
 }
 
 const handoff_schema = z.object({
@@ -32,6 +35,7 @@ const handoff_schema = z.object({
 	completed: z.array(z.string()),
 	remaining: z.array(z.string()),
 	untouched: z.array(z.string()),
+	findings: z.array(z.string()).optional(),
 })
 
 // The label each list is printed under when the handoff is shown to the resumed session, kept beside
@@ -40,23 +44,34 @@ const COMPLETED_LABEL = 'Completed'
 const REMAINING_LABEL = 'Remaining'
 const UNTOUCHED_LABEL = 'Deliberately untouched'
 const INSTRUCTION_LABEL = 'Instruction (verbatim)'
+const FINDINGS_LABEL =
+	'Round-1 findings, attested but not recorded — do not rerun round 1: fix them, then record them with `pnpm josh review:record --issue <N>`'
 const EMPTY_LIST_NOTE = '(none)'
 
 type HandoffKey = keyof Handoff
 
-function describe_key(key: HandoffKey): string {
-	const value = handoff_schema.shape[key] instanceof z.ZodArray ? '["…"]' : '"…"'
-
-	return `"${key}": ${value}`
+// The placeholders each example value is drawn with; `findings`' says which round it carries. They
+// parse, so a copied example is read as entries — `carried_findings` drops them, or a copied
+// `findings` would pass the unrecorded-round refusal.
+const PLACEHOLDER = '…'
+const FINDINGS_PLACEHOLDER = 'unrecorded'
+const EXAMPLE_LIST = `["${PLACEHOLDER}"]`
+
+const EXAMPLE_VALUES: Readonly<Record<HandoffKey, string>> = {
+	instruction: `"${PLACEHOLDER}"`,
+	completed: EXAMPLE_LIST,
+	remaining: EXAMPLE_LIST,
+	untouched: EXAMPLE_LIST,
+	findings: `["${FINDINGS_PLACEHOLDER}"]`,
 }
 
-// The shape a handoff file must have, derived from `handoff_schema` so the refusal that asks for the file
+// The shape a handoff file must have, keyed from `handoff_schema` so the refusal that asks for the file
 // and the error that rejects it can never name a key the parser does not read — a refusal listing the
 // items in prose invites Markdown, which `parse_handoff` rejects.
-const HANDOFF_FORMAT = `a JSON object {${handoff_schema
+const HANDOFF_FORMAT = `{${handoff_schema
 	.keyof()
-	.options.map((key) => describe_key(key))
-	.join(', ')}}`
+	.options.map((key) => `"${key}":${EXAMPLE_VALUES[key]}`)
+	.join(',')}}`
 
 function parse_handoff(raw: string): Handoff | undefined {
 	return json_value.parse_with(raw, handoff_schema)
@@ -115,6 +130,25 @@ function describe_list(label: string, items: ReadonlyArray<string>): string {
 	return `${label}:\n${bullets}`
 }
 
+// The findings a handoff really carries: a blank entry or an example placeholder is no finding.
+function carried_findings(handoff: Handoff | undefined): ReadonlyArray<string> {
+	const findings = handoff?.findings ?? []
+
+	return findings.filter(
+		(finding) => ![PLACEHOLDER, FINDINGS_PLACEHOLDER, ''].includes(finding.trim()),
+	)
+}
+
+// Carried findings are printed only when there are some — a handoff cut before any review says nothing
+// about one.
+function describe_findings(handoff: Handoff): ReadonlyArray<string> {
+	const findings = carried_findings(handoff)
+
+	if (findings.length === 0) return []
+
+	return [describe_list(FINDINGS_LABEL, findings)]
+}
+
 // The block the resume prints to standard error so the fresh process continues on the original
 // instruction rather than the tree alone.
 function describe_handoff(handoff: Handoff): string {
@@ -123,17 +157,27 @@ function describe_handoff(handoff: Handoff): string {
 		describe_list(COMPLETED_LABEL, handoff.completed),
 		describe_list(REMAINING_LABEL, handoff.remaining),
 		describe_list(UNTOUCHED_LABEL, handoff.untouched),
+		...describe_findings(handoff),
 	].join('\n\n')
 }
 
-// Where a handoff file is written: `.claude/tmp/` is ignored, so `josh git`, which stages every
+// Where a handoff file is written: `.josh/tmp/` is ignored, so `josh git`, which stages every
 // untracked non-ignored file, cannot commit the note with the code. A refusal that asked for "a file"
 // and named no place got one written beside the code and committed (joshuafolkken/kit#3603).
-const HANDOFF_PATH = '.claude/tmp/handoff-<N>.json'
+const HANDOFF_PATH = '.josh/tmp/handoff-<N>.json'
+const ISSUE_PLACEHOLDER = '<N>'
+
+// The handoff path for one issue, relative to the checkout — the path `HANDOFF_PATH` tells the run
+// to write, so the implementation-cut guard can let that one write through.
+function handoff_path_of(issue: string): string {
+	return HANDOFF_PATH.replace(ISSUE_PLACEHOLDER, () => issue)
+}
 
 const run_cut_handoff = {
 	HANDOFF_FORMAT,
 	HANDOFF_PATH,
+	handoff_path_of,
+	carried_findings,
 	describe_handoff,
 	handoff_schema,
 	is_complete_handoff,