@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/josh/session-language-cli.ts

@@ -1,8 +1,5 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
 import { run_carry } from '#scripts/run/carry/run-carry'
-import { josh_environment_file } from './josh-environment-file'
 import { session_language, type Resolution } from './session-language'
 
 // `josh session:lang` — say, on stdout, which language this session writes in, so a
@@ -43,7 +40,8 @@ const LIVE_PORTS: LivePorts = {
 	is_running: backlogrun_launch.is_running,
 }
 
-// The file load happens in `main`, on the command path only; the resolver reads the environment.
+// The file load happens in `session-language-main.ts`, on the command path only; the resolver reads
+// the environment.
 // The line carries the value alone: what the language covers is `CLAUDE.md` → "Output language",
 // already in context every turn, so repeating it here only spent context on each prompt. The default
 // prints nothing — that resident line already names `ja`.
@@ -68,8 +66,7 @@ function prompt_lines(resolution: Resolution, is_live: boolean): Array<string> {
 	return [format_line(resolution), is_live ? BOARD_LINE : ''].filter((line) => line !== '')
 }
 
-async function main(): Promise<void> {
-	josh_environment_file.load_environment_file()
+async function print_prompt_lines(): Promise<void> {
 	const lines = prompt_lines(resolve_session_lang(), await is_run_live())
 
 	for (const line of lines) console.info(line)
@@ -81,11 +78,10 @@ const session_language_cli = {
 	ENV_KEY,
 	format_line,
 	is_run_live,
+	print_prompt_lines,
 	prompt_lines,
 	resolve_session_lang,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
 export type { LivePorts }
 export { session_language_cli }

package/scripts/josh/session-language-main.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { josh_environment_file } from './josh-environment-file'
+import { session_language_cli } from './session-language-cli'
+
+// The `josh session:lang` entry and the `session-lang` hook bundle, kept apart from
+// `session-language-cli.ts` because `metrics-logic.ts` imports that one: a bundle is one file, so a
+// main guard there would fire for every command that carries it (joshuafolkken/kit#4186). `.env` is
+// read here, inside the guard, so a developer's own `.env` cannot decide what the unit tests see.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	josh_environment_file.load_environment_file()
+	await session_language_cli.print_prompt_lines()
+}

package/scripts/josh/session-language.ts

@@ -24,7 +24,12 @@ function resolve_session_lang(): Resolution {
 	return { lang: DEFAULT_SESSION_LANG, is_default: true }
 }
 
-const session_language = { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang }
+// `ja` and any regional form of it (`ja-JP`) is Japanese; every other language is the English fallback.
+function is_japanese(lang: string): boolean {
+	return lang.toLowerCase().startsWith(DEFAULT_SESSION_LANG)
+}
+
+const session_language = { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang, is_japanese }
 
 export type { Resolution }
 export { session_language }

package/scripts/josh/shared-cache.ts

@@ -0,0 +1,90 @@
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { stamp_file } from './stamp-file'
+
+// An answer one josh process read from GitHub, kept for the next process to reuse while it is fresh
+// (joshuafolkken/kit#4550).
+//
+// **Keyed to the repository's common git directory, so every work tree shares one record.** A
+// backlogrun asks the same question from its drive, its arrival probe and every lane at once; keying on
+// `PROJECT_ROOT` would give each work tree its own copy and each would read GitHub again.
+//
+// One record per slot: a different `key` replaces it rather than accumulating beside it, so the temp
+// directory holds at most one file per slot however many keys a run walks through.
+
+interface CacheSlot {
+	prefix: string
+	ttl_ms: number
+}
+
+const record_schema = z.object({
+	key: z.string(),
+	saved_at: z.number(),
+	value: z.unknown(),
+})
+
+function slot_path(slot: CacheSlot): string {
+	return stamp_file.stamp_path(slot.prefix, git_common_directory.repository() ?? PROJECT_ROOT)
+}
+
+function is_fresh(saved_at: number, slot: CacheSlot, now_ms: number): boolean {
+	return saved_at <= now_ms && now_ms - saved_at < slot.ttl_ms
+}
+
+function read_value(slot: CacheSlot, key: string, now_ms: number): unknown {
+	const raw = stamp_file.read_stamp_text(slot_path(slot))
+	const record = raw === undefined ? undefined : json_value.parse_with(raw, record_schema)
+
+	return record?.key === key && is_fresh(record.saved_at, slot, now_ms) ? record.value : undefined
+}
+
+// `undefined` is a miss: no record, another key's record, a stale one, or one that does not parse.
+function read<T>(
+	slot: CacheSlot,
+	key: string,
+	schema: z.ZodType<T>,
+	now_ms: number,
+): T | undefined {
+	const parsed = schema.safeParse(read_value(slot, key, now_ms))
+
+	return parsed.success ? parsed.data : undefined
+}
+
+// A write that fails leaves the next process to read GitHub itself — the answer this process already
+// has is still right, so the failure is not its caller's to handle.
+function write(slot: CacheSlot, key: string, value: unknown, now_ms: number): void {
+	try {
+		stamp_file.replace_stamp(slot_path(slot), { key, saved_at: now_ms, value })
+	} catch {
+		// The record is an optimization; a missing one costs one read.
+	}
+}
+
+// The cached answer for `key`, or `compute`'s — stored only when it is defined, so a failed read is
+// asked again by the next process rather than remembered for the whole TTL.
+async function remember<T>(
+	request: { slot: CacheSlot; key: string; schema: z.ZodType<T> },
+	compute: () => Promise<T | undefined>,
+	now_ms: number = Date.now(),
+): Promise<T | undefined> {
+	const cached = read(request.slot, request.key, request.schema, now_ms)
+
+	if (cached !== undefined) return cached
+
+	const value = await compute()
+
+	if (value !== undefined) write(request.slot, request.key, value, now_ms)
+
+	return value
+}
+
+function clear(slot: CacheSlot): void {
+	stamp_file.remove_stamp(slot_path(slot))
+}
+
+const shared_cache = { clear, read, remember, write }
+
+export { shared_cache }
+export type { CacheSlot }

package/scripts/josh/stamp-file.ts

@@ -1,12 +1,13 @@
-import { createHash, randomUUID } from 'node:crypto'
-import { lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { lstatSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { PACKAGE_DIR } from '#scripts/init/init-paths'
-import { PLATFORM_TEMP_ROOT } from './platform-temporary'
+import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
+import { atomic_write } from '#scripts/lib/atomic-write'
 
 // A small record one josh command writes and another reads, kept per checkout in the temp directory.
 //
-// Extracted from `scripts/eval/eval-stamp.ts` when `josh latest:scope` needed the same handoff.
+// Extracted from `tools/eval/eval-stamp.ts` when `josh latest:scope` needed the same handoff.
 // The mechanics below are not boilerplate — the symlink defense on the
 // write, the ownership check on the read, and the deterministic per-checkout path are each load
 // bearing — so a second copy of them is the clone `CLAUDE.md` prohibits. What differs between the
@@ -68,14 +69,22 @@ function account_key(): string {
 // **`suffix` is what the file is, not decoration.** Every record here was JSON until `josh gate`
 // needed to keep another tool's output verbatim, and a log named `.json`
 // tells every reader — a person, an editor, a `less` — that it is something it is not.
-function stamp_path(
+function stamp_name(
 	prefix: string,
 	root: string = PACKAGE_DIR,
 	suffix: string = STAMP_SUFFIX,
 ): string {
 	const key = digest(`${account_key()}${ACCOUNT_KEY_SEPARATOR}${root}`).slice(0, STAMP_KEY_LENGTH)
 
-	return path.join(PLATFORM_TEMP_ROOT, `${prefix}${key}${suffix}`)
+	return `${prefix}${key}${suffix}`
+}
+
+function stamp_path(
+	prefix: string,
+	root: string = PACKAGE_DIR,
+	suffix: string = STAMP_SUFFIX,
+): string {
+	return path.join(PLATFORM_TEMP_ROOT, stamp_name(prefix, root, suffix))
 }
 
 // **The write unlinks first, then creates exclusively.** `rmSync` removes a symlink rather than
@@ -121,8 +130,8 @@ function is_foreign_file(target: string): boolean {
 }
 
 // Mutable coordination state cannot disappear between an unlink and its replacement: a reader that
-// mistakes that gap for "no child" can start the same generation twice. The temporary file lives
-// beside the target, uses the same exclusive/symlink-safe create, and rename publishes it atomically.
+// mistakes that gap for "no child" can start the same generation twice. `atomic-write.ts` stages the
+// text beside the target with the same exclusive create and renames it over the target.
 // `rename` replaces the path itself rather than following a symlink planted there, so the write still
 // never lands somewhere else; a regular file another account owns is refused before it is replaced,
 // the same answer the unlink gives on a sticky temp directory.
@@ -131,16 +140,9 @@ function replace_text_stamp(target: string, text: string): string {
 		throw new Error(`refusing to replace another account's file: ${target}`)
 	}
 
-	const temporary = `${target}.${String(process.pid)}.${randomUUID()}`
-
-	try {
-		writeFileSync(temporary, text, { flag: STAMP_CREATE_FLAG, mode: STAMP_FILE_MODE })
-		renameSync(temporary, target)
+	atomic_write.replace_file(target, text, { mode: STAMP_FILE_MODE })
 
-		return target
-	} finally {
-		rmSync(temporary, { force: true })
-	}
+	return target
 }
 
 function replace_stamp(target: string, payload: unknown): string {
@@ -205,6 +207,7 @@ const stamp_file = {
 	replace_stamp,
 	replace_text_stamp,
 	remove_stamp,
+	stamp_name,
 	stamp_path,
 	write_stamp,
 	write_text_stamp,

package/scripts/lane/lane-adopt-cli.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_adopt, type Adoption } from './lane-adopt'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_state, type LaneRecords } from './lane-state'
+
+// `josh lane:adopt <issue> | --all` — write a state record for each open lane that lost its own
+// (`lane-adopt.ts`), one line per lane. A named lane left unknown exits non-zero; one already recorded
+// had nothing to adopt and exits zero. Under `--all` neither is a failure.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ALL_FLAG = '--all'
+const USAGE = 'Usage: josh lane:adopt <issue-number> | josh lane:adopt --all'
+
+async function named_lane(issue: string): Promise<Array<LaneInfo> | undefined> {
+	if (!issue_number_shape.is_issue_number(issue)) return undefined
+
+	const lane = await lane_registry.find_open_lane(issue)
+
+	return lane === undefined ? [] : [lane]
+}
+
+async function lanes_of(target: ReadonlyArray<string>): Promise<Array<LaneInfo> | undefined> {
+	const [issue, ...rest] = target
+
+	if (issue === undefined || rest.length > 0) return undefined
+
+	return issue === ALL_FLAG ? await lane_registry.list_lanes() : await named_lane(issue)
+}
+
+function outcome_text(adoption: Adoption): string {
+	if (adoption.kind === 'left') return `left unknown — ${adoption.reason}`
+	if (adoption.kind === 'kept') return `already recorded ${adoption.state}`
+
+	return `recorded open — ${lane_adopt.facts_text(adoption.facts)}`
+}
+
+// Adopt one lane, report it, and put an adoption on the run's event stream as a note, as
+// `backlog-drive-adopt.ts` does: a `lane-state` line would reset the once-per-episode paused-lanes
+// notice (`backlog-drive-paused.ts`) though no paused lane changed.
+async function settle(lane: LaneInfo, records: LaneRecords): Promise<Adoption> {
+	const adoption = await lane_adopt.adopt(lane, records)
+	const { ADOPT_COMMAND } = lane_adopt
+
+	console.info(`${ADOPT_COMMAND} ${session_cite.issue(lane.issue)}: ${outcome_text(adoption)}`)
+	if (adoption.kind !== 'adopted') return adoption
+
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.NOTE,
+		`${issue_cite.plain(lane.issue)} adopted by ${ADOPT_COMMAND}`,
+	)
+
+	return adoption
+}
+
+async function apply(lanes: ReadonlyArray<LaneInfo>, is_named: boolean): Promise<number> {
+	const records = await lane_state.read_states(lanes.map((lane) => lane.issue))
+	const adoptions = await Promise.all(lanes.map(async (lane) => await settle(lane, records)))
+
+	return is_named && adoptions.some((adoption) => adoption.kind === 'left')
+		? FAILURE_EXIT_CODE
+		: SUCCESS_EXIT_CODE
+}
+
+function report(message: string): number {
+	console.error(message)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const lanes = await lanes_of(argv)
+
+	if (lanes === undefined) return report(USAGE)
+
+	if (lanes.length === 0 && argv[0] !== ALL_FLAG) {
+		return report(`No open lane for ${session_cite.issue(argv[0] ?? '')}`)
+	}
+
+	return await apply(lanes, argv[0] !== ALL_FLAG)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_adopt_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_adopt_cli }

package/scripts/lane/lane-adopt.ts

@@ -0,0 +1,208 @@
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import {
+	git_gh_pr_read,
+	read_pull_or_listed,
+	read_pull as read_rest_pull,
+} from '#scripts/gh/git-gh-pr-read'
+import { git_gh_pr_rest } from '#scripts/gh/git-gh-pr-rest'
+import { git_command } from '#scripts/git/git-command'
+import { issue_state, type IssueState } from '#scripts/issue/issue-state'
+import { session_cite } from '#scripts/issue/session-cite'
+import { PROCESS_ALIVE, PROCESS_NONE, type ProcessTrace } from '#scripts/run/run-liveness'
+import { lane_await } from './lane-await'
+import type { LaneInfo } from './lane-registry'
+import { lane_spent } from './lane-spent'
+import {
+	lane_state,
+	type LaneChange,
+	type LaneRecords,
+	type LaneState,
+	type RecordOutcome,
+} from './lane-state'
+
+// `josh lane:adopt` (joshuafolkken/kit#4744): give a lane whose state record was lost — a restart, a
+// usage limit, an interrupted run — a record again, from what can be read off it, without touching its
+// branch, its work tree or its pull request.
+//
+// **Nothing is guessed.** A lane is written `open` — opened, no child working in it — only when its
+// process probe answers that no child is there and its work tree status, its unpushed commits, its pull
+// request and its issue all read; any one unread leaves it unknown, counted in use as before
+// (`backlog-occupied.ts`). `open` rather than `paused`: nobody suspended it, and a paused lane is one
+// `run:liveness` says not to recover. The next launch moves it to `running` (`lane-state.ts`), and
+// the next `backlogrun` takes the lane back while its issue still carries `in-progress`
+// (`backlog-drive-carried.ts`).
+
+const ADOPT_COMMAND = 'lane:adopt'
+const ISSUE_FIELDS = 'state,labels'
+const SEPARATOR = ' · '
+
+// The branch's pull request — the open one, else the newest (`git_gh_pr_rest.select_pull`) — with its
+// gh state, since a reopened lane's branch can still carry the merged one.
+interface Pull {
+	number: number
+	state: string
+}
+
+// A pull request read: the branch's pull request, or none.
+interface PullRead {
+	pull: Pull | undefined
+}
+
+interface LaneFacts {
+	branch: string
+	is_dirty: boolean
+	unpushed: number
+	pull: Pull | undefined
+	issue: IssueState
+}
+
+// Each read answers `undefined` when it could not be made.
+interface AdoptPorts {
+	process_trace: (issue: string) => ProcessTrace
+	tree_status: (directory: string) => Promise<string | undefined>
+	unpushed_commits: (branch: string) => Promise<number | undefined>
+	pull_request: (branch: string) => Promise<PullRead | undefined>
+	issue: (issue: string) => Promise<IssueState | undefined>
+	record: (change: LaneChange) => Promise<RecordOutcome>
+}
+
+type Adoption =
+	| { kind: 'adopted'; facts: LaneFacts }
+	| { kind: 'kept'; state: LaneState }
+	| { kind: 'left'; reason: string }
+
+async function read_tree_status(directory: string): Promise<string | undefined> {
+	try {
+		return await git_command.status(directory)
+	} catch {
+		return undefined
+	}
+}
+
+async function read_pull(branch: string): Promise<Pull | undefined> {
+	const number = await git_gh_pr_read.pr_get_number(branch)
+
+	if (number === undefined) return undefined
+
+	// The listing row carries `state` and `merged_at` too, so it stands in for a detail GitHub refuses
+	// as too many files changed.
+	const pull = await read_pull_or_listed(branch, number, read_rest_pull)
+	const state = git_gh_pr_rest.to_pr_state(pull)
+
+	return state === undefined ? undefined : { number, state }
+}
+
+// `undefined` when anything could not be read, including a pull request that exists but whose number
+// or state did not resolve.
+async function read_pull_request(branch: string): Promise<PullRead | undefined> {
+	try {
+		if (!(await git_gh_pr_read.pr_exists(branch))) return { pull: undefined }
+
+		const pull = await read_pull(branch)
+
+		return pull === undefined ? undefined : { pull }
+	} catch {
+		return undefined
+	}
+}
+
+async function read_issue(issue: string): Promise<IssueState | undefined> {
+	const json = await git_gh_issue_read.issue_view_json(issue, ISSUE_FIELDS)
+
+	return json === undefined ? undefined : issue_state.parse_issue_state(json)
+}
+
+async function record_open(change: LaneChange): Promise<RecordOutcome> {
+	return await lane_state.record_adopted(change)
+}
+
+const LIVE_PORTS: AdoptPorts = {
+	process_trace: lane_await.process_trace_default,
+	tree_status: read_tree_status,
+	unpushed_commits: lane_spent.read_unpushed_commits,
+	pull_request: read_pull_request,
+	issue: read_issue,
+	record: record_open,
+}
+
+function left(reason: string): Adoption {
+	return { kind: 'left', reason }
+}
+
+function process_reason(lane: LaneInfo, ports: AdoptPorts): string | undefined {
+	if (lane.is_stranded) return 'its work tree is gone'
+
+	const trace = ports.process_trace(lane.issue)
+
+	if (trace === PROCESS_ALIVE) return 'a child is working in it'
+
+	return trace === PROCESS_NONE ? undefined : 'its process probe did not answer'
+}
+
+// What each fact is called where it could not be read, in the order `facts_of` reads them.
+const FACT_NAMES = ['work tree status', 'unpushed commits', 'pull request', 'issue'] as const
+
+function unread_names(reads: ReadonlyArray<unknown>): string {
+	return FACT_NAMES.filter((_name, index) => reads[index] === undefined).join(', ')
+}
+
+async function facts_of(lane: LaneInfo, ports: AdoptPorts): Promise<LaneFacts | string> {
+	const reads = await Promise.all([
+		ports.tree_status(lane.directory),
+		ports.unpushed_commits(lane.branch),
+		ports.pull_request(lane.branch),
+		ports.issue(lane.issue),
+	])
+	const [status, unpushed, pull, issue] = reads
+
+	if (status === undefined || unpushed === undefined || pull === undefined || issue === undefined) {
+		return `could not read its ${unread_names(reads)}`
+	}
+
+	return { branch: lane.branch, is_dirty: status.trim() !== '', unpushed, pull: pull.pull, issue }
+}
+
+async function written(issue: string, facts: LaneFacts, ports: AdoptPorts): Promise<Adoption> {
+	const outcome = await ports.record({ issue, state: 'open', command: ADOPT_COMMAND })
+
+	return outcome.kind === 'written' ? { kind: 'adopted', facts } : left(outcome.reason)
+}
+
+/** Write an `open` record for `lane` when it has none and every fact about it reads. */
+async function adopt(
+	lane: LaneInfo,
+	records: LaneRecords,
+	ports: AdoptPorts = LIVE_PORTS,
+): Promise<Adoption> {
+	const recorded = records.get(lane.issue)
+
+	if (recorded !== undefined) return { kind: 'kept', state: recorded.state }
+
+	const blocked = process_reason(lane, ports)
+
+	if (blocked !== undefined) return left(blocked)
+
+	const facts = await facts_of(lane, ports)
+
+	return typeof facts === 'string' ? left(facts) : await written(lane.issue, facts, ports)
+}
+
+/** `branch 4744-lane · uncommitted changes · 2 unpushed commit(s) · PR [#4801](…) OPEN · issue OPEN (in-progress)` */
+function facts_text(facts: LaneFacts): string {
+	const labels = facts.issue.labels.length > 0 ? ` (${facts.issue.labels.join(', ')})` : ''
+
+	return [
+		`branch ${facts.branch}`,
+		facts.is_dirty ? 'uncommitted changes' : 'clean tree',
+		`${String(facts.unpushed)} unpushed commit(s)`,
+		facts.pull === undefined
+			? 'no PR'
+			: `PR ${session_cite.issue(facts.pull.number)} ${facts.pull.state}`,
+		`issue ${facts.issue.state}${labels}`,
+	].join(SEPARATOR)
+}
+
+const lane_adopt = { ADOPT_COMMAND, adopt, facts_text, read_pull_request }
+
+export { lane_adopt }
+export type { AdoptPorts, Adoption, LaneFacts }