@joshuafolkken/kit 1.1514.0 → 1.1784.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.ts

@@ -323,11 +323,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-handoff.ts

@@ -126,10 +126,10 @@ function describe_handoff(handoff: Handoff): string {
 	].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 run_cut_handoff = {
 	HANDOFF_FORMAT,

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

@@ -39,10 +39,6 @@ const TEXT_INDEX = 2
 const USAGE =
 	'Usage: josh run:event --append <kind> <text> | --from <position> | --follow <position> | --watch [<position>] | --last'
 
-function now_iso(): string {
-	return new Date().toISOString()
-}
-
 function report_usage(): number {
 	process.stderr.write(`${USAGE}\n`)
 
@@ -54,7 +50,7 @@ async function run_append(kind: string, text: string): Promise<number> {
 
 	if (target === undefined) return report_usage()
 
-	const result = run_event_stream.append(target, kind, text, now_iso())
+	const result = await run_event_stream_emit.append_at(target, kind, text, new Date())
 
 	if (!result.appended) {
 		process.stderr.write(`not a session-facing event kind: ${kind}\n`)

package/scripts/run/event/run-event-filed.ts

@@ -6,9 +6,9 @@ import {
 	has_label_name,
 } from '#scripts/issue/issue-labels'
 
-// The text of a `filed` event: the Issue a run filed, its kind, its title, and the child whose work
-// turned it up. `issue:file` writes it and `run:board` reads it back, both through this module, so the
-// two never spell it differently.
+// The text of a `filed` event: the Issue a run filed, its kind, its title, whether a run's own session
+// filed it, and the child whose work turned it up. `issue:file` writes it and `run:board` reads it
+// back, both through this module, so the two never spell it differently.
 
 // The classification labels a filing's kind is read from, in precedence order: a breaking change is
 // named as one whatever else it is.
@@ -25,13 +25,18 @@ interface Filed {
 	title: string
 	// The lane child that was working when the Issue was filed, when the filing came from one.
 	found_during: string | undefined
+	// A run's own session filed it — the parent holding the run's hold or a lane child — rather than one
+	// outside the run sharing the repository's stream (joshuafolkken/kit#4099). An event written before
+	// the mark was recorded reads as filed outside.
+	is_run?: boolean | undefined
 }
 
 // The kind slot is always written, `[<label>]` or `[]`, against the reference with no space: an event
 // written before the kind always has the space there, so no title, whatever it opens with, reads as a
-// kind.
+// kind. The run's mark follows the kind slot, again with no space.
+const RUN_MARK = '[run]'
 const TEXT_PATTERN = new RegExp(
-	String.raw`^(?<reference>\S*#\d+)(?:\[(?<kind>${KINDS.join('|')}|)\])? (?<title>.*?)(?: \(found during #(?<during>\d+)\))?$`,
+	String.raw`^(?<reference>\S*#\d+)(?:\[(?<kind>${KINDS.join('|')}|)\](?<run>\[run\])?)? (?<title>.*?)(?: \(found during #(?<during>\d+)\))?$`,
 	'u',
 )
 
@@ -41,7 +46,7 @@ function kind_of(labels: ReadonlyArray<string>): FiledKind | undefined {
 }
 
 function text_of(filed: Filed): string {
-	const kind = `[${filed.kind ?? ''}]`
+	const kind = `[${filed.kind ?? ''}]${filed.is_run === true ? RUN_MARK : ''}`
 	const suffix =
 		filed.found_during === undefined
 			? ''
@@ -60,6 +65,7 @@ function parse(text: string): Filed | undefined {
 		kind: KINDS.find((kind) => kind === groups['kind']),
 		title: String(groups['title']),
 		found_during: groups['during'],
+		is_run: groups['run'] !== undefined,
 	}
 }
 

package/scripts/run/event/run-event-follow.ts

@@ -1,3 +1,4 @@
+import { MS_PER_MINUTE, MS_PER_SECOND } from '#scripts/lib/timeouts'
 import type { StreamRead } from './run-event-stream'
 
 // The follow read behind `josh run:event --follow` and `--watch`. A reader
@@ -24,10 +25,8 @@ import type { StreamRead } from './run-event-stream'
 // The follow's quiet-tick cadence and how promptly it notices an arrival. The interval only bounds a
 // wait that found nothing — an arrival returns within a tick of landing — so it can be as long as the
 // heartbeat without making an arrival late, and the tick is a cheap `stat` of one file.
-const MS_PER_SECOND = 1000
-const SECONDS_PER_MINUTE = 60
 const FOLLOW_INTERVAL_MINUTES = 20
-const FOLLOW_INTERVAL_MS = FOLLOW_INTERVAL_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND
+const FOLLOW_INTERVAL_MS = FOLLOW_INTERVAL_MINUTES * MS_PER_MINUTE
 const FOLLOW_TICK_MS = MS_PER_SECOND
 
 interface FollowPorts {

package/scripts/run/event/run-event-render.ts

@@ -1,3 +1,4 @@
+import { figure_format } from '#scripts/lib/figure-format'
 import type { EventKind, RunEvent } from './run-event-stream'
 
 // One run event as the line a person reads in the watch pane. The pane is a script, not a session, so
@@ -10,8 +11,6 @@ import type { EventKind, RunEvent } from './run-event-stream'
 
 const JA = 'ja'
 const FIELD_SEPARATOR = ' · '
-const CLOCK_WIDTH = 2
-const CLOCK_PAD = '0'
 
 interface KindLabel {
 	ja: string
@@ -48,6 +47,9 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	'lane-limit': { ja: 'レーン上限', en: 'lane limit' },
 	setup: { ja: '準備', en: 'setup' },
 	'pr-checks': { ja: 'PR のチェック', en: 'PR checks' },
+	'idle-notice': { ja: '待機の通知', en: 'idle notice' },
+	'lane-state': { ja: 'レーンの状態', en: 'lane state' },
+	'paused-notice': { ja: '一時停止の通知', en: 'paused notice' },
 }
 
 const LABELS_BY_KIND: ReadonlyMap<string, KindLabel> = new Map(Object.entries(KIND_LABELS))
@@ -60,18 +62,12 @@ function label_of(kind: string, lang: string): string {
 	return lang === JA ? label.ja : label.en
 }
 
-function two_digits(value: number): string {
-	return String(value).padStart(CLOCK_WIDTH, CLOCK_PAD)
-}
-
 // The local wall-clock `HH:MM` of the event, the reading a person watching a pane compares with the clock
 // on their screen; an unparseable stamp is shown as written rather than as `NaN:NaN`.
 function clock_of(at: string): string {
-	const date = new Date(at)
-
-	if (Number.isNaN(date.getTime())) return at
+	const ms = new Date(at).getTime()
 
-	return `${two_digits(date.getHours())}:${two_digits(date.getMinutes())}`
+	return Number.isNaN(ms) ? at : figure_format.minute_of(ms)
 }
 
 function render(event: RunEvent, lang: string): string {

package/scripts/run/event/run-event-scope.ts

@@ -114,7 +114,7 @@ function is_own_ship_event(event: RunEvent, issue: string): boolean {
 }
 
 // The issue an event's text names, the way every reader here — and `run:board` — keys an event to a child.
-function issue_named(event: RunEvent): string | undefined {
+function issue_named(event: Pick<RunEvent, 'text'>): string | undefined {
 	return ISSUE_REFERENCE.exec(event.text)?.[1]
 }
 
@@ -169,7 +169,7 @@ function last_issue_event(
 
 // A child's launch and the endings `run:merge` settles it with — the ones `run:board` stops drawing it
 // running on. A park or a split already ran `run:merge`, so a child closed after one owes nothing; a
-// withdrawal settles the child itself, its issue closed by the person who withdrew it.
+// withdrawal settles the child itself, its issue left open for the next run.
 const LAUNCH_OR_SETTLE_KINDS: ReadonlySet<string> = new Set([
 	KIND.CHILD_LAUNCH,
 	KIND.MERGE,

package/scripts/run/event/run-event-stream-emit.ts

@@ -1,7 +1,9 @@
+import { lane_state, type LaneStateRecord } from '#scripts/lane/lane-state'
 import { error_text } from '#scripts/lib/error-message'
+import { run_board_lane_time } from '#scripts/run/board/run-board-lane-time'
 import { run_carry } from '#scripts/run/carry/run-carry'
 import { run_event_scope } from './run-event-scope'
-import { run_event_stream, type RunEvent } from './run-event-stream'
+import { run_event_stream, type AppendResult, type RunEvent } from './run-event-stream'
 
 // The write side of the run's event stream. It resolves the run's identity and
 // appends, and it is where the "reporting must not break the work it reports on" contract is kept: every
@@ -27,17 +29,66 @@ async function stream_target(): Promise<string | undefined> {
 	return repository === undefined ? undefined : run_event_stream.target_of(repository)
 }
 
+// The child's lane record; an unreadable one reads as none, so the ending is still written.
+async function lane_record(issue: string): Promise<LaneStateRecord | undefined> {
+	try {
+		return await lane_state.read_state(issue)
+	} catch (error) {
+		error_text.trace_swallowed('run_event_stream_emit.lane_record', error)
+
+		return undefined
+	}
+}
+
+async function ending_fields(
+	target: string,
+	event: Omit<RunEvent, 'pos'>,
+): Promise<Pick<RunEvent, 'elapsed_ms'>> {
+	const issue = run_event_scope.issue_named(event)
+
+	if (issue === undefined || !run_board_lane_time.OFF_LANE_KINDS.has(event.kind)) return {}
+
+	const elapsed_ms = run_board_lane_time.ending_elapsed({
+		events: run_event_stream.read_events(target),
+		issue: Number(issue),
+		record: await lane_record(issue),
+		ended_ms: Date.parse(event.at),
+	})
+
+	return elapsed_ms === undefined ? {} : { elapsed_ms }
+}
+
+/**
+ * Append one event at `at`, an ending with its child's lane time (joshuafolkken/kit#4481). Every writer
+ * of an ending — `emit` and `run:event --append` — appends through here, so the time is computed once,
+ * as the ending is written, with the board's own count.
+ */
+async function append_at(
+	target: string,
+	kind: string,
+	text: string,
+	at: Date,
+): Promise<AppendResult> {
+	const event = { kind, text, at: at.toISOString() }
+
+	return run_event_stream.append_event(target, {
+		...event,
+		...(await ending_fields(target, event)),
+	})
+}
+
 /**
  * Append one session-facing event, best-effort. A kind outside the enumeration is refused by `append`;
  * every error is swallowed, because the reporting path must never fail the work it reports on.
+ * `at` is the caller's instant where another record must carry the same one.
  */
-async function emit(kind: string, text: string): Promise<void> {
+async function emit(kind: string, text: string, at: Date = new Date()): Promise<void> {
 	try {
 		const target = await stream_target()
 
 		if (target === undefined) return
 
-		run_event_stream.append(target, kind, text, now_iso())
+		await append_at(target, kind, text, at)
 	} catch {
 		// Reporting is best-effort: a failed append is dropped rather than raised into the caller's work.
 	}
@@ -85,37 +136,52 @@ function invocation_events(repository: string, target: string): ReadonlyArray<Ru
  * Append one event unless this kind is already on the stream since the newest `reset_kind` — the
  * episode marker for a condition that holds across other events. `emit_once`'s newest-event test would
  * re-fire each time a parallel lane appended a merge or a park; this ends the episode only at
- * `reset_kind`. Returns whether it appended, as `emit_once` does.
+ * `reset_kind`. The text is composed only once the episode is new, so a caller polled every pass whose
+ * text costs a network read pays it once. Returns the appended text, or `undefined` when nothing was.
  */
-async function emit_once_since(kind: string, text: string, reset_kind: string): Promise<boolean> {
+async function emit_once_since_with(
+	kind: string,
+	reset_kind: string,
+	compose: () => Promise<string>,
+): Promise<string | undefined> {
 	try {
 		const repository = await run_carry.repository_directory()
 
-		if (repository === undefined) return false
+		if (repository === undefined) return undefined
 
 		const target = run_event_stream.target_of(repository)
 
 		if (run_event_stream.has_since(invocation_events(repository, target), kind, reset_kind)) {
-			return false
+			return undefined
 		}
 
-		return run_event_stream.append(target, kind, text, now_iso()).appended
+		const text = await compose()
+
+		return run_event_stream.append(target, kind, text, now_iso()).appended ? text : undefined
 	} catch (error) {
 		// Best-effort: a failed append is dropped rather than raised into the caller's work.
 		error_text.trace_swallowed('run_event_stream_emit.emit_once_since', error)
 
-		return false
+		return undefined
 	}
 }
 
+// `emit_once_since_with` for a text already in hand. Returns whether it appended, as `emit_once` does.
+async function emit_once_since(kind: string, text: string, reset_kind: string): Promise<boolean> {
+	const appended = await emit_once_since_with(kind, reset_kind, async () => text)
+
+	return appended !== undefined
+}
+
 // One progress heartbeat line onto the stream, so a relay reaches it across a cut.
 async function emit_heartbeat(line: string): Promise<void> {
 	await emit(run_event_stream.EVENT_KIND.HEARTBEAT, line)
 }
 
-// The events of the invocation now running, `undefined` where the invocation's scope could not be told
-// — for a reader that must not take "no events" for "nothing launched" (`backlog-occupied.ts`).
-async function scoped_current_events(): Promise<ReadonlyArray<RunEvent> | undefined> {
+// The events of the invocation now running, for a reader restoring the run from its stream
+// (`backlog:drive`). Fail-quiet like the writers: no repository, an unreadable stream or an
+// undetermined scope is an empty invocation.
+async function current_events(): Promise<ReadonlyArray<RunEvent>> {
 	try {
 		const repository = await run_carry.repository_directory()
 
@@ -125,19 +191,12 @@ async function scoped_current_events(): Promise<ReadonlyArray<RunEvent> | undefi
 		const scope = run_event_scope.scope_of(read)
 		const events = run_event_stream.read_events(run_event_stream.target_of(repository))
 
-		return run_event_scope.scoped_events(events, scope)
+		return run_event_scope.scoped_events(events, scope) ?? []
 	} catch {
-		return undefined
+		return []
 	}
 }
 
-// The events of the invocation now running, for a reader restoring the run from its stream
-// (`backlog:drive`). Fail-quiet like the writers: no repository, an unreadable stream or an
-// undetermined scope is an empty invocation.
-async function current_events(): Promise<ReadonlyArray<RunEvent>> {
-	return (await scoped_current_events()) ?? []
-}
-
 // The invocation's events for a writer deciding whether a marker is already there: unlike
 // `current_events`, an undetermined scope keeps the whole stream, so a run with no carry record skips a
 // marker it already wrote rather than writing it twice.
@@ -167,13 +226,14 @@ async function all_events(): Promise<ReadonlyArray<RunEvent>> {
 
 const run_event_stream_emit = {
 	all_events,
+	append_at,
 	current_events,
 	emit,
 	emit_heartbeat,
 	emit_once,
 	emit_once_since,
+	emit_once_since_with,
 	invocation_or_all_events,
-	scoped_current_events,
 	stream_target,
 }
 

package/scripts/run/event/run-event-stream.ts

@@ -29,10 +29,11 @@ const EVENT_PREFIX = 'josh-run-events-'
 // every reader — a person, an editor — that it is a line stream rather than a single document, the same
 // distinction the ambient `.log` draws.
 const EVENT_SUFFIX = '.jsonl'
-// A run's session-facing events over one unattended night: a plan, a launch/PR/review-round/merge
-// per child across a few dozen children, plus parks, cuts and stops. Five hundred keeps the whole of a
-// large `backlogrun` and still bounds an unattended run — past it the oldest events roll off.
-const EVENT_CAP = 500
+// A week of a busy run's events, so `josh lane:stats --period 7` reads the parks that end a stop's wait
+// and `run:board` keeps every ship stage (joshuafolkken/kit#3997). A four-lane `backlogrun` wrote about
+// 75 events an hour (1,877 in 25 hours), so fifteen thousand holds about eight days at that rate and
+// still bounds the file to a few megabytes — past it the oldest events roll off.
+const EVENT_CAP = 15_000
 const FIRST_POSITION = 0
 const POSITION_INCREMENT = 1
 const LINE_SEPARATOR = '\n'
@@ -64,7 +65,7 @@ const EVENT_KIND = {
 	// (`lane:restart`). It follows the fresh dispatch's `CHILD_LAUNCH`, so it is a launch to the parent and
 	// the board, and — like that launch — a batch record a lane child never reads as its own position.
 	RESTART: 'restart',
-	// A person withdrew a lane child — stopped it and closed its issue as not planned (`lane:withdraw`).
+	// A person withdrew a lane child — stopped it and left its issue open for the next run (`lane:withdraw`).
 	// It is written before the stop, so `run:merge` settles the child as withdrawn whatever GitHub says
 	// by the time the parent collects it, and counts it as neither a merge, a failure nor an outage.
 	WITHDRAW: 'withdraw',
@@ -143,6 +144,19 @@ const EVENT_KIND = {
 	// in followup without asking GitHub (joshuafolkken/kit#3770). A trace: it says how the checks stand,
 	// not where the run is.
 	PR_CHECKS: 'pr-checks',
+	// `backlog:drive` reached a watch with no child running and nothing to dispatch — the point a person's
+	// hand is wanted. Emitted once per idle episode (`emit_once_since_with`, reset by `CHILD_LAUNCH`), it
+	// is the dedup marker for the one idle Telegram. A trace: a drain's retrospective is read off the
+	// position beneath it, so the marker must not stand over it.
+	IDLE_NOTICE: 'idle-notice',
+	// A person paused or resumed a lane child (`lane:pause` / `lane:resume`), so who halted a lane and
+	// when is on the stream rather than only in a shell history (joshuafolkken/kit#4268). A trace: it
+	// says what a lane's processes were told, not where the run is.
+	LANE_STATE: 'lane-state',
+	// `backlog:drive` found nothing of the run in flight and only paused lanes left, paused past the
+	// silent window (joshuafolkken/kit#4270). Emitted once per pause episode (`emit_once_since_with`,
+	// reset by `LANE_STATE`), it is the dedup marker for the one paused-lane Telegram. A trace.
+	PAUSED_NOTICE: 'paused-notice',
 } as const
 
 type EventKind = (typeof EVENT_KIND)[keyof typeof EVENT_KIND]
@@ -162,6 +176,9 @@ const TRACE_KINDS: ReadonlySet<string> = new Set([
 	EVENT_KIND.LANE_LIMIT,
 	EVENT_KIND.SETUP,
 	EVENT_KIND.PR_CHECKS,
+	EVENT_KIND.IDLE_NOTICE,
+	EVENT_KIND.LANE_STATE,
+	EVENT_KIND.PAUSED_NOTICE,
 ])
 
 // The trace kinds that say only that the run was alive, so the bound rolls them off first. A `filed` or
@@ -181,6 +198,9 @@ const event_schema = z.object({
 	at: z.string(),
 	kind: z.string(),
 	text: z.string(),
+	// The child's time on a lane, recorded once by the writer of an ending (joshuafolkken/kit#4481), so a
+	// reader never has to find its launch again. An event written before it has none.
+	elapsed_ms: z.number().optional(),
 })
 
 type RunEvent = z.infer<typeof event_schema>
@@ -346,12 +366,12 @@ function append_held(target: string, event: Omit<RunEvent, 'pos'>): number {
  * unlocked read-then-rewrite would lose one writer's event to another's. A lock still
  * held after the wait is reported on stderr and thrown, which the best-effort emit side swallows.
  */
-function append(target: string, kind: string, text: string, at: string): AppendResult {
-	if (!is_event_kind(kind)) return { appended: false, position: FIRST_POSITION }
+function append_event(target: string, event: Omit<RunEvent, 'pos'>): AppendResult {
+	if (!is_event_kind(event.kind)) return { appended: false, position: FIRST_POSITION }
 
 	const lock = `${target}${LOCK_SUFFIX}`
 	const position = repository_lock.with_lock_sync(
-		() => append_held(target, { at, kind, text }),
+		() => append_held(target, event),
 		lock,
 		LOCK_WAIT_MS,
 	)
@@ -366,6 +386,11 @@ function append(target: string, kind: string, text: string, at: string): AppendR
 	return { appended: true, position }
 }
 
+// `append_event` for an event that records nothing beyond its kind, text and instant.
+function append(target: string, kind: string, text: string, at: string): AppendResult {
+	return append_event(target, { at, kind, text })
+}
+
 /**
  * Every event after `position`, in order, and the position a reader passes back next time.
  *
@@ -415,6 +440,7 @@ const run_event_stream = {
 	EVENT_KINDS,
 	TRACE_KINDS,
 	append,
+	append_event,
 	format_event,
 	has_since,
 	is_stage_start,

package/scripts/run/hold/run-hold-adopt.ts

@@ -0,0 +1,65 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
+import { run_label } from '#scripts/run/run-label'
+import { run_hold } from './run-hold'
+
+// `josh run:hold --adopt <N>` — a `new` run's hand-over once its Issue is filed (joshuafolkken/kit#4156).
+// The unnumbered record is re-keyed in place to `<N>`, so every later stop of the run releases with
+// `run:release <N>` and that release takes `in-progress` back off; the adopt applies the label the
+// numbered entry would have. **In place, not released and re-claimed**: a release would free the tree
+// for a moment another session could claim it in, and the record's owner and stop marks stay as written.
+
+const ADOPTED = 'adopted'
+// The tree holds no record, so there is nothing to hand over.
+const NO_RECORD = 'none'
+const FOREIGN = 'foreign'
+const UNREADABLE = 'unreadable'
+
+type AdoptResult = typeof ADOPTED | typeof FOREIGN | typeof NO_RECORD | typeof UNREADABLE
+
+// The record re-keyed: the unnumbered run's own, or one already naming `<N>` — a repeated adopt is
+// the same hand-over, so it answers alike. Another issue's record is never touched.
+function rekey(target: string, issue: string): AdoptResult {
+	const read = run_hold.read_hold(target)
+
+	if (read.kind === 'unreadable') return UNREADABLE
+
+	const hold = run_halfrun_resume.hold_of(read)
+
+	if (hold === undefined) return NO_RECORD
+
+	if (hold.issue !== run_hold.UNNUMBERED_ISSUE && hold.issue !== issue) return FOREIGN
+
+	stamp_file.write_stamp(target, { ...hold, issue })
+
+	return ADOPTED
+}
+
+function no_record_message(issue: string): string {
+	return `run:hold --adopt: this tree holds no record to adopt — claim it with \`pnpm josh run:hold ${issue}\`.`
+}
+
+// Not the claim race's message: that one advises `--force`, which here would free another run's tree.
+function foreign_message(issue: string): string {
+	return `run:hold --adopt: this tree is held for another issue, so it is not handed to issue ${issue}; \`--adopt\` only re-keys a \`new\` run's unnumbered record.`
+}
+
+async function adopt(target: string, issue: string): Promise<AdoptResult> {
+	const result = rekey(target, issue)
+
+	if (result === ADOPTED) await run_label.mark(issue)
+
+	return result
+}
+
+const run_hold_adopt = {
+	ADOPTED,
+	NO_RECORD,
+	UNREADABLE,
+	adopt,
+	foreign_message,
+	no_record_message,
+}
+
+export type { AdoptResult }
+export { run_hold_adopt }