@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/issue/issue-evidence-exit.ts

@@ -0,0 +1,102 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { cli_body } from '#scripts/josh/cli-body'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
+import { run_hold_cli } from '#scripts/run/hold/run-hold-cli'
+
+// The shape every evidence exit shares — `josh issue:already-done` and `josh issue:measured`: the
+// evidence comment, the exit's own finishing write, then the `run:release`, in that order.
+//
+// **The order is the point.** The finishing write without the comment is an uncited claim, so the
+// comment goes first and each step runs only once the one before it landed — a failure stops there
+// and names the step.
+
+const FAILURE_EXIT_CODE = 1
+const EVIDENCE_FILE_FLAG = '--evidence-file'
+const OPTIONS = { 'evidence-file': { type: 'string' } } as const
+
+interface EvidenceRequest {
+	issue_number: string
+	evidence: string
+}
+
+// `admit`, when given, runs once the request parsed and before the first write: an exit that does not
+// fit the Issue refuses there, with nothing written.
+interface EvidenceExit {
+	command: string
+	finish: (issue_number: string) => Promise<boolean>
+	admit?: (issue_number: string) => Promise<boolean>
+}
+
+// An evidence file that is empty or whitespace only is refused before anything is written: a comment
+// with no citations is not the finding an exit is for. The throw carries the reason to `run`.
+function parse_request(argv: ReadonlyArray<string>): EvidenceRequest | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return undefined
+	const issue_number = issue_number_shape.single_of(parsed.positionals)
+	const file_path = parsed.values['evidence-file']
+	if (issue_number === undefined || file_path === undefined) return undefined
+	const evidence = cli_body.read_file_or_stdin(file_path).trim()
+	if (evidence.length === 0) throw new Error(`Evidence file is empty: ${file_path}`)
+
+	return { issue_number, evidence }
+}
+
+// A file-read failure or an empty file is an `Error` naming the path, printed as-is; every other
+// refusal is `undefined`, which the usage line explains.
+function resolve_request(
+	argv: ReadonlyArray<string>,
+	command: string,
+): EvidenceRequest | undefined {
+	try {
+		const request = parse_request(argv)
+
+		if (request === undefined) {
+			console.error(`Usage: josh ${command} <issue-number> ${EVIDENCE_FILE_FLAG} <path>`)
+		}
+
+		return request
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return undefined
+	}
+}
+
+async function post_evidence(request: EvidenceRequest): Promise<boolean> {
+	try {
+		console.info(await git_gh_command.issue_comment(request.issue_number, request.evidence))
+
+		return true
+	} catch (error) {
+		console.error(`Evidence comment not posted: ${error_text.message_of(error)}`)
+
+		return false
+	}
+}
+
+// Each write runs only once the one before it landed: `&&` stops at the first that did not.
+async function write_exit(request: EvidenceRequest, exit: EvidenceExit): Promise<boolean> {
+	return (await post_evidence(request)) && (await exit.finish(request.issue_number))
+}
+
+async function is_admitted(request: EvidenceRequest, exit: EvidenceExit): Promise<boolean> {
+	return exit.admit === undefined || (await exit.admit(request.issue_number))
+}
+
+async function run(argv: ReadonlyArray<string>, exit: EvidenceExit): Promise<number> {
+	const request = resolve_request(argv, exit.command)
+	if (request === undefined || !(await is_admitted(request, exit))) return FAILURE_EXIT_CODE
+
+	return (await write_exit(request, exit))
+		? await run_hold_cli.run(['--release', request.issue_number])
+		: FAILURE_EXIT_CODE
+}
+
+// The writes alone, for evidence composed in process — `backlog:drive`'s measured close
+// (`backlog-measure-close.ts`), which holds no tree of the issue's, so there is nothing to release.
+const issue_evidence_exit = { run, write: write_exit }
+
+export type { EvidenceExit, EvidenceRequest }
+export { issue_evidence_exit }

package/scripts/issue/issue-file-cap.ts

@@ -0,0 +1,58 @@
+import { run_hold_member } from '#scripts/run/hold/run-hold-member'
+import { issue_file_fold } from './issue-file-fold'
+import { session_cite } from './session-cite'
+
+// The automatic-filing cap, asked by `josh issue:file` itself as the fold and the WIP cap are.
+//
+// **Ten filings per originating work item, refused at the eleventh** (joshuafolkken/kit#4750). The
+// origin is the fold's finder — the `--found-during` the filing names, else the lane child's mark, else
+// the Issue the checkout's branch names — so a lane's filings, a long lane the parent investigated and
+// the Issue a prerequisite came out of are each their own count. The count is the origin's `filed`
+// events on the repository's event stream, read whole, so it outlives a session cut; a transcript tail
+// counted every origin a long session touched against one ceiling and forgot each filing once it
+// scrolled out (joshuafolkken/kit#2119).
+//
+// **Only a run's filings are automatic**: the cap holds in a run's session — a lane child or the
+// hold's owner — and counts the filings marked as a run's, so a person filing from their own session
+// is the further Issue the refusal leaves to them. **A filing with no origin counts against the
+// invocation running** — the carry record's scope the fold reads for it too — so a retrospective's or a
+// parent's own filings share one count per run. **A failed filing never counts**: `issue:file` appends
+// its `filed` event only once the Issue exists.
+
+const FILING_CAP = 10
+
+// How many Issues the origin has already filed from a run.
+async function prior_count(origin: string | undefined): Promise<number> {
+	const events = await issue_file_fold.events_of(origin)
+
+	return issue_file_fold.finder_filings(events, origin).filter((filed) => filed.is_run === true)
+		.length
+}
+
+function owner_of(origin: string | undefined): string {
+	return origin === undefined ? 'this run (no originating Issue)' : session_cite.issue(origin)
+}
+
+function reason_of(origin: string | undefined): string {
+	return (
+		`✖ filing cap: ${owner_of(origin)} has already filed ${String(FILING_CAP)} Issues, the ceiling ` +
+		"per originating work item. Stop filing and report; a further Issue is a person's to file from " +
+		'their own session (`.claude/skills/workflow-commands/prerequisite.md`).'
+	)
+}
+
+// Whether the filing may go on: `false`, with the reason printed, once a run's filing finds its
+// origin's count at the cap — this filing would be the eleventh.
+async function is_cap_clear(named: string | undefined): Promise<boolean> {
+	if (!(await run_hold_member.is_run_member())) return true
+	const origin = await issue_file_fold.finder(named)
+
+	if ((await prior_count(origin)) < FILING_CAP) return true
+	console.error(reason_of(origin))
+
+	return false
+}
+
+const issue_file_cap = { FILING_CAP, is_cap_clear, reason_of }
+
+export { issue_file_cap }

package/scripts/issue/issue-file-cli.ts

@@ -8,40 +8,56 @@ import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { git_gh_issue_list, MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { error_text } from '#scripts/lib/error-message'
 import type { PollOptions } from '#scripts/lib/poll'
 import { repository_labels } from '#scripts/repo/repository-labels'
 import { run_event_filed } from '#scripts/run/event/run-event-filed'
 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_hold_member } from '#scripts/run/hold/run-hold-member'
+import { split_resolution } from '#scripts/split/split-resolution'
 import { issue_auto_ok } from './issue-auto-ok'
 import { issue_cite } from './issue-cite'
 import { issue_file, type FileArguments } from './issue-file'
+import { issue_file_cap } from './issue-file-cap'
+import { issue_file_deferral } from './issue-file-deferral'
 import { issue_file_fold } from './issue-file-fold'
+import { issue_file_interrupt } from './issue-file-interrupt'
+import { issue_file_lane_hint } from './issue-file-lane-hint'
 import { issue_lint_cli } from './issue-lint-cli'
+import { issue_priority } from './issue-priority'
 import { issue_release_cli } from './issue-release-cli'
+import { issue_sample_required } from './issue-sample-required'
+import { issue_sample_source } from './issue-sample-source'
 import { issue_scout_cli } from './issue-scout-cli'
 import { issue_wip } from './issue-wip'
-
-// `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
-// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]` — file an Issue
-// with every filing step run in order: the third-party refusal, the body
-// lint, the `## Origin` check for another repository, the `auto-ok` decision
-// with the run label it owes, the fold question against the run's earlier
-// filings, the WIP cap count, the
-// duplicate scout, the missing workflow labels created, the create call
-// carrying every label, the release link on `--release`, and `epic:bundle`.
+import { size_estimate } from './size-estimate'
+
+// `josh issue:file "<title>" --body-file <path> [--route <route>] [--label <name>]…
+// [--repo <owner/repo>] [--distinct <N,…>] [--found-during <N>] [--over-cap] [--no-auto-ok]
+// [--release] [--blocks-finder]` — file an Issue with every filing step run: the third-party refusal,
+// the filing cap per origin and the fold question against the run's earlier filings, each ending the
+// filing on its own; then, each tier printing every refusal of its own at once, the local checks —
+// the body lint, the size estimate against the split guide, the start condition a measurement
+// follow-up owes, the `## Origin` check for another repository, the `auto-ok` decision with the run
+// label it owes; once those pass, the start condition read as a pull request and the WIP cap count;
+// once those pass, the duplicate scout; then the missing workflow labels created, the create call
+// carrying every label, a blocking interrupt's finder recorded as blocked by it, the release link on
+// `--release`, and `epic:bundle`.
 // A direct `gh api …/issues` filing is refused by the `direct-filing` delivered rule and pointed here.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE =
-	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]'
+	'Usage: josh issue:file "<title>" --body-file <path> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--found-during <N>] [--over-cap] [--no-auto-ok] [--release] [--blocks-finder]'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote`, so the filing has no repository to compare against — check `gh auth status`.'
 const THIRD_PARTY_MESSAGE =
 	'✖ third-party target: a tracker we do not own is Tier C — draft the Issue for a person to post instead (`CLAUDE.md` → "Third-party repositories are Tier C").'
+const UNKNOWN_PARTY_MESSAGE =
+	'✖ unknown party: the owner of this session or of the target could not be read (`git remote` / `--repo`), so the target is not known to be ours — check `pnpm josh repo:party`.'
 // `GH_REPO` is the variable `gh` reads `{owner}/{repo}` from, so setting it points every listing the
 // scout and `epic:bundle` make at the target repository rather than at this checkout.
 const GH_REPO_VARIABLE = 'GH_REPO'
@@ -64,19 +80,24 @@ async function read_body(path: string): Promise<string | undefined> {
 	}
 }
 
-function is_third_party(target: string): boolean {
+// An owner that cannot be read is refused like a third party — stricter than the `third-party-write`
+// hook, which stays silent on `unknown`: a filing is admitted only when the target is known to be ours.
+function party_refusal(target: string): string | undefined {
 	const party = repo_party.classify(repo_party.current_owner(), repo_party.target_owner(target))
 
-	return party === repo_party.THIRD_PARTY
+	if (party === repo_party.FIRST_PARTY) return undefined
+
+	return party === repo_party.THIRD_PARTY ? THIRD_PARTY_MESSAGE : UNKNOWN_PARTY_MESSAGE
 }
 
-// Every refusal the filing can meet before a request is sent, in the order the steps run — `[]` when
-// the filing may go on to the scout.
+// Every refusal the body and the arguments carry, read locally — `[]` when the body is admitted.
 function refusals_of(filing: Filing): ReadonlyArray<string> {
-	if (is_third_party(filing.target)) return [THIRD_PARTY_MESSAGE]
 	const problems = [
 		...issue_lint_cli.problems(filing.body),
+		size_estimate.guide_problem(filing.body, filing.args.route),
+		issue_sample_required.problem(filing.body),
 		issue_auto_ok.declaration_problem(filing.body),
+		issue_priority.problem(filing.body, filing.args.labels),
 		issue_file.origin_problem(filing.body, filing.target, filing.current),
 	]
 
@@ -138,7 +159,8 @@ async function is_scout_clear(filing: Filing): Promise<boolean> {
 
 	if (outcome === undefined) return false
 	console.info(outcome.report)
-	const open = issue_file.unacknowledged(outcome.candidates, filing.args.distinct)
+	const answered = issue_file.acknowledged(filing.args, filing.target, filing.current)
+	const open = issue_file.unacknowledged(outcome.candidates, answered)
 
 	if (open.length > 0) console.error(unacknowledged_message(open))
 
@@ -146,8 +168,8 @@ async function is_scout_clear(filing: Filing): Promise<boolean> {
 }
 
 // Every label the create call carries, or `undefined` when an `auto-ok` filing names neither run label.
-// Decided before the WIP count and the scout, so a refusal costs no listing. The decision reads the
-// labels the body's declarations add, so a declared breaking change is excluded like its label.
+// The decision reads the labels the body's declarations add, so a declared breaking change is excluded
+// like its label.
 function labels_of(filing: Filing): ReadonlyArray<string> | undefined {
 	const auto_ok = issue_auto_ok.decide({
 		is_opted_out: filing.args.is_auto_ok_opted_out,
@@ -223,26 +245,70 @@ async function place(url: string, target: string): Promise<void> {
 }
 
 // Every filing lands on the run's event stream: this is the one filing path, so
-// one append here reaches `run:board` from every route. A filing outside a run lands too and is left
-// out by the board's own scope to the invocation; the append is best-effort, as every emit is.
+// one append here reaches `run:board` from every route. A filing outside a run lands too, unmarked as
+// the run's (`run_hold_member`), and the board counts only the marked ones; a lane's overrun
+// investigation marks its own, which the board draws after 🔍; the append is best-effort, as every emit is.
+async function emit_filed(
+	reference: string,
+	filing: Filing,
+	labels: ReadonlyArray<string>,
+	found_during: string | undefined,
+): Promise<void> {
+	const kind = run_event_filed.kind_of(labels)
+	const is_run = await run_hold_member.is_run_member()
+	const is_overrun = lane_child_marker.is_overrun()
+	const { title } = filing.args
+	const text = run_event_filed.text_of({ reference, kind, title, found_during, is_run, is_overrun })
+
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.FILED, text)
+}
+
 async function record(url: string, filing: Filing, labels: ReadonlyArray<string>): Promise<void> {
 	const number = String(issue_number_of(url))
 	const reference = issue_cite.plain(
 		number,
 		issue_file_fold.reference_prefix(filing.target, filing.current),
 	)
-	const found_during = await issue_file_fold.finder()
-	const kind = run_event_filed.kind_of(labels)
-	const text = run_event_filed.text_of({ reference, kind, title: filing.args.title, found_during })
+	const found_during = await issue_file_fold.finder(filing.args.found_during)
 
-	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.FILED, text)
+	await emit_filed(reference, filing, labels, found_during)
+	await issue_file_deferral.note_finder({
+		found_during: filing.args.found_during,
+		reference,
+		title: filing.args.title,
+		current: filing.current,
+	})
+	await split_resolution.record_child({ route: filing.args.route, found_during, child: reference })
+	await issue_file_interrupt.block_finder({
+		route: filing.args.route,
+		is_blocking_finder: filing.args.is_blocking_finder,
+		found_during,
+		blocker: issue_number_of(url),
+		is_here: issue_file.is_same_repository(filing.target, filing.current),
+	})
 }
 
-function is_admitted(filing: Filing): boolean {
+async function is_admitted(filing: Filing): Promise<boolean> {
 	const refusals = refusals_of(filing)
 
 	if (refusals.length === 0) return true
-	console.error(refusals.join('\n'))
+	const hint = await issue_file_lane_hint.lines_of(filing.args.found_during, filing.body)
+
+	console.error([...refusals, ...hint].join('\n'))
+
+	return false
+}
+
+// The start condition's citation read against GitHub.
+async function is_source_clear(filing: Filing): Promise<boolean> {
+	const is_here = issue_file.is_same_repository(filing.target, filing.current)
+	const problem = await issue_sample_source.problem(
+		filing.body,
+		is_here ? undefined : filing.target,
+	)
+
+	if (problem === undefined) return true
+	console.error(`✖ ${problem}`)
 
 	return false
 }
@@ -259,23 +325,46 @@ async function send(filing: Filing, labels: ReadonlyArray<string>): Promise<numb
 	return SUCCESS_EXIT_CODE
 }
 
-// The holds that read the run and the backlog, in the order they cost: the fold reads the local event
-// stream and diff, the WIP count one listing, the scout a search.
-async function is_clear(filing: Filing): Promise<boolean> {
+// The holds that end the filing whatever the body says, read first: the filing cap reads the local
+// event stream, the fold the stream and diff.
+async function is_run_clear(filing: Filing): Promise<boolean> {
 	const prefix = issue_file_fold.reference_prefix(filing.target, filing.current)
 
-	if (!(await issue_file_fold.is_fold_clear(prefix, filing.args))) return false
+	return (
+		(await issue_file_cap.is_cap_clear(filing.args.found_during)) &&
+		(await issue_file_fold.is_fold_clear(prefix, filing.args))
+	)
+}
+
+// Every step the caller answers from the body and the arguments, cheapest first, each tier's refusals
+// printed at once and fixed in one reissue: the local checks (the body's own refusals and the run
+// label) before anything asks GitHub, then the start condition's citation and the WIP count, then the
+// duplicate scout's search, run only once nothing else refuses. The labels, or `undefined` when any refused.
+async function labels_in_one_pass(filing: Filing): Promise<ReadonlyArray<string> | undefined> {
+	const is_body_clear = await is_admitted(filing)
+	const labels = labels_of(filing)
+
+	if (!is_body_clear || labels === undefined) return undefined
+	const verdicts = [await is_source_clear(filing), await is_wip_clear(filing)]
+
+	if (!verdicts.every(Boolean)) return undefined
 
-	return (await is_wip_clear(filing)) && (await is_scout_clear(filing))
+	return (await is_scout_clear(filing)) ? labels : undefined
 }
 
 async function file(filing: Filing): Promise<number> {
-	if (!is_admitted(filing)) return FAILURE_EXIT_CODE
-	const labels = labels_of(filing)
+	const party_problem = party_refusal(filing.target)
+
+	if (party_problem !== undefined) {
+		console.error(party_problem)
 
-	if (labels === undefined || !(await is_clear(filing))) return FAILURE_EXIT_CODE
+		return FAILURE_EXIT_CODE
+	}
 
-	return await send(filing, labels)
+	if (!(await is_run_clear(filing))) return FAILURE_EXIT_CODE
+	const labels = await labels_in_one_pass(filing)
+
+	return labels === undefined ? FAILURE_EXIT_CODE : await send(filing, labels)
 }
 
 async function filing_of(args: FileArguments): Promise<Filing | string> {
@@ -314,7 +403,13 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const issue_file_cli = { FRESH_ISSUE_POLL, THIRD_PARTY_MESSAGE, record, run }
+const issue_file_cli = {
+	FRESH_ISSUE_POLL,
+	THIRD_PARTY_MESSAGE,
+	UNKNOWN_PARTY_MESSAGE,
+	record,
+	run,
+}
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/issue/issue-file-deferral.ts

@@ -0,0 +1,52 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { shell_quote } from '#scripts/lib/shell-quote'
+import { session_cite } from './session-cite'
+
+// What `josh issue:file --found-during <N>` leaves on #N: one comment, `NOTE_PREFIX <filed> <title>`, so
+// the deferral is read wherever #N is read. The run event alone reached neither `issue:read <N>` nor the
+// ship reviewer's brief, so the reviewer raised the deferred gap again as a Medium and the ship
+// stopped on scope the lane had already filed away (joshuafolkken/kit#4821). `review-rubric.md` →
+// "Stop conditions" is the rule that reads the note.
+//
+// Only a finder the filing names is noted — a finder inferred from the lane mark or the branch is the
+// run's, not a declared deferral. The finder is an Issue in this repository, so the comment is posted
+// to `current` even when `GH_REPO` points the filing's listings at another target. The Issue already
+// exists, so a failed comment is reported rather than failed, for the reason `issue-file-cli.ts` →
+// `place` gives.
+
+const NOTE_PREFIX = '先送り:'
+
+interface Deferral {
+	found_during: string | undefined
+	reference: string
+	title: string
+	current: string
+}
+
+function note_of(deferral: Deferral): string {
+	return `${NOTE_PREFIX} ${deferral.reference} ${deferral.title}`
+}
+
+function failure_line(finder: number, note: string): string {
+	const rerun = `pnpm josh issue:comment ${String(finder)} --body ${shell_quote.single_quoted(note)}`
+
+	return `⚠ the deferral note did not reach ${session_cite.issue(finder)} — run \`${rerun}\`.`
+}
+
+async function note_finder(deferral: Deferral): Promise<void> {
+	const finder = Number(deferral.found_during)
+
+	if (!Number.isSafeInteger(finder) || finder <= 0) return
+	const note = note_of(deferral)
+	const is_noted = await git_gh_issue_write.issue_try_comment(
+		String(finder),
+		note,
+		deferral.current,
+	)
+
+	if (!is_noted) console.error(failure_line(finder, note))
+}
+
+const issue_file_deferral = { NOTE_PREFIX, note_finder }
+
+export { issue_file_deferral }

package/scripts/issue/issue-file-fold.ts

@@ -28,6 +28,7 @@ const CLOSED_STATE = 'CLOSED'
 interface FoldArguments {
 	route: string | undefined
 	distinct: ReadonlyArray<number>
+	found_during: string | undefined
 }
 
 function number_of(reference: string): number {
@@ -55,10 +56,12 @@ async function branch_issue(): Promise<number | undefined> {
 	}
 }
 
-// Whose work turned the finding up: the lane child's mark, else the Issue the checkout's branch names,
-// so a person's `fullrun` on `3423-x` is one finder across its filings just as a lane child is. A
-// checkout on no Issue's branch — a `backlogrun` parent on `main` — has none.
-async function finder(): Promise<string | undefined> {
+// Whose work turned the finding up: the `--found-during` the filing named, else the lane child's mark,
+// else the Issue the checkout's branch names, so a person's `fullrun` on `3423-x` is one finder across
+// its filings just as a lane child is. A checkout on no Issue's branch — a `backlogrun` parent on
+// `main` — has none unless the filing names one.
+async function finder(named?: string): Promise<string | undefined> {
+	if (named !== undefined) return named
 	const marked = lane_child_marker.marked_issue()
 
 	if (marked !== undefined) return marked
@@ -76,6 +79,17 @@ async function events_of(found_during: string | undefined): Promise<ReadonlyArra
 	return await run_event_stream_emit.all_events()
 }
 
+// The finder's filings on the events, in every repository.
+function finder_filings(
+	events: ReadonlyArray<RunEvent>,
+	found_during: string | undefined,
+): ReadonlyArray<Filed> {
+	return events
+		.filter((event) => event.kind === run_event_stream.EVENT_KIND.FILED)
+		.flatMap((event) => run_event_filed.parse(event.text) ?? [])
+		.filter((filed) => filed.found_during === found_during)
+}
+
 // This run's earlier filings by the same finder — so a parallel lane's filing is never what this one
 // folds into — in the repository this filing targets. One the caller named in `--distinct` has been
 // declared a separate deliverable and is left out, the same declaration the scout's candidates take.
@@ -85,10 +99,8 @@ function prior_filings(
 	prefix: string,
 	distinct: ReadonlyArray<number>,
 ): ReadonlyArray<Filed> {
-	return events
-		.filter((event) => event.kind === run_event_stream.EVENT_KIND.FILED)
-		.flatMap((event) => run_event_filed.parse(event.text) ?? [])
-		.filter((filed) => filed.found_during === found_during && prefix_of(filed.reference) === prefix)
+	return finder_filings(events, found_during)
+		.filter((filed) => prefix_of(filed.reference) === prefix)
 		.filter((filed) => !distinct.includes(number_of(filed.reference)))
 }
 
@@ -136,7 +148,7 @@ function held_message(priors: ReadonlyArray<Filed>): string {
 // exempt, as it is from the WIP cap: the split assessment already decided it is a separate deliverable.
 async function is_fold_clear(prefix: string, args: FoldArguments): Promise<boolean> {
 	if (args.route === SPLIT_ROUTE_LABEL) return true
-	const found_during = await finder()
+	const found_during = await finder(args.found_during)
 	const filings = prior_filings(await events_of(found_during), found_during, prefix, args.distinct)
 	const priors = await open_filings(filings, prefix)
 
@@ -150,6 +162,13 @@ async function is_fold_clear(prefix: string, args: FoldArguments): Promise<boole
 	return verdict !== issue_fold.FOLD
 }
 
-const issue_file_fold = { finder, is_fold_clear, prior_filings, reference_prefix }
+const issue_file_fold = {
+	events_of,
+	finder,
+	finder_filings,
+	is_fold_clear,
+	prior_filings,
+	reference_prefix,
+}
 
 export { issue_file_fold }

package/scripts/issue/issue-file-interrupt.ts

@@ -0,0 +1,85 @@
+import { epic_relations } from '#scripts/epic/epic-relations'
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { INTERRUPT_ROUTE_LABEL } from './issue-labels'
+import { session_cite } from './session-cite'
+
+// What `josh issue:file` just filed on `--route interrupt --blocks-finder`: the Issue whose work turned
+// the defect up is recorded as blocked by it, in the same command as the filing — so a session that
+// dies after the filing still leaves the dispatch a relation that keeps the finder back until the
+// interrupt lands (`upstream-interrupt.md` → the run-machinery case). An interrupt that blocks nobody
+// (`wip-cap.md` → the three conditions) omits the flag, since a relation there is a false dependency.
+// Written through the relation path epic creation and `epic --add` use, and only for a filing in this
+// repository: the relation write resolves both numbers here.
+//
+// The Issue already exists, so a failed write is reported rather than failed, for the reason
+// `issue-file-cli.ts` → `place` gives.
+
+interface InterruptFiling {
+	route: string | undefined
+	is_blocking_finder: boolean
+	found_during: string | undefined
+	blocker: number
+	is_here: boolean
+}
+
+function is_issue_number(value: number): boolean {
+	return Number.isSafeInteger(value) && value > 0
+}
+
+function finder_of(filing: InterruptFiling): number | undefined {
+	if (filing.route !== INTERRUPT_ROUTE_LABEL || !filing.is_here) return undefined
+	const finder = Number(filing.found_during)
+
+	return is_issue_number(finder) ? finder : undefined
+}
+
+// An explicit `--blocks-finder` that records nothing is said, so the caller does not read the
+// silence as a recorded relation and leave the finder dispatchable.
+function ignored_line(filing: InterruptFiling): string {
+	const reason =
+		filing.route === INTERRUPT_ROUTE_LABEL
+			? 'no finder and filed Issue pair in this repository was read'
+			: 'it applies to `--route interrupt` only'
+
+	return `⚠ --blocks-finder recorded nothing: ${reason}.`
+}
+
+// The re-run writes the one relation and nothing else — no epic placement and no chain splice, which
+// would record dependencies the interrupt does not have.
+function failure_line(blocked: number, blocker: number): string {
+	const path = git_gh_api_path.blocked_by_api_path(String(blocked))
+	const id = `$(gh api ${git_gh_api_path.issue_api_path(String(blocker))} --jq .id)`
+	const cited = `${session_cite.issue(blocked)} could not be recorded as blocked by ${session_cite.issue(blocker)}`
+
+	return `⚠ ${cited} — run \`gh api ${path} -F issue_id=${id}\`.`
+}
+
+async function record(blocked: number, blocker: number): Promise<void> {
+	const links = [{ blocked, blocker }]
+	const failures = await epic_relations.apply_relations(links, 'record')
+
+	if (failures === 0) {
+		console.info(epic_relations.format_relation_report({ links, failures, action: 'record' }))
+
+		return
+	}
+
+	console.error(failure_line(blocked, blocker))
+}
+
+async function block_finder(filing: InterruptFiling): Promise<void> {
+	if (!filing.is_blocking_finder) return
+	const blocked = finder_of(filing)
+
+	if (blocked === undefined || !is_issue_number(filing.blocker)) {
+		console.warn(ignored_line(filing))
+
+		return
+	}
+
+	await record(blocked, filing.blocker)
+}
+
+const issue_file_interrupt = { block_finder }
+
+export { issue_file_interrupt }