@joshuafolkken/kit 1.1435.0 → 1.1455.0

package/scripts/josh/process-identity.ts

@@ -52,6 +52,7 @@ const PROBE_ENVIRONMENT = { TZ: 'UTC', LC_ALL: 'C' }
 // `process.kill(pid, 0)` runs every permission check and delivers nothing, so it is the standard
 // liveness probe: it throws `ESRCH` where the process is gone.
 const LIVENESS_SIGNAL = 0
+const NO_SUCH_PROCESS = 'ESRCH'
 // Below this a pid is not a process: `0` addresses the caller's own process group and anything
 // negative addresses another group, so a truncated or hand-edited record carrying either would
 // otherwise answer "alive" forever.
@@ -79,18 +80,28 @@ interface StartProbes {
 	read_ps_start: (pid: number) => string | undefined
 }
 
-function is_live_pid(pid: number): boolean {
-	if (pid < LOWEST_REAL_PID) return false
-
+// The code the liveness probe was refused with, or nothing where the caller may signal the process.
+function signal_refusal(pid: number): string | undefined {
 	try {
 		process.kill(pid, LIVENESS_SIGNAL)
 
-		return true
-	} catch {
-		return false
+		return undefined
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code ?? NO_SUCH_PROCESS
 	}
 }
 
+function is_live_pid(pid: number): boolean {
+	return pid >= LOWEST_REAL_PID && signal_refusal(pid) === undefined
+}
+
+// **Whether a pid names any process at all, for a reader that may not be allowed to signal it.** Only
+// `ESRCH` proves the process gone: `EPERM` is the kernel refusing a signal to a process it has just
+// found — one under another user, or outside a sandbox that may only signal its own — so it is present.
+function is_present_pid(pid: number): boolean {
+	return pid >= LOWEST_REAL_PID && signal_refusal(pid) !== NO_SUCH_PROCESS
+}
+
 // Linux exposes field 22 as the process start time in clock ticks since boot. The command name in
 // field 2 may itself contain spaces or `)`, so parsing starts after its final closing parenthesis;
 // `state` is then index 0 and `starttime` index 19. A direct file read avoids process enumeration and
@@ -315,6 +326,19 @@ function is_same_process(
 	return matches_recorded_start(pid, recorded_start, read)
 }
 
+// `is_same_process` for a reader that may not be allowed to signal the writer (`is_present_pid`): a
+// refused signal still compares the start time, so a reissued pid separates from its writer here too.
+function is_present_process(
+	pid: number,
+	recorded_start: string | undefined,
+	read: (pid: number) => string | undefined = read_start,
+): boolean | undefined {
+	if (!is_present_pid(pid)) return false
+	if (recorded_start === undefined) return undefined
+
+	return matches_recorded_start(pid, recorded_start, read)
+}
+
 // **Whether a record is the caller's own, which is a different question from whether its writer is
 // alive**. `is_same_process` asks about the recorded process; this asks
 // whether that process *is this one*. A supervisor that has been replaced reads its successor's
@@ -339,6 +363,8 @@ const process_identity = {
 	is_live_beacon,
 	is_live_pid,
 	is_own_process,
+	is_present_pid,
+	is_present_process,
 	is_same_process,
 	open_beacon,
 	own_fields,

package/scripts/lane/lane-broker-server.ts

@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs'
+import { process_identity } from '#scripts/josh/process-identity'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// Which process serves a lane's brokered sessions, recorded beside the response it answers in.
+//
+// **A server is live while its process is, never while its event loop happens to answer.** One
+// supervisor serves every Claude lane beside its drive passes, so any synchronous call in it — a
+// `spawnSync` of an agent CLI's `--version` alone may take 10 s — stalled the timer-written heartbeat
+// past its limit and failed every review then in flight (joshuafolkken/kit#3840).
+//
+// **A record of its own rather than fields on the response**, because a ship branched before this
+// record existed parses the response strictly and reads any new field as no server at all; the
+// response keeps the shape and heartbeat that ship reads, and this record names the writer by
+// `process_identity.own_fields()`, so a pid the operating system reissued is not taken for it.
+
+const SERVER_SUFFIX = '.server'
+const server_schema = z
+	.object({
+		session: z.uuid(),
+		pid: z.number().int().positive(),
+		process_start: z.string().optional(),
+	})
+	.strict()
+type BrokerServer = z.infer<typeof server_schema>
+
+function server_path(response: string): string {
+	return `${response}${SERVER_SUFFIX}`
+}
+
+function write(response: string, session: string): void {
+	stamp_file.replace_stamp(server_path(response), { session, ...process_identity.own_fields() })
+}
+
+function remove(response: string): void {
+	stamp_file.remove_stamp(server_path(response))
+}
+
+// Only the record of the session the response names: one left by an earlier server is no answer.
+function read(response: string, session: string): BrokerServer | undefined {
+	try {
+		const server = json_value.parse_with(readFileSync(server_path(response), 'utf8'), server_schema)
+
+		return server?.session === session ? server : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// **The identity is checked when a ship first finds the server, the pid while it waits.** A response
+// a killed supervisor left behind is met on that first look, where a reissued pid must not read as
+// it; the wait polls every 100 ms, where a start-time probe would spawn `ps` on each. Both read
+// through `is_present_*`, because a Codex lane's ship probes from inside its sandbox, where the kernel
+// answers `EPERM` for a supervisor it has found. A start time that cannot be read is no proof of a
+// dead server, so it does not fail the review.
+function is_serving_process(server: BrokerServer): boolean {
+	return process_identity.is_present_process(server.pid, server.process_start) !== false
+}
+
+function is_running(server: BrokerServer): boolean {
+	return process_identity.is_present_pid(server.pid)
+}
+
+const lane_broker_server = { is_running, is_serving_process, read, remove, server_path, write }
+
+export type { BrokerServer }
+export { lane_broker_server }

package/scripts/lane/lane-session-broker.ts

@@ -12,6 +12,7 @@ import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review } from '#scripts/run/ship/run-ship-review'
 import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
 import { z } from 'zod'
+import { lane_broker_server, type BrokerServer } from './lane-broker-server'
 import { lane_child_invocation, type ShipStop } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
 import type { LaneInfo } from './lane-registry'
@@ -32,8 +33,10 @@ const FINDINGS_PREFIX = 'josh-ship-review-findings-'
 const LOG_PREFIX = 'josh-ship-review-log-'
 const CACHE_DIRECTORY = ['node_modules', '.cache']
 const POLL_MS = 100
-const HEARTBEAT_MS = 500
-const HEARTBEAT_LIMIT_MS = 3000
+// The heartbeat is kept for a ship branched before the server record, and read only where a
+// supervisor started before it left no such record (`lane-broker-server.ts`).
+const LEGACY_HEARTBEAT_MS = 500
+const LEGACY_HEARTBEAT_LIMIT_MS = 3000
 const MINUTE_MS = 60_000
 const REQUEST_LIMIT_MINUTES = 30
 const REQUEST_LIMIT_MS = REQUEST_LIMIT_MINUTES * MINUTE_MS
@@ -203,6 +206,7 @@ async function serve(
 	}
 }
 
+// The server record is written before the response, so a ship that finds the response finds it too.
 function prepare(lane: LaneInfo): { response: string; current: BrokerResponse } {
 	const response = response_path(lane.directory, lane.issue)
 	if (response === undefined) throw new Error('review broker has no trusted response location')
@@ -211,6 +215,7 @@ function prepare(lane: LaneInfo): { response: string; current: BrokerResponse }
 
 	mkdirSync(path.dirname(response), { recursive: true })
 	mkdirSync(path.dirname(request_path(lane.directory, lane.issue)), { recursive: true })
+	lane_broker_server.write(response, session)
 	const current: BrokerResponse = {
 		session,
 		nonce: '',
@@ -227,7 +232,7 @@ function start_heartbeat(state: { current: BrokerResponse }, response: string):
 	const heartbeat = setInterval(() => {
 		state.current = { ...state.current, heartbeat_at: Date.now() }
 		write_response(response, state.current)
-	}, HEARTBEAT_MS)
+	}, LEGACY_HEARTBEAT_MS)
 
 	heartbeat.unref()
 
@@ -246,6 +251,7 @@ async function stop_server(
 	await serving
 	clearInterval(heartbeat)
 	unlinkSync(response)
+	lane_broker_server.remove(response)
 }
 
 async function with_server<T>(lane: LaneInfo, run: () => Promise<T>): Promise<T> {
@@ -261,25 +267,40 @@ async function with_server<T>(lane: LaneInfo, run: () => Promise<T>): Promise<T>
 	}
 }
 
+function is_fresh_heartbeat(heartbeat_at: number): boolean {
+	const now = Date.now()
+
+	return heartbeat_at <= now && heartbeat_at >= now - LEGACY_HEARTBEAT_LIMIT_MS
+}
+
+// Live by the server record (`lane-broker-server.ts`); a response with none was written by a
+// supervisor started before it, read by the heartbeat that supervisor still writes.
 function is_live_response(
+	target: string,
 	response: BrokerResponse | undefined,
-	session: string,
+	is_live: (server: BrokerServer) => boolean,
 ): response is BrokerResponse {
-	const now = Date.now()
+	if (response === undefined) return false
 
-	return (
-		response?.session === session &&
-		response.heartbeat_at <= now &&
-		response.heartbeat_at >= now - HEARTBEAT_LIMIT_MS
-	)
+	const server = lane_broker_server.read(target, response.session)
+
+	return server === undefined ? is_fresh_heartbeat(response.heartbeat_at) : is_live(server)
+}
+
+function session_response(target: string, session: string): BrokerResponse | undefined {
+	const response = read_record(target, response_schema)
+
+	return response?.session === session ? response : undefined
 }
 
 function response_verdict(
-	response: BrokerResponse | undefined,
+	target: string,
 	session: string,
 	nonce: string,
 ): 'wait' | 'success' | 'failure' {
-	if (!is_live_response(response, session)) return 'failure'
+	const response = session_response(target, session)
+
+	if (!is_live_response(target, response, lane_broker_server.is_running)) return 'failure'
 	if (response.nonce !== nonce) return 'wait'
 
 	return response.is_success ? 'success' : 'failure'
@@ -289,7 +310,7 @@ async function wait_response(target: string, session: string, nonce: string): Pr
 	const deadline = Date.now() + REQUEST_LIMIT_MS
 
 	while (Date.now() < deadline) {
-		const verdict = response_verdict(read_record(target, response_schema), session, nonce)
+		const verdict = response_verdict(target, session, nonce)
 		if (verdict !== 'wait') return verdict === 'success'
 
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
@@ -302,7 +323,9 @@ async function wait_response(target: string, session: string, nonce: string): Pr
 function live_response(target: string): BrokerResponse | undefined {
 	const response = read_record(target, response_schema)
 
-	return is_live_response(response, response?.session ?? '') ? response : undefined
+	return is_live_response(target, response, lane_broker_server.is_serving_process)
+		? response
+		: undefined
 }
 
 // Whether a server answers for this lane now — what a Claude lane's ship asks before it hands a session

package/scripts/notify/confirmation-options.ts

@@ -0,0 +1,59 @@
+import { session_language } from '#scripts/josh/session-language'
+
+// **A confirmation names what to choose, not only why the run stopped.** The person reading it is
+// off-screen by definition, so the message itself carries the recommended choice and the others —
+// in the session language, because that is the language the person works in.
+
+interface ConfirmationOptions {
+	recommended: string
+	alternatives: ReadonlyArray<string>
+}
+
+interface Headings {
+	recommended: string
+	alternatives: string
+	none: string
+}
+
+const JAPANESE_LANG_PREFIX = 'ja'
+const JAPANESE_HEADINGS: Headings = {
+	recommended: '推奨:',
+	alternatives: '他の選択肢:',
+	none: 'なし',
+}
+const ENGLISH_HEADINGS: Headings = {
+	recommended: 'Recommended:',
+	alternatives: 'Alternatives:',
+	none: 'none',
+}
+
+// Only the two languages the workflow is written in have headings; any other falls back to English.
+function headings(): Headings {
+	const { lang } = session_language.resolve_session_lang()
+
+	return lang.toLowerCase().startsWith(JAPANESE_LANG_PREFIX) ? JAPANESE_HEADINGS : ENGLISH_HEADINGS
+}
+
+// An empty list is stated as none, so a confirmation with no other option says so rather than
+// leaving a reader to wonder whether the line was lost.
+function alternatives_block(options: ConfirmationOptions, labels: Headings): string {
+	if (options.alternatives.length === 0) return `${labels.alternatives} ${labels.none}`
+
+	const lines = options.alternatives.map((alternative) => `- ${alternative}`)
+
+	return [labels.alternatives, ...lines].join('\n')
+}
+
+// The block is handed to the sender as its own `choices` field rather than appended to the body:
+// the body is what a too-long message is cut from, and the choices are the one part a reader cannot
+// act without, so they must survive the cut.
+function block(options: ConfirmationOptions): string {
+	const labels = headings()
+
+	return `${labels.recommended} ${options.recommended}\n${alternatives_block(options, labels)}`
+}
+
+const confirmation_options = { block }
+
+export { confirmation_options }
+export type { ConfirmationOptions }

package/scripts/notify/notify-opt-in.ts

@@ -0,0 +1,33 @@
+import type { TelegramTaskType } from './telegram-notify'
+
+// **`planning` and `completion` reach a person only when they asked for them.** Neither needs the
+// person to act now — a plan is posted on the Issue and a merge is visible on the pull request — so
+// sending both on every run buried the types that do need someone. Every other type is unaffected.
+//
+// **One variable listing the opted-in types, not one switch per type**, so making a further type
+// optional later adds an entry to `OPTIONAL_TASK_TYPES` rather than another variable.
+const OPT_IN_KEY = 'JOSH_NOTIFY_OPT_IN'
+const OPTIONAL_TASK_TYPES: ReadonlySet<TelegramTaskType> = new Set(['planning', 'completion'])
+const LIST_SEPARATOR = ','
+
+function opted_in_types(): ReadonlyArray<string> {
+	return (process.env[OPT_IN_KEY] ?? '')
+		.split(LIST_SEPARATOR)
+		.map((entry) => entry.trim().toLowerCase())
+		.filter((entry) => entry.length > 0)
+}
+
+// Unset means none: an optional type is sent only once it is named.
+function is_skipped(task_type: TelegramTaskType): boolean {
+	if (!OPTIONAL_TASK_TYPES.has(task_type)) return false
+
+	return !opted_in_types().includes(task_type)
+}
+
+function skip_line(task_type: TelegramTaskType): string {
+	return `🔕 ${task_type} notifications are not opted in (${OPT_IN_KEY}).`
+}
+
+const notify_opt_in = { is_skipped, skip_line }
+
+export { notify_opt_in }

package/scripts/notify/telegram-notify.ts

@@ -1,6 +1,8 @@
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { z } from 'zod'
+import { confirmation_options, type ConfirmationOptions } from './confirmation-options'
+import { notify_opt_in } from './notify-opt-in'
 
 const TELEGRAM_API_BASE = 'https://api.telegram.org'
 // `sendMessage` refuses a text longer than this.
@@ -42,6 +44,9 @@ interface TelegramSendInput {
 	repo_name: string | undefined
 	issue_title: string | undefined
 	body: string | undefined
+	// A confirmation's recommended choice and the others — set beside the body rather than inside it
+	// so a body cut to the length limit never takes the choices with it.
+	choices?: string | undefined
 	issue_url: string | undefined
 	pr_url: string | undefined
 }
@@ -149,6 +154,16 @@ function is_notify_disabled(): boolean {
 	return parse_environment_string(process.env[NOTIFY_SWITCH_KEY]).toLowerCase() === NOTIFY_OFF_VALUE
 }
 
+// The line a skipped send prints, or `undefined` for a send that goes out. The blanket opt-out wins
+// over the per-type opt-in, so `off` stays the one switch that silences everything.
+function skip_line(task_type: TelegramTaskType): string | undefined {
+	if (is_notify_disabled()) {
+		return `🔕 Telegram notifications are disabled (${NOTIFY_SWITCH_KEY}=${NOTIFY_OFF_VALUE}).`
+	}
+
+	return notify_opt_in.is_skipped(task_type) ? notify_opt_in.skip_line(task_type) : undefined
+}
+
 function build_header(task_type: TelegramTaskType, repo_name: string | undefined): string {
 	const { icon, label } = TASK_DEFINITIONS[task_type]
 	if (repo_name === undefined || repo_name.length === 0) return `${icon} ${label}`
@@ -185,6 +200,7 @@ function build_blocks(input: TelegramSendInput): Array<string> {
 	const blocks: Array<string> = [build_title_block(input)]
 
 	push_if_present(blocks, input.body)
+	push_if_present(blocks, input.choices)
 	blocks.push(...build_url_parts(input))
 
 	return blocks
@@ -243,13 +259,13 @@ function build_send_failure(error: unknown, config: TelegramConfig): Error {
 //
 // The failure it throws carries a `cause`, and that cause is redacted too — see `build_send_failure`.
 //
-// The opt-out is checked here, before `load_config`, so every caller — the tolerant form included —
-// skips the same way and none has to repeat the check.
+// The opt-out and the per-type opt-in are checked here, before `load_config`, so every caller — the
+// tolerant form included — skips the same way and none has to repeat the check.
 async function send(input: TelegramSendInput): Promise<void> {
-	if (is_notify_disabled()) {
-		console.info(
-			`🔕 Telegram notifications are disabled (${NOTIFY_SWITCH_KEY}=${NOTIFY_OFF_VALUE}).`,
-		)
+	const skipped = skip_line(input.task_type)
+
+	if (skipped !== undefined) {
+		console.info(skipped)
 
 		return
 	}
@@ -341,7 +357,7 @@ async function warn(input: WarningInput): Promise<boolean> {
 	)
 }
 
-interface ConfirmInput {
+interface ConfirmInput extends ConfirmationOptions {
 	issue_title: string
 	body: string
 	recovery: string
@@ -365,6 +381,7 @@ async function confirm(input: ConfirmInput): Promise<boolean> {
 			repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
 			issue_title: input.issue_title,
 			body: input.body,
+			choices: confirmation_options.block(input),
 			issue_url: undefined,
 			pr_url: undefined,
 		},
@@ -463,4 +480,4 @@ const telegram_notify = {
 }
 
 export { telegram_notify, build_text, TASK_DEFINITIONS, telegram_environment_schema }
-export type { TelegramSendInput, TelegramTaskType }
+export type { ConfirmInput, TelegramSendInput, TelegramTaskType }

package/scripts/notify/telegram-test-logic.ts

@@ -1,4 +1,5 @@
 import { cli_body } from '#scripts/josh/cli-body'
+import { confirmation_options } from './confirmation-options'
 import type { TelegramSendInput, TelegramTaskType } from './telegram-notify'
 
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -10,6 +11,8 @@ interface CliValues {
 	'body-file'?: string
 	'issue-url'?: string
 	'pr-url'?: string
+	recommended?: string
+	alternative?: Array<string>
 }
 /* eslint-enable @typescript-eslint/naming-convention */
 
@@ -67,12 +70,41 @@ function normalize_body(values: CliValues): string | undefined {
 	})
 }
 
+// **A confirmation without a recommended choice is refused, not sent**: the person it reaches is
+// off-screen, and a stop that names no choice leaves them to reconstruct one. `--alternative` may be
+// absent — a stop with one way forward says so — so only `--recommended` is required.
+function require_recommended(values: CliValues): string {
+	const recommended = values.recommended?.trim() ?? ''
+
+	if (recommended.length === 0) {
+		throw new Error('--task-type confirmation needs --recommended "<the recommended choice>".')
+	}
+
+	return recommended
+}
+
+function given_alternatives(values: CliValues): Array<string> {
+	return (values.alternative ?? []).filter((alternative) => alternative.trim().length > 0)
+}
+
+function build_choices(values: CliValues, task_type: TelegramTaskType): string | undefined {
+	if (task_type !== 'confirmation') return undefined
+
+	return confirmation_options.block({
+		recommended: require_recommended(values),
+		alternatives: given_alternatives(values),
+	})
+}
+
 function build_input(input: { values: CliValues; context: ResolvedContext }): TelegramSendInput {
+	const task_type = parse_task_type(input.values['task-type'])
+
 	return {
-		task_type: parse_task_type(input.values['task-type']),
+		task_type,
 		repo_name: coalesce(input.values['repo-name'], input.context.repo_name),
 		issue_title: coalesce(input.values['issue-title'], input.context.issue_title),
 		body: normalize_body(input.values),
+		choices: build_choices(input.values, task_type),
 		issue_url: input.values['issue-url'],
 		pr_url: input.values['pr-url'],
 	}

package/scripts/notify/telegram-test.ts

@@ -14,10 +14,10 @@ const REPO_NAME_SEPARATOR = '/'
 const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
 const USAGE =
-	'Usage: josh notify [--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]'
+	'Usage: josh notify [--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>] [--recommended <text>] [--alternative <text>]...'
 
 // The free-text values a caller writes, often opening with a Markdown `-` bullet.
-const FREE_TEXT_FLAGS = ['--body', '--issue-title']
+const FREE_TEXT_FLAGS = ['--body', '--issue-title', '--recommended', '--alternative']
 
 const OPTIONS = {
 	'task-type': { type: 'string' },
@@ -27,6 +27,8 @@ const OPTIONS = {
 	'body-file': { type: 'string' },
 	'issue-url': { type: 'string' },
 	'pr-url': { type: 'string' },
+	recommended: { type: 'string' },
+	alternative: { type: 'string', multiple: true },
 } as const
 
 // `undefined` for a line nobody can read — an unknown flag, or a flag given no value.

package/scripts/observations/observation-ledger-migrate.ts

@@ -8,6 +8,7 @@ import {
 	rmSync,
 } from 'node:fs'
 import path from 'node:path'
+import { process_identity } from '#scripts/josh/process-identity'
 import { file_reader } from '#scripts/lib/read-file'
 import {
 	LEDGER_FILE_EXTENSION,
@@ -38,8 +39,6 @@ import { observation_ledger_line } from './observation-ledger-line'
 // migration with no await point cannot be interleaved with another write in the same process.
 
 const NEWLINE = '\n'
-const NO_SIGNAL = 0
-const NO_SUCH_PROCESS = 'ESRCH'
 
 function claim_path(legacy: string): string {
 	return `${legacy}.${String(process.pid)}${MIGRATION_CLAIM_SUFFIX}`
@@ -55,18 +54,6 @@ function claim(from: string, to: string): boolean {
 	}
 }
 
-// Only `ESRCH` means the process is gone; `EPERM` means it runs under another user, and its claim is
-// still its own.
-function is_alive(pid: number): boolean {
-	try {
-		process.kill(pid, NO_SIGNAL)
-
-		return true
-	} catch (error) {
-		return (error as NodeJS.ErrnoException).code !== NO_SUCH_PROCESS
-	}
-}
-
 // A claim is named `<old ledger>.<pid>.migrating`, so the pid is what sits between the two.
 function is_stale_claim(name: string, legacy_name: string): boolean {
 	const prefix = `${legacy_name}.`
@@ -75,7 +62,8 @@ function is_stale_claim(name: string, legacy_name: string): boolean {
 
 	const pid = Number(name.slice(prefix.length, -MIGRATION_CLAIM_SUFFIX.length))
 
-	return Number.isSafeInteger(pid) && !is_alive(pid)
+	// A process under another user still holds its claim (`process_identity.is_present_pid`).
+	return Number.isSafeInteger(pid) && !process_identity.is_present_pid(pid)
 }
 
 function stale_claims(legacy: string): ReadonlyArray<string> {