@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,4 +1,5 @@
 import { repository_lock } from '#scripts/git/repository-lock'
+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 { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
@@ -24,15 +25,16 @@ import { z } from 'zod'
 // must never fail the work it reports on, so `run-event-stream-emit.ts` wraps
 // every append in a swallow; this module is free to throw on a genuinely broken write.
 
-const EVENT_PREFIX = 'josh-run-events-'
+const EVENT_PREFIX = durable_state.PREFIX.EVENTS
 // `.jsonl` rather than `.json`: the file is one JSON event per line, appended to, and the suffix tells
 // 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'
@@ -55,6 +57,10 @@ const EVENT_KIND = {
 	PARK: 'park',
 	SPLIT: 'split',
 	OUTAGE: 'outage',
+	// A Claude usage limit stopped a lane child (joshuafolkken/kit#4745). Its text names the reset time,
+	// which `backlog:drive` reads to hold launches until then; it counts against no streak, so it is not an
+	// `OUTAGE`.
+	USAGE_LIMIT: 'usage-limit',
 	CUT: 'cut',
 	// A fresh session adopted an implementation cut — `run:cut --resume` answered `resume-impl`. The
 	// resume clears the cut record, so without this the `cut` would stay the newest position and
@@ -64,7 +70,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',
@@ -115,6 +121,11 @@ const EVENT_KIND = {
 	// The position that hands control back: `run:step` prints the command that
 	// shows the stopped report, so the agent fixes it and relaunches rather than rebuilding the context.
 	SHIP_STOP: 'ship-stop',
+	// The relaunch meant to answer a `SHIP_STOP` started nothing — the broker refused it, or the direct
+	// spawn failed (joshuafolkken/kit#4765). `run:merge` reads it, not the transcript's mtime, to tell the
+	// stop went unanswered, and a re-dispatch cap's park names its reason. A trace: the stop stays the
+	// position `run:step` answers.
+	RELAUNCH_FAILED: 'relaunch-failed',
 	// An Issue the run filed on its way, written by `issue:file`, so a run started from the command line
 	// still surfaces what it found — `run:board`'s findings section reads it.
 	FILED: 'filed',
@@ -143,6 +154,27 @@ 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',
+	// `backlog:drive` ran a due issue's measurement declaration itself, found it within its bound and
+	// closed the issue through `issue:measured` — no lane was launched for it (joshuafolkken/kit#4621).
+	// `run:board` draws it merged. A trace: the parent's position is the drive's, not this close.
+	MEASURED: 'measured',
+	// The host slept while `backlog:drive` sampled its load (joshuafolkken/kit#5032): the sampler's timer
+	// ran late by more than a few intervals. `at` is the wake and `elapsed_ms` how long the sleep
+	// lasted; every lane's net time takes it out (`lane-sleep.ts`). A trace.
+	SLEEP: 'sleep',
 } as const
 
 type EventKind = (typeof EVENT_KIND)[keyof typeof EVENT_KIND]
@@ -162,6 +194,12 @@ 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,
+	EVENT_KIND.MEASURED,
+	EVENT_KIND.RELAUNCH_FAILED,
+	EVENT_KIND.SLEEP,
 ])
 
 // The trace kinds that say only that the run was alive, so the bound rolls them off first. A `filed` or
@@ -181,6 +219,10 @@ 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. A `sleep` event
+	// carries the sleep's length here.
+	elapsed_ms: z.number().optional(),
 })
 
 type RunEvent = z.infer<typeof event_schema>
@@ -204,7 +246,7 @@ function is_event_kind(value: string): value is EventKind {
 // The stream's path, keyed on the run's identity the caller resolved. `.jsonl` so the append surface is
 // named for what it is.
 function target_of(repository: string): string {
-	return stamp_file.stamp_path(EVENT_PREFIX, repository, EVENT_SUFFIX)
+	return durable_state.path(EVENT_PREFIX, repository, EVENT_SUFFIX)
 }
 
 function is_present(event: RunEvent | undefined): event is RunEvent {
@@ -346,12 +388,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 +408,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 +462,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 }

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { run_cli_fault } from '#scripts/run/run-cli-fault'
 import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
@@ -7,7 +5,10 @@ import { run_label } from '#scripts/run/run-label'
 import { run_preflight, type PreflightDecision } from '#scripts/run/run-preflight'
 import { run_prrun_resume } from '#scripts/run/run-prrun-resume'
 import { run_tidy_cli } from '#scripts/run/tidy/run-tidy-cli'
+import { test_e2e_stamp } from '#scripts/test/test-e2e-stamp'
 import { run_hold, type HoldRead, type RunHold } from './run-hold'
+import { run_hold_adopt } from './run-hold-adopt'
+import { run_stop_notify } from './run-stop-notify'
 
 // `josh run:hold [<N>]` and `josh run:release [<N> | --force]` — the working-tree guard the typed
 // entry points ask before they start.
@@ -37,7 +38,6 @@ import { run_hold, type HoldRead, type RunHold } from './run-hold'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const RELEASE_FLAG = '--release'
 // What removes a record this run did not write. **Deliberate friction**: every release names the run
 // it belongs to, and the one act that cannot — clearing a record somebody else left behind — is
@@ -49,10 +49,14 @@ const FULLRUN_FLAG = '--fullrun'
 const HALFRUN_STOP_FLAG = '--halfrun-stop'
 // A `prrun`'s stop before merge: its record keeps the commit it stopped on.
 const PRRUN_STOP_FLAG = '--prrun-stop'
+// A `needs-human-review` stop: marked as a `halfrun` stop is, with its own confirmation.
+const HUMAN_REVIEW_STOP_FLAG = '--human-review-stop'
+// A `new` run's hand-over of its unnumbered record to the Issue it filed (`run-hold-adopt.ts`).
+const ADOPT_FLAG = '--adopt'
 // The most a claim reads: the issue number and the one flag after it.
 const MAX_CLAIM_ARGUMENTS = 2
 const USAGE =
-	'Usage: josh run:hold [<issue-number> [--fullrun | --halfrun-stop | --prrun-stop]] | josh run:release [<issue-number> | --force]'
+	'Usage: josh run:hold [<issue-number> [--fullrun | --halfrun-stop | --human-review-stop | --prrun-stop]] | josh run:hold --adopt <issue-number> | josh run:release [<issue-number> | --force]'
 
 const COMMAND = 'run:hold'
 
@@ -64,10 +68,16 @@ const NONE_VERDICT = 'none'
 // The record is another run's, so nothing was removed. **It is not `none`**: a release that did not
 // happen must never read to a script as a tree it has just freed.
 const HELD_VERDICT = 'held'
+// A stop before commit asked on a tree `josh test:e2e` has not answered green on: nothing was marked.
+const E2E_OWED_VERDICT = 'e2e-owed'
 
 const FORCE_RELEASE_KIND = 'force-release'
 const HALFRUN_STOP_KIND = 'halfrun-stop'
+const HUMAN_REVIEW_STOP_KIND = 'human-review-stop'
 const PRRUN_STOP_KIND = 'prrun-stop'
+const ADOPT_KIND = 'adopt'
+
+type StopKind = typeof HALFRUN_STOP_KIND | typeof HUMAN_REVIEW_STOP_KIND | typeof PRRUN_STOP_KIND
 
 interface ClaimRequest {
 	kind: 'claim'
@@ -76,18 +86,25 @@ interface ClaimRequest {
 }
 
 interface StopRequest {
-	kind: typeof HALFRUN_STOP_KIND | typeof PRRUN_STOP_KIND
+	kind: StopKind
 	issue: string
 }
 
 type HoldRequest =
 	| ClaimRequest
 	| StopRequest
+	| { kind: typeof ADOPT_KIND; issue: string }
 	| { kind: 'release'; claimant: string }
 	| { kind: typeof FORCE_RELEASE_KIND }
 
+const STOP_KINDS: ReadonlySet<string> = new Set([
+	HALFRUN_STOP_KIND,
+	HUMAN_REVIEW_STOP_KIND,
+	PRRUN_STOP_KIND,
+])
+
 function is_stop_request(request: HoldRequest): request is StopRequest {
-	return request.kind === HALFRUN_STOP_KIND || request.kind === PRRUN_STOP_KIND
+	return STOP_KINDS.has(request.kind)
 }
 
 const FORCE_RELEASE_REQUEST: HoldRequest = { kind: FORCE_RELEASE_KIND }
@@ -96,14 +113,14 @@ function release_request(claimant: string): HoldRequest {
 	return { kind: 'release', claimant }
 }
 
-const STOP_KIND_BY_FLAG: ReadonlyMap<string, typeof HALFRUN_STOP_KIND | typeof PRRUN_STOP_KIND> =
-	new Map([
-		[HALFRUN_STOP_FLAG, HALFRUN_STOP_KIND],
-		[PRRUN_STOP_FLAG, PRRUN_STOP_KIND],
-	])
+const STOP_KIND_BY_FLAG: ReadonlyMap<string, StopKind> = new Map([
+	[HALFRUN_STOP_FLAG, HALFRUN_STOP_KIND],
+	[HUMAN_REVIEW_STOP_FLAG, HUMAN_REVIEW_STOP_KIND],
+	[PRRUN_STOP_FLAG, PRRUN_STOP_KIND],
+])
 
-// The flag after a numbered claim: absent, `--fullrun`, `--halfrun-stop` or `--prrun-stop`. Anything
-// else is a usage error.
+// The flag after a numbered claim: absent, `--fullrun`, `--halfrun-stop`, `--human-review-stop` or
+// `--prrun-stop`. Anything else is a usage error.
 function numbered_claim(issue: string, flag: string | undefined): HoldRequest | undefined {
 	if (flag === undefined) return { kind: 'claim', issue }
 
@@ -142,9 +159,21 @@ function parse_release(argv: ReadonlyArray<string>): HoldRequest | undefined {
 	return argv.length > 1 ? undefined : parse_release_argument(first)
 }
 
+function parse_adopt(argv: ReadonlyArray<string>): HoldRequest | undefined {
+	const [issue] = argv
+
+	if (issue === undefined || argv.length > 1) return undefined
+
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)
+		? { kind: ADOPT_KIND, issue }
+		: undefined
+}
+
 function parse_request(argv: ReadonlyArray<string>): HoldRequest | undefined {
 	if (argv[0] === RELEASE_FLAG) return parse_release(argv.slice(1))
 
+	if (argv[0] === ADOPT_FLAG) return parse_adopt(argv.slice(1))
+
 	return parse_claim(argv)
 }
 
@@ -339,25 +368,73 @@ function report_usage(): number {
 	return FAILURE_EXIT_CODE
 }
 
+const SEND_BY_KIND: Readonly<Record<StopKind, (target: string, issue: string) => Promise<void>>> = {
+	[HALFRUN_STOP_KIND]: run_stop_notify.send_halfrun,
+	[HUMAN_REVIEW_STOP_KIND]: run_stop_notify.send_human_review,
+	[PRRUN_STOP_KIND]: run_stop_notify.send_prrun,
+}
+
 // **A `halfrun` stop marks its own record** — the positive "this run has ended over its verified diff"
-// that `run:entry` adopts on `fullrun #N`. Another run's record is left alone. A `prrun` stop marks
-// its record the same way, with the commit it stopped on.
+// that `run:entry` adopts on `fullrun #N`. Another run's record is left alone. A `needs-human-review`
+// stop is the same mark, since its resume is `halfrun`'s. A `prrun` stop marks its record the same
+// way, with the commit it stopped on. **A marked stop then sends its own `confirmation`**
+// (`run-stop-notify.ts`), after the mark, since the mark rewrites the record its send is stamped on.
+async function marked_stop(target: string, request: StopRequest): Promise<number> {
+	await SEND_BY_KIND[request.kind](target, request.issue)
+
+	return report_hold()
+}
+
+// **A stop before commit has no CI E2E job behind it**, so it is refused until `josh test:e2e` has
+// answered green on this exact tree (`test-e2e-stamp.ts`). A `prrun` stop has a pull request, and CI's.
+async function e2e_refusal(request: StopRequest): Promise<number | undefined> {
+	if (request.kind === PRRUN_STOP_KIND || (await test_e2e_stamp.is_current_tree())) return undefined
+
+	return report(
+		'run:hold: `pnpm josh test:e2e` has not answered green on this tree — run it, then mark the stop again.',
+		E2E_OWED_VERDICT,
+		FAILURE_EXIT_CODE,
+	)
+}
+
 async function mark_stop(target: string, request: StopRequest): Promise<number> {
+	const refusal = await e2e_refusal(request)
+
+	if (refusal !== undefined) return refusal
+
 	const mark =
 		request.kind === PRRUN_STOP_KIND
 			? await run_prrun_resume.mark_stop_at(target, request.issue)
 			: run_halfrun_resume.mark_stop_at(target, request.issue)
 
-	if (mark === run_halfrun_resume.MARKED) return report_hold()
+	if (mark === run_halfrun_resume.MARKED) return await marked_stop(target, request)
 
 	if (mark === run_halfrun_resume.UNREADABLE) return report_unreadable_record()
 
 	return report_busy(run_hold.race_message(run_hold.read_hold(target), target))
 }
 
+// The re-keyed record answers `hold`; no record answers `none` and another issue's `busy`, each a
+// failure, since the run asking holds nothing it can stop on.
+async function adopt(target: string, issue: string): Promise<number> {
+	const result = await run_hold_adopt.adopt(target, issue)
+
+	if (result === run_hold_adopt.ADOPTED) return report_hold()
+
+	if (result === run_hold_adopt.UNREADABLE) return report_unreadable_record()
+
+	if (result === run_hold_adopt.NO_RECORD) {
+		return report(run_hold_adopt.no_record_message(issue), NONE_VERDICT, FAILURE_EXIT_CODE)
+	}
+
+	return report(run_hold_adopt.foreign_message(issue), BUSY_VERDICT, FAILURE_EXIT_CODE)
+}
+
 async function dispatch(request: HoldRequest, target: string, is_linked: boolean): Promise<number> {
 	if (request.kind === 'claim') return await claim(target, request, is_linked)
 
+	if (request.kind === ADOPT_KIND) return await adopt(target, request.issue)
+
 	if (is_stop_request(request)) return await mark_stop(target, request)
 
 	if (request.kind === FORCE_RELEASE_KIND) return force_release(target)
@@ -392,10 +469,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	}
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const run_hold_cli = {
 	BUSY_VERDICT,
 	HELD_VERDICT,
@@ -408,6 +481,4 @@ const run_hold_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { run_hold_cli }

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_hold_cli } from './run-hold-cli'
+
+// The `josh run:hold` and `josh run:release` entry, kept apart from `run-hold-cli.ts` because other
+// modules import that one: a bundle is one file, so a main guard there would fire for every command
+// that carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await run_hold_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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

@@ -0,0 +1,37 @@
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { run_hold, type RunHold, type SessionOwner } from './run-hold'
+import { run_hold_session } from './run-hold-session'
+
+// Whether this session is one of a run's own (joshuafolkken/kit#4099): a lane child, or the session
+// holding the run's hold on this working tree. The run's event stream is the repository's, so a
+// session outside the run — a question answered beside a `backlogrun` — writes to it too, and what it
+// files is not the run's.
+//
+// **Unknown is outside.** Unlike the `Stop` hook's question (`run-hold-session.ts`), a hold or a session
+// with no owner recorded is not this session's: counting another session's filing as the run's is the
+// failure this answers.
+
+function is_owned(hold: RunHold, owner: SessionOwner): boolean {
+	if (hold.owner_pid === undefined || owner.owner_pid === undefined) return false
+
+	return run_hold_session.is_session_hold(hold, owner)
+}
+
+async function is_hold_owner(owner: SessionOwner): Promise<boolean> {
+	const directory = await run_hold.worktree_directory()
+	if (directory === undefined) return false
+
+	const read = run_hold.read_hold(run_hold.hold_path(directory))
+
+	return read.kind === 'held' && is_owned(read.hold, owner)
+}
+
+async function is_run_member(owner: SessionOwner = run_hold.session_owner()): Promise<boolean> {
+	if (lane_child_marker.marked_issue() !== undefined) return true
+
+	return await is_hold_owner(owner)
+}
+
+const run_hold_member = { is_run_member }
+
+export { run_hold_member }