@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/issue/issue-watch-diff.ts

@@ -0,0 +1,152 @@
+import { read_json_listing } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+// What a person changed on an issue since a run last read it, as the one pure answer the hook, the
+// review attestation, `josh issue:ack` and `josh followup` all print. Kept free of I/O so the four
+// callers cannot each draw the line between "a person's update" and "noise" differently.
+//
+// **A person's update is a body edit or a comment nobody automated.** A bot's comment (`type: Bot`,
+// or a `[bot]` login) is not one. A run's own comment is posted under the person's own `gh` login,
+// so the login cannot tell the two apart; `git-gh-issue-write.ts` stamps every comment josh posts
+// with `RUN_MARKER`, and a marked comment is not one either. An unmarked comment written by hand
+// through a raw `gh api` counts as a person's — the direction that costs one `josh issue:ack`, never a
+// missed correction.
+//
+// **Comment edits are out of scope.** A new comment carries an id above the baseline's; an edited
+// one keeps its id and is not seen. The body is compared whole, so its edits are.
+
+const RUN_MARKER = '<!-- josh:run -->'
+const BOT_TYPE = 'Bot'
+const BOT_SUFFIX = '[bot]'
+const NO_COMMENT_ID = 0
+const UNKNOWN_AUTHOR = '(unknown)'
+const UNKNOWN_TIME = '(undated)'
+
+const BODY_HEADING = 'Body edited:'
+const REMOVED_PREFIX = '- '
+const ADDED_PREFIX = '+ '
+const COMMENT_HEADING = 'New comment by '
+const AT = ' at '
+const SECTION_SEPARATOR = '\n\n'
+const LINE_SEPARATOR = '\n'
+const CRLF = '\r\n'
+
+const comment_schema = z.looseObject({
+	id: z.number(),
+	user: z.looseObject({ login: z.string(), type: z.string().optional() }).nullish(),
+	created_at: z.string().optional(),
+	body: z.string().nullish(),
+})
+
+interface WatchComment {
+	id: number
+	author: string
+	is_automated: boolean
+	created_at: string
+	body: string
+}
+
+interface WatchSnapshot {
+	body: string
+	comments: ReadonlyArray<WatchComment>
+}
+
+interface WatchBaseline {
+	body: string
+	last_comment_id: number
+}
+
+function is_bot(user: z.infer<typeof comment_schema>['user']): boolean {
+	return user?.type === BOT_TYPE || (user?.login.endsWith(BOT_SUFFIX) ?? false)
+}
+
+function is_automated(user: z.infer<typeof comment_schema>['user'], body: string): boolean {
+	return is_bot(user) || body.includes(RUN_MARKER)
+}
+
+function to_comment(raw: z.infer<typeof comment_schema>): WatchComment {
+	const body = raw.body ?? ''
+	const author = raw.user?.login ?? UNKNOWN_AUTHOR
+	const created_at = raw.created_at ?? UNKNOWN_TIME
+
+	return { id: raw.id, author, is_automated: is_automated(raw.user, body), created_at, body }
+}
+
+// `undefined` — never `[]` — for a listing that could not be read, so a failed read is never taken
+// for "nobody commented".
+function parse_comments(json: string | undefined): ReadonlyArray<WatchComment> | undefined {
+	if (json === undefined) return undefined
+
+	const listing = read_json_listing(json, comment_schema)
+
+	return listing.kind === 'read' ? listing.rows.map((row) => to_comment(row)) : undefined
+}
+
+function last_comment_id(comments: ReadonlyArray<WatchComment>): number {
+	return Math.max(NO_COMMENT_ID, ...comments.map((comment) => comment.id))
+}
+
+function baseline_of(snapshot: WatchSnapshot): WatchBaseline {
+	return { body: snapshot.body, last_comment_id: last_comment_id(snapshot.comments) }
+}
+
+function lines_missing_from(source: string, other: string): Array<string> {
+	const present = new Set(other.split(LINE_SEPARATOR))
+
+	return source.split(LINE_SEPARATOR).filter((line) => line.trim() !== '' && !present.has(line))
+}
+
+// GitHub stores a body saved in its web editor with CRLF line endings, so one edited line to a body
+// josh wrote over the API with LF would otherwise read as every line removed and added.
+function to_lf(body: string): string {
+	return body.split(CRLF).join(LINE_SEPARATOR)
+}
+
+// The lines that left and the lines that arrived — not a positional diff, which would need a
+// dependency in a hook that runs on every tool call, and a reader comparing a spec only needs which
+// sentences changed.
+function body_section(previous_raw: string, current_raw: string): string | undefined {
+	const previous = to_lf(previous_raw)
+	const current = to_lf(current_raw)
+
+	if (previous === current) return undefined
+
+	const removed = lines_missing_from(previous, current).map((line) => `${REMOVED_PREFIX}${line}`)
+	const added = lines_missing_from(current, previous).map((line) => `${ADDED_PREFIX}${line}`)
+
+	return [BODY_HEADING, ...removed, ...added].join(LINE_SEPARATOR)
+}
+
+function comment_section(comment: WatchComment): string {
+	return `${COMMENT_HEADING}${comment.author}${AT}${comment.created_at}${LINE_SEPARATOR}${comment.body}`
+}
+
+function new_person_comments(
+	baseline: WatchBaseline,
+	snapshot: WatchSnapshot,
+): ReadonlyArray<WatchComment> {
+	return snapshot.comments.filter(
+		(comment) => comment.id > baseline.last_comment_id && !comment.is_automated,
+	)
+}
+
+// The unread update as the text a run is shown, or `undefined` when a person changed nothing.
+function unread_diff(baseline: WatchBaseline, snapshot: WatchSnapshot): string | undefined {
+	const body = body_section(baseline.body, snapshot.body)
+	const comments = new_person_comments(baseline, snapshot).map((comment) =>
+		comment_section(comment),
+	)
+	const sections = [...(body === undefined ? [] : [body]), ...comments]
+
+	return sections.length === 0 ? undefined : sections.join(SECTION_SEPARATOR)
+}
+
+const issue_watch_diff = {
+	RUN_MARKER,
+	baseline_of,
+	parse_comments,
+	unread_diff,
+}
+
+export type { WatchBaseline, WatchComment, WatchSnapshot }
+export { issue_watch_diff }

package/scripts/issue/issue-watch-gate.ts

@@ -0,0 +1,81 @@
+import { git_command } from '#scripts/git/git-command'
+import { session_cite } from '#scripts/issue/session-cite'
+import { review_attest } from '#scripts/review/review-attest'
+import { issue_watch, type WatchRecord } from './issue-watch'
+
+// The refusals a person's unread issue update raises, composed once so the hook, `josh review:attest
+// --check` and `josh followup` say the same thing about the same state.
+//
+// **The gates poll on every call** (`interval_ms: 0`): they run a handful of times per run, and the
+// poll is a conditional request that a 304 answers for free. Only the hook, which runs on every tool
+// call, spaces its polls out.
+
+const EVERY_CALL_MS = 0
+
+function ack_command(issue: string): string {
+	return `pnpm josh issue:ack ${issue}`
+}
+
+function unread_message(record: Pick<WatchRecord, 'issue' | 'pending'>): string {
+	return [
+		`A person updated issue ${session_cite.issue(record.issue)} after this run read it, and the run has not taken the update in:`,
+		record.pending ?? '',
+		`Read it, compare it with the acceptance criteria, fix what it changes, then run \`${ack_command(record.issue)}\` to record that it was read.`,
+	].join('\n\n')
+}
+
+function review_message(record: WatchRecord, briefed_at: string): string {
+	return [
+		`Issue ${session_cite.issue(record.issue)} was updated after the review was briefed (taken in at ${record.acknowledged_at}, briefed at ${briefed_at}), so the review read the earlier specification.`,
+		'Re-run `/code-review` with a fresh `pnpm josh review:brief`, so the review reads the change against the updated issue.',
+	].join('\n')
+}
+
+async function polled(root: string): Promise<WatchRecord | undefined> {
+	return await issue_watch.poll({ interval_ms: EVERY_CALL_MS }, root)
+}
+
+// The merge-time refusal: a person's update the run has not acknowledged. `undefined` when there is
+// none, when no run recorded a baseline in this checkout, or when the issue could not be read — an
+// unreachable GitHub does not hold a merge `josh followup` would otherwise make.
+async function unread_refusal(root: string): Promise<string | undefined> {
+	const record = await polled(root)
+
+	return record?.pending === undefined ? undefined : unread_message(record)
+}
+
+// The review-time refusal: an unread update, or one taken in after the review was briefed — the fix
+// it led to is then a change the review never saw.
+async function review_refusal(root: string): Promise<string | undefined> {
+	const record = await polled(root)
+
+	if (record === undefined) return undefined
+	if (record.pending !== undefined) return unread_message(record)
+
+	const pointer = review_attest.read_pointer(root)
+
+	if (pointer === undefined || record.acknowledged_at <= pointer.taken_at) return undefined
+
+	return review_message(record, pointer.taken_at)
+}
+
+async function review_refusal_here(): Promise<string | undefined> {
+	return await review_refusal(await git_command.repository_root())
+}
+
+// Throws the refusal, for the `josh followup` seams that stop by throwing.
+async function assert_read_here(): Promise<void> {
+	const refusal = await unread_refusal(await git_command.repository_root())
+
+	if (refusal !== undefined) throw new Error(refusal)
+}
+
+const issue_watch_gate = {
+	assert_read_here,
+	review_refusal,
+	review_refusal_here,
+	unread_message,
+	unread_refusal,
+}
+
+export { issue_watch_gate }

package/scripts/issue/issue-watch-hook.ts

@@ -0,0 +1,54 @@
+import { error_text } from '#scripts/lib/error-message'
+import { issue_watch, type WatchRecord } from './issue-watch'
+import { issue_watch_gate } from './issue-watch-gate'
+
+// The `PreToolUse` adapter that shows a run a person's update to its issue on the next tool call,
+// composed into `pretool-guard.ts` — the one PreToolUse hook — rather than added as a second
+// `.claude/settings.json` entry.
+//
+// **It polls at most once per interval.** Every tool call reads the checkout's record from disk; only
+// one whose last poll is older than `POLL_INTERVAL_MS` asks GitHub, with the ETag of the previous
+// answer, so an unchanged issue costs a 304. The request is bounded well under the hook's own timeout.
+//
+// **It refuses once per update.** The refusal is what puts the update in front of the run; repeating
+// it on every call would wedge the run before it could act. A further update changes the pending text
+// and is shown again. `josh issue:ack` clears it, and the review attestation and `josh followup` keep
+// refusing until it does — the hook is the early warning, not the enforcement.
+//
+// **It fails open.** No record, an unreadable issue or a thrown error allows the call: a hook that
+// stalls every tool call over a network blip would cost more than the update it watches for.
+
+const POLL_INTERVAL_MS = 180_000
+const POLL_TIMEOUT_MS = 5000
+
+function is_new_to_run(record: WatchRecord | undefined): record is WatchRecord {
+	return record?.pending !== undefined && record.pending !== record.shown
+}
+
+async function new_update_reason(now: Date): Promise<string | undefined> {
+	const record = await issue_watch.poll({
+		interval_ms: POLL_INTERVAL_MS,
+		timeout_ms: POLL_TIMEOUT_MS,
+		now,
+	})
+
+	if (!is_new_to_run(record)) return undefined
+
+	issue_watch.mark_shown(record)
+
+	return issue_watch_gate.unread_message(record)
+}
+
+async function watch_reason(now: Date = new Date()): Promise<string | undefined> {
+	try {
+		return await new_update_reason(now)
+	} catch (error) {
+		error_text.trace_swallowed('issue_watch_hook.watch_reason', error)
+
+		return undefined
+	}
+}
+
+const issue_watch_hook = { POLL_INTERVAL_MS, watch_reason }
+
+export { issue_watch_hook }

package/scripts/issue/issue-watch.ts

@@ -0,0 +1,240 @@
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_conditional } from '#scripts/gh/git-gh-conditional'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_command } from '#scripts/git/git-command'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { issue_watch_diff, type WatchSnapshot } from './issue-watch-diff'
+
+// The record of what a run last read of its issue, and the poll that compares the issue against it.
+//
+// **The baseline is written where the run reads the issue** — `josh run:entry`, which prints the body
+// and every comment — so it is the same for a dispatched lane child and a `fullrun` in a person's own
+// checkout, and a resume that prints nothing keeps the baseline it had. One record per checkout,
+// keyed on its root like the review attestation, carries the issue number, so the hook needs no other
+// way to learn which issue the session works on.
+//
+// **A poll is a conditional request.** The issue object's ETag changes with its body and with its
+// comment count, so a 304 there means neither moved and the comments are not read at all.
+
+const RECORD_PREFIX = 'josh-issue-watch-'
+const CLOSED_STATE = 'closed'
+
+const record_schema = z.object({
+	issue: z.string(),
+	body: z.string(),
+	last_comment_id: z.number(),
+	acknowledged_at: z.string(),
+	checked_at: z.string(),
+	etag: z.string().optional(),
+	pending: z.string().optional(),
+	shown: z.string().optional(),
+})
+
+const issue_schema = z.looseObject({ body: z.string().nullish(), state: z.string() })
+
+type WatchRecord = z.infer<typeof record_schema>
+
+type Fetched =
+	| { kind: 'unchanged' }
+	| { kind: 'unreadable' }
+	| { kind: 'closed' }
+	| { kind: 'read'; snapshot: WatchSnapshot; etag: string | undefined }
+
+const UNREADABLE: Fetched = { kind: 'unreadable' }
+
+function record_path(root: string = PROJECT_ROOT): string {
+	return stamp_file.stamp_path(RECORD_PREFIX, root)
+}
+
+function read_record(root?: string): WatchRecord | undefined {
+	const raw = stamp_file.read_stamp_text(record_path(root))
+
+	return raw === undefined ? undefined : json_value.parse_with(raw, record_schema)
+}
+
+function write_record(record: WatchRecord, root?: string): WatchRecord {
+	stamp_file.replace_stamp(record_path(root), record)
+
+	return record
+}
+
+function clear(root?: string): void {
+	stamp_file.remove_stamp(record_path(root))
+}
+
+interface FetchRequest {
+	issue: string
+	etag?: string | undefined
+	timeout_ms?: number | undefined
+}
+
+async function read_snapshot(
+	request: FetchRequest,
+	body: string,
+	etag: string | undefined,
+): Promise<Fetched> {
+	const comments = issue_watch_diff.parse_comments(
+		await git_gh_issue_read.issue_list_comments(request.issue, request.timeout_ms),
+	)
+
+	return comments === undefined ? UNREADABLE : { kind: 'read', snapshot: { body, comments }, etag }
+}
+
+async function fetch_issue(request: FetchRequest): Promise<Fetched> {
+	const read = await git_gh_conditional.read_conditional(
+		git_gh_api_path.issue_api_path(request.issue),
+		request.etag,
+		request.timeout_ms,
+	)
+
+	if (read.kind !== 'changed') return read
+
+	const fields = json_value.parse_with(read.body, issue_schema)
+
+	if (fields === undefined) return UNREADABLE
+	if (fields.state === CLOSED_STATE) return { kind: 'closed' }
+
+	return await read_snapshot(request, fields.body ?? '', read.etag)
+}
+
+// `acknowledged_at` is when a person's update was last taken in — the baseline's own read, or an
+// acknowledgement that had something to take in. The review attestation compares it with the brief.
+function fresh_record(
+	issue: string,
+	fetched: Extract<Fetched, { kind: 'read' }>,
+	now: Date,
+	acknowledged_at: string = now.toISOString(),
+): WatchRecord {
+	const baseline = issue_watch_diff.baseline_of(fetched.snapshot)
+	const checked_at = now.toISOString()
+
+	return { issue, ...baseline, acknowledged_at, checked_at, etag: fetched.etag }
+}
+
+// Called by `josh run:entry` once it has printed the issue. `false` when the issue could not be read,
+// which leaves no record — a watch with no baseline would call the whole issue unread.
+async function record_baseline(
+	issue: string,
+	root?: string,
+	now: Date = new Date(),
+): Promise<boolean> {
+	const fetched = await fetch_issue({ issue })
+
+	if (fetched.kind !== 'read') return false
+
+	write_record(fresh_record(issue, fetched, now), root)
+
+	return true
+}
+
+// The `_here` forms key the record on the repository root rather than `process.cwd()`, the same reason
+// `review_attest.check_here` does: a run started from a subdirectory must find the record it wrote.
+async function record_baseline_here(issue: string): Promise<boolean> {
+	return await record_baseline(issue, await git_command.repository_root())
+}
+
+async function clear_here(): Promise<void> {
+	clear(await git_command.repository_root())
+}
+
+function with_fetched(record: WatchRecord, fetched: Fetched, checked_at: string): WatchRecord {
+	if (fetched.kind !== 'read') return { ...record, checked_at }
+
+	const pending = issue_watch_diff.unread_diff(record, fetched.snapshot)
+
+	return { ...record, checked_at, etag: fetched.etag, pending }
+}
+
+interface PollOptions {
+	interval_ms: number
+	timeout_ms?: number
+	now?: Date
+}
+
+function is_due(record: WatchRecord, options: PollOptions, now: Date): boolean {
+	return now.getTime() - Date.parse(record.checked_at) >= options.interval_ms
+}
+
+async function refresh(
+	record: WatchRecord,
+	options: PollOptions,
+	now: Date,
+	root?: string,
+): Promise<WatchRecord | undefined> {
+	const fetched = await fetch_issue({
+		issue: record.issue,
+		etag: record.etag,
+		timeout_ms: options.timeout_ms,
+	})
+
+	if (fetched.kind === 'closed') {
+		clear(root)
+
+		return undefined
+	}
+
+	return write_record(with_fetched(record, fetched, now.toISOString()), root)
+}
+
+// The checkout's record, polled when the last poll is at least `interval_ms` old. `undefined` when no
+// run recorded a baseline here, or the issue has closed — a closed issue ends its watch.
+async function poll(options: PollOptions, root?: string): Promise<WatchRecord | undefined> {
+	const record = read_record(root)
+	const now = options.now ?? new Date()
+
+	if (record === undefined || !is_due(record, options, now)) return record
+
+	return await refresh(record, options, now, root)
+}
+
+// Marks a pending update shown, so the hook stops once per update rather than on every call.
+function mark_shown(record: WatchRecord, root?: string): WatchRecord {
+	return write_record({ ...record, shown: record.pending }, root)
+}
+
+interface Acknowledged {
+	issue: string
+	diff: string | undefined
+}
+
+// `josh issue:ack`: read the issue as it is now, return what changed since the baseline, and make
+// that the new baseline. **What is returned is exactly what is acknowledged** — the read and the new
+// baseline are the same snapshot, so an update landing between the two cannot be acknowledged unseen.
+async function acknowledge(
+	root?: string,
+	now: Date = new Date(),
+): Promise<Acknowledged | undefined> {
+	const record = read_record(root)
+
+	if (record === undefined) return undefined
+
+	const fetched = await fetch_issue({ issue: record.issue })
+
+	if (fetched.kind !== 'read') return undefined
+
+	const diff = issue_watch_diff.unread_diff(record, fetched.snapshot)
+
+	const acknowledged_at = diff === undefined ? record.acknowledged_at : now.toISOString()
+
+	write_record(fresh_record(record.issue, fetched, now, acknowledged_at), root)
+
+	return { issue: record.issue, diff }
+}
+
+const issue_watch = {
+	acknowledge,
+	clear,
+	clear_here,
+	mark_shown,
+	poll,
+	read_record,
+	record_baseline,
+	record_baseline_here,
+	record_path,
+}
+
+export type { Acknowledged, PollOptions, WatchRecord }
+export { issue_watch }

package/scripts/issue/measure-rerun-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { execSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { gh_author_association } from '#scripts/gh/gh-author-association'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
@@ -24,8 +25,6 @@ import { session_cite } from './session-cite'
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const ISSUE_FIELDS = 'body,author_association'
-const TRUSTED_ASSOCIATIONS: ReadonlySet<string> = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
-const TRUSTED_LIST = [...TRUSTED_ASSOCIATIONS].join(' / ')
 const UNKNOWN_ASSOCIATION = 'unknown'
 const USAGE = 'Usage: josh measure:rerun <issue-number>'
 const NO_BASELINE = 'no `command → value` baseline found in ## ベースライン — nothing to re-run'
@@ -100,10 +99,10 @@ async function read_trusted_body(issue_number: string): Promise<BodyRead> {
 
 	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
 
-	if (!TRUSTED_ASSOCIATIONS.has(association)) {
+	if (!gh_author_association.is_trusted(association)) {
 		return {
 			kind: 'refused',
-			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${TRUSTED_LIST}`,
+			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${gh_author_association.TRUSTED_LIST}`,
 		}
 	}
 

package/scripts/josh/josh-command-map.ts

@@ -54,6 +54,7 @@ const ALIASES: Record<string, string> = {
 	pf: 'profile',
 	st: 'start',
 	sy: 'sync',
+	un: 'uninstall',
 	rmi: 'registry:migrate',
 	g: 'git',
 	gp: 'pr',
@@ -79,9 +80,12 @@ const ALIASES: Record<string, string> = {
 	rvf: 'review:findings',
 	ruv: 'rule:value',
 	ev: 'eval',
+	fr: 'fresh:run',
+	as: 'auth:setup',
 	lsm: 'lane:sample',
 	lst: 'lane:stats',
 	lli: 'lane:limit',
+	lrs: 'lane:restart',
 	blr: 'backlogrun',
 }
 

package/scripts/josh/josh-commands-backlog.ts

@@ -11,10 +11,10 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 	backlogrun: {
 		script: 'scripts/backlog/backlogrun-cli.ts',
 		description:
-			'Start a backlogrun in the background and show its board; with one already running, only show the board',
+			'Start a backlogrun in the background and show its board; with one already running, only show the board, or replace it when it is idle and the invocation differs; --stop stops it',
 		category: 'AI tools',
 		reference: [
-			'[#<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex]',
+			'[<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop',
 			'developer',
 			['files', 'network', 'processes'],
 		],

package/scripts/josh/josh-commands-development.ts

@@ -181,7 +181,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'test:unit': {
 		script: 'scripts/test/test-unit-guard.ts',
 		description:
-			'Run unit tests with Vitest (skips when Vitest is absent; fails when it has no tests)',
+			'Run unit tests with Vitest (without Vitest: a basic project runs its own test script, others skip; fails when Vitest has no tests)',
 		category: 'Development',
 		reference: [FILTER_ARGUMENTS, 'developer', ['processes']],
 		core_weight: gate_plan.direct_unit_weight,

package/scripts/josh/josh-commands-issue.ts

@@ -11,6 +11,13 @@ const ISSUES_WITH_REPO = '<issue...> [--repo <owner/repo>]'
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const ISSUE_COMMANDS: Record<string, CommandEntry> = {
+	'issue:ack': {
+		script: 'scripts/issue/issue-ack-cli.ts',
+		description:
+			"Record that the run read a person's update to its issue, printing the update it acknowledges",
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
 	'issue:read': {
 		script: 'scripts/issue/issue-read-cli.ts',
 		description: "Print each issue's title, body and every comment on it, in one call",

package/scripts/josh/josh-commands-lane.ts

@@ -40,7 +40,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:prune': {
 		...LANE_ARGUMENTS,
 		description:
-			'Close every lane an interruption left without its work tree, then sweep unregistered leftovers under the lanes root',
+			'Close every lane an interruption left without its work tree and every spent lane, then sweep unregistered leftovers under the lanes root',
 		category: 'AI tools',
 		reference: ['', 'automation', ['files', 'git']],
 		default_script_arguments: ['prune'],
@@ -74,6 +74,15 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [--stash <message>]', 'automation', ['files', 'git', 'processes']],
 	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+	'lane:restart': {
+		script: 'scripts/lane/lane-restart-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Stop a running lane child, stash its uncommitted work and re-dispatch its issue in a fresh session — not counted as an outage or a failure',
+		category: 'AI tools',
+		reference: ['<issue>', 'developer', ['files', 'git', 'processes', 'network']],
+	},
 	// A live run's lane limit: `.env` is read so the bare form reports the
 	// `JOSH_LANE_LIMIT` a person set there when no override stands.
 	'lane:limit': {
@@ -97,7 +106,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print one table row of lane throughput, gate duration and machine load over a period, and the per-stage durations of a lane under it',
+			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, and the wait after each ship stop reason under those',
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],