@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/auth/claude-token-output.ts

@@ -0,0 +1,78 @@
+import { stripVTControlCharacters } from 'node:util'
+
+// What `claude setup-token` printed, split into the token and the text that may be shown: the token
+// is replaced, so it reaches neither the screen nor a log.
+
+const REDACTED = '[REDACTED]'
+const TOKEN_START = 'sk-ant-oat'
+const TOKEN_PATTERN = /sk-ant-oat\d+-[\w-]+/u
+const EVERY_TOKEN_PATTERN = new RegExp(TOKEN_PATTERN.source, 'gu')
+// A narrow terminal wraps the token onto lines of its own characters alone, so a continuation is a
+// whole such line and the prose after the token never joins it.
+const CONTINUATION_PATTERN = /^[\w-]+$/u
+const LINE_BREAK_PATTERN = /\r?\n/u
+
+interface Captured {
+	token: string | undefined
+	shown: string
+}
+
+// A line that starts a token is another copy of it, never the tail of the one before.
+function is_continuation(line: string): boolean {
+	return CONTINUATION_PATTERN.test(line) && !line.startsWith(TOKEN_START)
+}
+
+function continuation(lines: ReadonlyArray<string>): Array<string> {
+	const length = lines.findIndex((line) => !is_continuation(line.trim()))
+
+	return (length === -1 ? lines : lines.slice(0, length)).map((line) => line.trim())
+}
+
+// Every copy of the token is replaced, its wrapped tail with it: Ink may draw it in more than one frame.
+function redact(lines: ReadonlyArray<string>): Array<string> {
+	const start = lines.findIndex((line) => TOKEN_PATTERN.test(line))
+
+	if (start === -1) return [...lines]
+
+	const [head = '', ...rest] = lines.slice(start)
+	const remaining = rest.slice(continuation(rest).length)
+
+	return [
+		...lines.slice(0, start),
+		head.replaceAll(EVERY_TOKEN_PATTERN, () => REDACTED),
+		...redact(remaining),
+	]
+}
+
+function capture(output: string): Captured {
+	const lines = stripVTControlCharacters(output).split(LINE_BREAK_PATTERN)
+	const start = lines.findIndex((line) => TOKEN_PATTERN.test(line))
+	const head = lines[start]
+	const shown = redact(lines).join('\n')
+
+	if (head === undefined) return { token: undefined, shown }
+
+	const token = [TOKEN_PATTERN.exec(head)?.[0], ...continuation(lines.slice(start + 1))].join('')
+
+	return { token, shown }
+}
+
+// How much of the output so far may be shown as it arrives — the sign-in URL and any prompt come
+// before the token: everything before the token, less a tail that could be the start of one.
+function live_length(output: string): number {
+	const start = output.indexOf(TOKEN_START)
+
+	if (start !== -1) return start
+
+	const prefixes = Array.from({ length: TOKEN_START.length }, (_, index) =>
+		TOKEN_START.slice(0, index + 1),
+	)
+	const held = prefixes.findLast((prefix) => output.endsWith(prefix))
+
+	return output.length - (held?.length ?? 0)
+}
+
+const claude_token_output = { capture, live_length }
+
+export { claude_token_output }
+export type { Captured }

package/scripts/auth/claude-token.ts

@@ -0,0 +1,68 @@
+import { execaSync } from 'execa'
+
+// Where the Claude Code token of `josh fresh:run` lives on the host: the macOS keychain item
+// `josh auth:setup` writes, or — on a machine without a keychain — `CLAUDE_CODE_OAUTH_TOKEN` in the
+// environment. No shell profile is read or written, so no other Claude Code on the host changes how
+// it signs in.
+
+const VARIABLE = 'CLAUDE_CODE_OAUTH_TOKEN'
+const SERVICE = 'josh-claude-code-oauth-token'
+const ACCOUNT = 'josh'
+const SECURITY = 'security'
+const SECURITY_TIMEOUT_MS = 10_000
+const FIND = 'find-generic-password'
+const ITEM_ARGUMENTS: ReadonlyArray<string> = ['-s', SERVICE, '-a', ACCOUNT]
+// The modification date of the item, `"mdat"<timedate>=0x… "20261014071518Z\000"`, in UTC.
+const SAVED_DATE_PATTERN = /"mdat"<timedate>=\S+\s+"(\d{4})(\d{2})(\d{2})/u
+
+function security(arguments_: ReadonlyArray<string>, input = ''): string | undefined {
+	try {
+		const { stdout } = execaSync(SECURITY, [...arguments_], { input, timeout: SECURITY_TIMEOUT_MS })
+
+		return stdout
+	} catch {
+		return undefined
+	}
+}
+
+function non_empty(value: string | undefined): string | undefined {
+	const trimmed = value?.trim()
+
+	return trimmed === undefined || trimmed === '' ? undefined : trimmed
+}
+
+function from_keychain(): string | undefined {
+	return non_empty(security([FIND, ...ITEM_ARGUMENTS, '-w']))
+}
+
+// The keychain first, then the environment; `undefined` when neither holds a token.
+function read(): string | undefined {
+	return from_keychain() ?? non_empty(process.env[VARIABLE])
+}
+
+// `security -i` reads its command from stdin, so the token is in no argument list `ps` could show.
+// The item is read back, because the interactive mode exits 0 whether or not the command succeeded.
+function save(token: string): boolean {
+	security(['-i'], `add-generic-password -U ${ITEM_ARGUMENTS.join(' ')} -w "${token}"\n`)
+
+	return from_keychain() === token
+}
+
+// The day the item was last written, `YYYY-MM-DD`; `undefined` when there is none.
+function saved_date(): string | undefined {
+	const attributes = security([FIND, ...ITEM_ARGUMENTS])
+	const match = attributes === undefined ? undefined : SAVED_DATE_PATTERN.exec(attributes)
+
+	return match?.slice(1).join('-')
+}
+
+// Whether `security` answers at all, asked before a sign-in whose token would have nowhere to go.
+function has_keychain(): boolean {
+	return security(['list-keychains']) !== undefined
+}
+
+const SETUP_HINT = 'Run `pnpm josh auth:setup` to save one.'
+
+const claude_token = { read, save, saved_date, has_keychain, VARIABLE, SETUP_HINT }
+
+export { claude_token }

package/scripts/backlog/backlog-drive-epic.ts

@@ -1,3 +1,4 @@
+import { epic_triage } from '#scripts/epic/epic-triage'
 import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
@@ -12,7 +13,12 @@ import { backlog_offer } from './backlog-offer'
 // is runnable, without `run:add` and without waking a parent session.
 //
 // **Only what needs a person is handed back.** `stop` means every child left waits on a person, which a
-// judgment session reads. A failed `epic:next` is either a network blip or a broken graph (a cycle, an
+// judgment session reads. `triage` means a child carries neither `run:solo` nor `run:lane`, so
+// `epic:next --lanes` offers nothing until a session judges it — it exits 0 and repeats on every pass,
+// so waiting on it would never end. It is handed back under its own word, as the pool path's is, never
+// as `epic #N`: that verdict sends the session to run the epic's children, and the single-child
+// `epic:next` it asks there is not triage-gated, so it would launch the untriaged child instead of
+// labelling it. A failed `epic:next` is either a network blip or a broken graph (a cycle, an
 // undeclared order, an unreadable child), and its exit code does not tell them apart — so a failure is
 // a `wait` that retries on the next pass, and `backlog:offer`'s consecutive-retry limit of them hands the
 // epic back too, rather than waiting out the idle budget on an anomaly nobody is shown.
@@ -21,6 +27,7 @@ const NO_RETRIES = 0
 const SUCCESS_EXIT_CODE = 0
 const FIRST_LINE = 0
 const WAIT: OfferRead = { verdict: 'wait', issues: [], retries: NO_RETRIES }
+const TRIAGE: OfferRead = { ...WAIT, verdict: epic_triage.TRIAGE_VERDICT }
 
 // `--lanes` lists every child a free lane could take, so one the loop already knows about is passed
 // over rather than standing in front of the rest. `undefined` is an answer that could not be read.
@@ -53,22 +60,31 @@ function child_offer(children: ReadonlyArray<string>, state: DriveState): OfferR
 	return child === undefined ? WAIT : { verdict: 'run', issues: [child], retries: NO_RETRIES }
 }
 
+// The answers only a judgment session can move.
+function judgment_offer(epic: string, token: string): OfferRead | undefined {
+	if (token === 'stop') return handed_back(epic)
+
+	return token === epic_triage.TRIAGE_VERDICT ? TRIAGE : undefined
+}
+
 async function answered_offer(
 	epic: string,
 	answers: ReadonlyArray<string>,
 	state: DriveState,
 	owner: string,
 ): Promise<OfferRead> {
-	const token = answers[FIRST_LINE]
+	const token = answers[FIRST_LINE] ?? ''
 
-	if (token !== undefined && issue_number_shape.ISSUE_NUMBER_PATTERN.test(token)) {
-		return child_offer(answers, state)
-	}
-
-	if (token === 'stop') return handed_back(epic)
+	if (issue_number_shape.ISSUE_NUMBER_PATTERN.test(token)) return child_offer(answers, state)
+	const judgment = judgment_offer(epic, token)
+	if (judgment !== undefined) return judgment
 
 	if (token === 'complete') {
-		await backlog_drive_named.mark_done(epic, { outcome: 'merged', code: 0, token: 'none' }, owner)
+		await backlog_drive_named.mark_done(
+			epic,
+			{ outcome: 'merged', code: 0, token: 'none', is_offer: true },
+			owner,
+		)
 	}
 
 	return WAIT

package/scripts/backlog/backlog-drive-launch.ts

@@ -33,6 +33,9 @@ async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind
 
 	const outcome = await lane_launch_cli.launch_lane({ issue, stash: await latest_stash() })
 
+	// A refusal the driver waits out writes nothing else, so the lane's stage is ended here.
+	if (outcome.kind !== 'launched') await run_event_setup.emit(run_event_setup.STAGE.NO_CHILD)
+
 	return outcome.kind
 }
 

package/scripts/backlog/backlog-drive-named-offer.ts

@@ -10,6 +10,7 @@ import { backlog_budget } from './backlog-budget'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_epic } from './backlog-drive-epic'
 import { backlog_drive_named } from './backlog-drive-named'
+import { backlog_drive_unread } from './backlog-drive-unread'
 
 interface NamedContext {
 	is_only: boolean
@@ -67,12 +68,16 @@ async function classify(
 ): Promise<OfferRead> {
 	const result = await issue_state_cli.read_issue(issue)
 
-	if (result.kind !== 'state') return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
+	if (result.kind !== 'state') return backlog_drive_unread.offer(issue, result, state.retries)
 
 	const outcome = settled_outcome(result.state)
 
 	if (outcome !== undefined) {
-		await backlog_drive_named.mark_done(issue, { outcome, code: 0, token: 'none' }, owner)
+		await backlog_drive_named.mark_done(
+			issue,
+			{ outcome, code: 0, token: 'none', is_offer: true },
+			owner,
+		)
 
 		return { verdict: 'wait', issues: [], retries: NO_RETRIES }
 	}

package/scripts/backlog/backlog-drive-named.ts

@@ -55,7 +55,9 @@ function is_done(result: MergeResult): boolean {
 		return result.code === 0 && result.token !== MERGE_TOKEN.BUSY
 	}
 
-	return result.outcome === 'failed' && result.code === 0 && result.token !== MERGE_TOKEN.STOP
+	return (
+		result.outcome === 'failed' && result.code === 0 && !run_merge_token.is_control_stop(result)
+	)
 }
 
 function can_mark(carry: RunCarry, issue: string, owner: string): boolean {
@@ -125,7 +127,7 @@ async function reconcile(
 		const outcome = parked.has(issue) ? 'parked' : 'merged'
 
 		// eslint-disable-next-line no-await-in-loop -- each mark rewrites the same carry file
-		await mark_done(String(issue), { outcome, code: 0, token: 'none' }, owner)
+		await mark_done(String(issue), { outcome, code: 0, token: 'none', is_offer: true }, owner)
 	}
 }
 

package/scripts/backlog/backlog-drive-unread.ts

@@ -0,0 +1,56 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import type { StateRead } from '#scripts/issue/issue-state-cli'
+import type { OfferRead } from './backlog-drive'
+import { backlog_offer } from './backlog-offer'
+
+// **A named issue whose state did not read is asked again before a session hears of it.** The read is
+// one `gh` request, and a dropped connection fails it for a moment and no longer: handing that to a
+// session costs a wake that can only cut and hand the loop back. So the failure is a `wait` that reads
+// again on the next pass — the driver keeps collecting children meanwhile — and `backlog:offer`'s
+// consecutive-retry limit bounds it, the count `backlog-drive-epic.ts` advances for a failed `epic:next`.
+//
+// **What is handed back is `offer`, with the issue and the reason on stderr.** That is the row a session
+// already reads for an offer that produced nothing to start: report what stderr printed, pick no issue
+// by hand. A number that resolves to nothing is an answer rather than a gap, so it is not asked again.
+
+type UnreadState = Exclude<StateRead, { kind: 'state' }>
+
+const NO_RETRIES = 0
+// The loop's own word for an offer it could not use (`backlog-drive.ts` → `ask_offer`).
+const HANDED_BACK = 'offer'
+const UNKNOWN_REASON = 'unknown reason'
+
+function cause_of(read: UnreadState): string {
+	if (read.kind === 'missing') return 'the number does not resolve'
+	const status = read.status === undefined ? [] : [`status ${String(read.status)}`]
+
+	return [read.reason ?? UNKNOWN_REASON, ...status].join(', ')
+}
+
+function note_of(issue: string, read: UnreadState): string {
+	return `The state of named issue ${issue_cite.plain(issue)} could not be read (${cause_of(read)})`
+}
+
+function handed_back(note: string): OfferRead {
+	console.error(note)
+
+	return { verdict: HANDED_BACK, issues: [], retries: NO_RETRIES }
+}
+
+// `retries` is the count of consecutive failed offers before this one. A named epic's failed
+// `epic:next` advances it too, so the note counts offers, never state reads.
+function offer(issue: string, read: UnreadState, retries: number): OfferRead {
+	const note = note_of(issue, read)
+	if (read.kind === 'missing') return handed_back(`${note}; check the number and the repository.`)
+	const failures = retries + 1
+
+	if (failures >= backlog_offer.RETRY_LIMIT) {
+		return handed_back(`${note}; the offer failed ${String(failures)} times in a row.`)
+	}
+
+	console.error(`${note}; reading it again.`)
+
+	return { verdict: 'wait', issues: [], retries: failures }
+}
+
+export const backlog_drive_unread = { HANDED_BACK, offer }

package/scripts/backlog/backlog-drive.ts

@@ -26,10 +26,14 @@ const RUN_VERDICT = 'run'
 const STOP_VERDICT = 'stop'
 // How the loop reads each `run:merge` token — keyed by the producer's own type, so a token added there
 // is a type error here until it is classified. `hand-back` ends the loop at once: a hand-off, a person's
-// stop, the environment down, a foreign owner, an unreadable state. `stop` — a parked backlog or the
-// failure guard — is the offer's `stop` reached through a merge: the child is collected, nothing more
-// starts, and the children still in flight are collected before the loop ends. `await` is a cut resumed
-// in place: the same lane is awaited again.
+// stop, the environment down, a foreign owner, an unreadable state. `stop` — the failure guard, or a
+// failed child left unparked — collects the child, starts nothing more, and collects the children still
+// in flight before the loop ends. `await` is a cut resumed in place: the same lane is awaited again.
+//
+// **The offer `run:merge` passes through is never read here** (joshuafolkken/kit#3781): its `stop` —
+// only person-waiting issues left — is spelled like the control one, and acting on it ended the run
+// without the idle watch. The loop asks `backlog:offer` on the next pass instead, so whether a parked
+// backlog waits or ends is `backlog:budget`'s alone, after a merge as after any other pass.
 type TokenHandling = 'hand-back' | 'stop' | 'await'
 const TOKEN_HANDLING: Readonly<Record<MergeToken, TokenHandling>> = {
 	[MERGE_TOKEN.OVER]: 'hand-back',
@@ -103,7 +107,7 @@ interface DriveEnd {
 	is_finish?: boolean | undefined
 }
 
-type Collected = Pick<MergeResult, 'token' | 'outcome'>
+type Collected = Pick<MergeResult, 'token' | 'outcome' | 'is_offer'>
 
 interface DrivePorts {
 	// Whether a child's process has confirmed-ended — `lane:await`'s re-confirmed check in production.
@@ -209,15 +213,19 @@ function collected_state(
 // One finished child: handed back on an immediate token, otherwise collected.
 async function collect(issue: string, state: DriveState, ports: DrivePorts): Promise<PassResult> {
 	const collected = await ports.merge(issue)
-	const { token } = collected
+	const { token, is_offer } = collected
 
 	// An empty first line is a `run:merge` that failed before printing one: never read as a collection.
+	// An offer's `retry` is `backlog:next`'s transport answer, left to the next `backlog:offer`.
 	if (token === '') return ended('merge', state, undefined, issue)
-	if (IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
+	if (!is_offer && IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
 
 	const next = collected_state(issue, collected, state, ports.now().toISOString())
 
-	return { kind: 'continue', state: token === MERGE_TOKEN.STOP ? merge_stopped(issue, next) : next }
+	return {
+		kind: 'continue',
+		state: run_merge_token.is_control_stop(collected) ? merge_stopped(issue, next) : next,
+	}
 }
 
 async function collect_finished(state: DriveState, ports: DrivePorts): Promise<PassResult> {

package/scripts/backlog/backlog-overlap.ts

@@ -78,9 +78,8 @@ interface SeparateContext {
 	repo: string
 }
 
-// The path each running lane declares, mapped to the issue that holds it.
-function running_claims(declared: Declared, read: BusyRead): Map<string, number> {
-	const holders = read.kind === 'busy' ? read.issues.map((issue) => issue.number) : []
+// The path each of `holders` declares, mapped to the issue that holds it.
+function claims_of(declared: Declared, holders: ReadonlyArray<number>): Map<string, number> {
 	const pairs = holders.flatMap((number) =>
 		[...(declared.get(number) ?? [])].map((path): [string, number] => [path, number]),
 	)
@@ -88,6 +87,10 @@ function running_claims(declared: Declared, read: BusyRead): Map<string, number>
 	return new Map(pairs)
 }
 
+function running_claims(declared: Declared, read: BusyRead): Map<string, number> {
+	return claims_of(declared, read.kind === 'busy' ? read.issues.map((issue) => issue.number) : [])
+}
+
 function paths_of(child: EpicChild, declared: Declared, repo: string): ReadonlySet<string> {
 	if (child.repo !== repo) return new Set()
 
@@ -113,6 +116,20 @@ function clash_of(
 	return clashes[0]
 }
 
+// The running issues a candidate is weighed against, and the repository they are in.
+interface Holding {
+	holders: ReadonlyArray<number>
+	repo: string
+}
+
+// The path `child` declares that one of the running `holders` already declares — the clash `separate`
+// withholds a candidate on, for a reader that names the running issues itself (`run:board`).
+function running_clash(child: EpicChild, declared: Declared, holding: Holding): Clash | undefined {
+	const claims = claims_of(declared, holding.holders)
+
+	return clash_of(claims, paths_of(child, declared, holding.repo))
+}
+
 function clash_note(child: EpicChild, clash: Clash): string {
 	const waiting = session_cite.issue(child.number, undefined, child.repo)
 	const holder = session_cite.issue(clash.holder, undefined, child.repo)
@@ -172,7 +189,7 @@ function separate(
 	return { offered: walk.offered, withheld, ...(notice !== undefined && { notice }) }
 }
 
-const backlog_overlap = { declared_of, declared_paths, separate }
+const backlog_overlap = { declared_of, declared_paths, running_clash, separate }
 
 export { backlog_overlap }
-export type { Declared }
+export type { Clash, Declared }

package/scripts/backlog/backlog-ready.ts

@@ -25,9 +25,7 @@ interface ReadyPorts {
 
 // The lanes in use: the open worktrees an interruption has not stranded. `josh lane:limit` prints it.
 async function live_lane_count(): Promise<number> {
-	const lanes = await lane_registry.list_lanes()
-
-	return lanes.filter((lane) => !lane.is_stranded).length
+	return lane_registry.live_count(await lane_registry.list_lanes())
 }
 
 async function free_under(limit: number): Promise<number> {

package/scripts/backlog/backlogrun-args.ts

@@ -9,8 +9,12 @@ import { run_invocation } from '#scripts/run/run-invocation'
 //
 // **A bare number is an issue.** A shell reads an unquoted `#3437` as a comment, so `3437` in the named
 // list is taken as `#3437`; a number after the first flag is that flag's value and is left alone.
+//
+// **`--stop` stands alone.** It stops the run rather than starting one, so beside an issue or any other
+// flag it is refused before anything is stopped — a mistyped start must never end a run.
 
 const AGENT_FLAG = '--agent'
+const STOP_FLAG = '--stop'
 const BACKLOG_COMMAND = 'backlogrun'
 const ISSUE_PREFIX = '#'
 const FLAG_PREFIX = '-'
@@ -26,7 +30,8 @@ interface BacklogrunArguments {
 	issues: ReadonlyArray<number>
 }
 
-type ArgumentsResult = { kind: 'args'; args: BacklogrunArguments } | { kind: 'refused' }
+type ArgumentsResult =
+	{ kind: 'args'; args: BacklogrunArguments } | { kind: 'stop' } | { kind: 'refused' }
 
 interface AgentSplit {
 	agent: string | undefined
@@ -56,7 +61,7 @@ function normalized(rest: ReadonlyArray<string>): Array<string> {
 	return [...rest.slice(0, split_at).map((token) => issue_token(token)), ...rest.slice(split_at)]
 }
 
-function parse(argv: ReadonlyArray<string>): ArgumentsResult {
+function parse_start(argv: ReadonlyArray<string>): ArgumentsResult {
 	const { agent, rest } = split_agent(argv)
 	const provider = agent === undefined ? undefined : AGENTS[agent]
 	const invocation = run_invocation.rebuild([BACKLOG_COMMAND, ...normalized(rest)].join(' '))
@@ -68,6 +73,12 @@ function parse(argv: ReadonlyArray<string>): ArgumentsResult {
 	return { kind: 'args', args: { provider, invocation, issues } }
 }
 
+function parse(argv: ReadonlyArray<string>): ArgumentsResult {
+	if (!argv.includes(STOP_FLAG)) return parse_start(argv)
+
+	return { kind: argv.length === 1 ? 'stop' : 'refused' }
+}
+
 const backlogrun_args = { parse }
 
 export type { BacklogrunArguments }