@joshuafolkken/kit 1.1050.0 → 1.1128.0

package/scripts/rules/stop-rules.ts

@@ -45,6 +45,9 @@ interface StopContext {
 	hold_present: boolean
 	// `git status --porcelain` came back empty.
 	tree_clean: boolean
+	// That record carries a `prrun` stop mark (joshuafolkken/kit#3023): the run stopped at a green pull
+	// request and keeps the hold over a clean tree on purpose, so a person can look before it merges.
+	prrun_stopped: boolean
 	// A `confirmation` notify is on this run's transcript tail.
 	notified: boolean
 	// The turn's session-facing reply text.
@@ -75,6 +78,9 @@ interface StopContext {
 	// A backgrounded subagent this run launched has not finished — `lane_background.pending_agent_ids`
 	// (joshuafolkken/kit#2774). Apart from `background_pending`, since only a subagent is sure to end.
 	agent_pending: boolean
+	// This lane child handed its region to a running detached ship — `lane_handoff.is_handed_off`
+	// (joshuafolkken/kit#2962). The supervisor notifies on its own outcome, so nobody waits on this stop.
+	handed_off: boolean
 	// The resolved `JOSH_SESSION_LANG` — `session_language.resolve_session_lang` (joshuafolkken/kit#2470).
 	session_lang: string
 }
@@ -105,8 +111,8 @@ const HOLD_RELEASE_REASON =
 	'place, so the next run here runs `git switch main && git pull` believing the tree is free while ' +
 	'you hold it. `.claude/skills/workflow-commands/SKILL.md` → §2f: a stop that leaves the tree clean ' +
 	'releases the hold with `pnpm josh run:release <N>` (bare for a `new` entry). A `halfrun` ' +
-	'pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty — this ' +
-	'row is silent there. Release it, then end with a one-line confirmation that it was released — do ' +
+	'pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty, and a ' +
+	'`prrun` stop keeps it by its stop mark — this row is silent there. Release it, then end with a one-line confirmation that it was released — do ' +
 	'not repeat your previous reply.'
 
 // **A refusal that corrects rather than advises** (joshuafolkken/kit#2247). The bare `#N` is already
@@ -156,15 +162,18 @@ const HEADLESS_WAIT_MARKER = '⛔ headless parent:'
 const HEADLESS_REFUSAL_CAP = 3
 
 // The foreground waits as they appear in a transcript's tool-call input — the JSON `command` field, so
-// the refusal's own prose, which names the same commands, never matches.
-const HEADLESS_WAIT_CALLS = ['"command":"pnpm josh lane:await', '"command":"pnpm josh run:progress']
+// the refusal's own prose, which names the same commands, never matches. `run:progress --wait` is not
+// one (joshuafolkken/kit#3102): it streams its reports and runs until work arrives, so it is started in
+// the background, where it lives as long as the turn the foreground wait keeps open.
+const HEADLESS_WAIT_CALLS = ['"command":"pnpm josh lane:await']
 
 const HEADLESS_WAIT_BODY =
 	' this is a `claude -p` `backlogrun` parent (`JOSH_RUN_HEADLESS`) with lanes still ' +
 	'in flight, and ending this turn ends the process — its background waits are killed with it and the ' +
 	'lanes are left without a parent. Wait in the foreground instead: run `pnpm josh lane:await <N...>` ' +
-	'for the in-flight lanes (and `pnpm josh run:progress --wait` for the heartbeat) as foreground ' +
-	'commands within the tool timeout, act on what they report, and continue the loop. End the turn only ' +
+	'for the in-flight lanes as a foreground command within the tool timeout (with ' +
+	'`pnpm josh run:progress --wait` in the background for the heartbeat, which streams its reports ' +
+	'itself and lives while this turn does), act on what it reports, and continue the loop. End the turn only ' +
 	'after `pnpm josh run:carry --cut` or `--end` (`backlogrun-progress.md` → "The parent keeps no clock ' +
 	'of its own").'
 
@@ -232,8 +241,11 @@ function needs_filing(context: StopContext): boolean {
 // notify there says "nothing needed" and dilutes the ones that do. A backgrounded command does not
 // count: a dev server never ends, and a stop behind it would leave a person silently waiting. A lane
 // child never reaches this with a task running: `needs_background_wait` answers it first.
+//
+// **A lane handed to the detached ship stands them down too** (joshuafolkken/kit#2962): the hold now
+// belongs to the supervisor driving the merge, and the person hears from that supervisor's own notify.
 function is_held_idle(context: StopContext): boolean {
-	return context.hold_present && !context.agent_pending
+	return context.hold_present && !context.agent_pending && !context.handed_off
 }
 
 function needs_notify(context: StopContext): boolean {
@@ -241,7 +253,7 @@ function needs_notify(context: StopContext): boolean {
 }
 
 function needs_release(context: StopContext): boolean {
-	return is_held_idle(context) && context.tree_clean
+	return is_held_idle(context) && context.tree_clean && !context.prrun_stopped
 }
 
 function citation_reason(context: StopContext): string | undefined {
@@ -345,7 +357,6 @@ const stop_rules = {
 	STOP_NOTIFY_REASON,
 	SWITCH_ENV_KEY,
 	block_envelope,
-	block_reason,
 	build_language_reason,
 	count_headless_refusals,
 	is_enabled,

package/scripts/rules/tail-commands.ts

@@ -30,6 +30,6 @@ function prior_bash_commands(tail: string): ReadonlyArray<string> {
 	return tail.split('\n').flatMap((line) => bash_commands_of(line))
 }
 
-const tail_commands = { bash_commands_of, is_bash_use, prior_bash_commands }
+const tail_commands = { is_bash_use, prior_bash_commands }
 
 export { tail_commands }

package/scripts/rules/test-declared-commit.ts

@@ -46,6 +46,6 @@ const REASON =
 // reason above.
 const ROW = { id: 'test-declared', is_trigger: is_untested_commit, reason: REASON }
 
-const test_declared_commit = { REASON, ROW, is_untested_commit }
+const test_declared_commit = { REASON, ROW }
 
 export { test_declared_commit }

package/scripts/rules/third-party-write.ts

@@ -83,7 +83,6 @@ const ROW = {
 const third_party_write = {
 	ROW,
 	THIRD_PARTY_WRITE_REASON,
-	is_third_party_write_segment,
 	writes_third_party,
 }
 

package/scripts/rules/worktree-guard.ts

@@ -36,8 +36,8 @@ function is_worktree_checkout(args: ReadonlyArray<string>): boolean {
 }
 
 // `git restore <path>` discards working-tree changes. `--staged` / `-S` alone is an index restore —
-// that is the deny list's territory (`git restore --staged*` / `-S*`), so a pure index restore is not
-// refused twice. Anything touching the worktree (the default, or an explicit `--worktree` / `-W`) is.
+// that is the `index-mutation` row's (`index-guard.ts`), so a pure index restore is not claimed by two
+// rows. Anything touching the worktree (the default, or an explicit `--worktree` / `-W`) is this row's.
 const STAGED_LONG = '--staged'
 const STAGED_LETTER = 'S'
 const WORKTREE_LONG = '--worktree'
@@ -83,14 +83,33 @@ function is_unauthorized_stash(args: ReadonlyArray<string>): boolean {
 	return true
 }
 
+// `git clean` deletes untracked files, which no commit can bring back (joshuafolkken/kit#2983). It
+// refuses to act without a force (`clean.requireForce`), so a force — `--force`, or a cluster carrying
+// `f` — is what marks the destructive call; `git clean -n` is a dry run and passes.
+const CLEAN_SUBCOMMAND = 'clean'
+const FORCE_LONG = '--force'
+const FORCE_LETTER = 'f'
+
+function is_forced_clean(args: ReadonlyArray<string>): boolean {
+	return args.some(
+		(argument) => argument === FORCE_LONG || git_argv.short_cluster_has(argument, FORCE_LETTER),
+	)
+}
+
+// Each subcommand this row judges, with the predicate that reads its arguments.
+const JUDGED_SUBCOMMANDS: ReadonlyMap<string, (args: ReadonlyArray<string>) => boolean> = new Map([
+	[CHECKOUT_SUBCOMMAND, is_worktree_checkout],
+	[RESTORE_SUBCOMMAND, touches_worktree],
+	[CLEAN_SUBCOMMAND, is_forced_clean],
+	[STASH_SUBCOMMAND, is_unauthorized_stash],
+])
+
 function is_unauthorized_segment(segment: string): boolean {
 	const call = git_argv.parse(segment)
 
 	if (call === undefined) return false
-	if (call.subcommand === CHECKOUT_SUBCOMMAND) return is_worktree_checkout(call.args)
-	if (call.subcommand === RESTORE_SUBCOMMAND) return touches_worktree(call.args)
 
-	return call.subcommand === STASH_SUBCOMMAND && is_unauthorized_stash(call.args)
+	return JUDGED_SUBCOMMANDS.get(call.subcommand ?? '')?.(call.args) === true
 }
 
 function is_unauthorized_worktree_change(command: string): boolean {
@@ -101,8 +120,8 @@ function is_unauthorized_worktree_change(command: string): boolean {
 // and — for a stash — the message form that is allowed. `pnpm josh git` and `pnpm josh stash:pop` are
 // invisible to this trigger, so a run that uses them is never refused.
 const WORKTREE_MUTATION_REASON =
-	'⛔ unauthorized working-tree change: `git checkout -- <path>`, `git restore <path>` and an ' +
-	'unauthorized `git stash` mutate the working tree or the repository-wide stash every work tree ' +
+	'⛔ unauthorized working-tree change: `git checkout -- <path>`, `git restore <path>`, a forced ' +
+	'`git clean` and an unauthorized `git stash` discard work or mutate the repository-wide stash every work tree ' +
 	'shares, and none is on the `.claude/settings.json` deny list (`operating-rules.md`). Do not run ' +
 	'them on your own judgement. A commit goes through `pnpm josh git`; a stash pop goes through `pnpm ' +
 	'josh stash:pop "<message>"`, never a positional `git stash pop` a shared stack lets another lane ' +
@@ -121,9 +140,7 @@ const ROW = {
 const worktree_guard = {
 	ROW,
 	WORKTREE_MUTATION_REASON,
-	is_unauthorized_stash,
 	is_unauthorized_worktree_change,
-	is_worktree_checkout,
 	touches_worktree,
 }
 

package/scripts/run/run-carry-args.ts

@@ -76,17 +76,13 @@ type Request =
 const READ_REQUEST: Request = { kind: 'read' }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
-}
-
-function text_of(value: OptionValue): string | undefined {
-	return typeof value === 'string' ? value : undefined
+	return cli_flags.values_of(argv, OPTIONS)
 }
 
 // Absent is zero; present but not a count is `undefined`, which invalidates the whole invocation
 // rather than quietly counting nothing.
 function to_count(value: OptionValue): number | undefined {
-	const text = text_of(value)
+	const text = cli_flags.string_of(value)
 
 	if (text === undefined) return NO_INCREMENT
 
@@ -99,7 +95,7 @@ function to_count(value: OptionValue): number | undefined {
 // than a zero: there is no issue to record, which is a different fact from recording issue zero. A
 // present-but-malformed value invalidates the whole invocation, exactly as a bad `--merged` does.
 function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
-	const text = text_of(value)
+	const text = cli_flags.string_of(value)
 
 	if (text === undefined) return {}
 
@@ -165,7 +161,7 @@ function group_count(values: ParsedValues): number {
 // the record simply declares no owner and every standing record reads as not provably live, which
 // refuses rather than resumes.
 function to_owner(value: OptionValue): CarryOwner | undefined {
-	const text = text_of(value)
+	const text = cli_flags.string_of(value)
 
 	if (text === undefined) return run_carry.NO_OWNER
 
@@ -179,7 +175,7 @@ function to_owner(value: OptionValue): CarryOwner | undefined {
 // A non-empty `--summary`, or nothing. An empty string is nothing here, so it reads as absent and the
 // pairing check below refuses it against `--retrospective`.
 function summary_text(values: ParsedValues): string | undefined {
-	const summary = text_of(values.summary)
+	const summary = cli_flags.string_of(values.summary)
 
 	return summary === undefined || summary === '' ? undefined : summary
 }
@@ -220,17 +216,17 @@ function to_claim_request(
 }
 
 function to_other_request(values: ParsedValues, owner: CarryOwner): Request | undefined {
-	if (values.end === true) return { kind: 'end', stopped: text_of(values.stopped) }
+	if (values.end === true) return { kind: 'end', stopped: cli_flags.string_of(values.stopped) }
 
 	return has_count(values) ? to_count_request(values, owner) : READ_REQUEST
 }
 
 function to_named_request(values: ParsedValues, owner: CarryOwner): Request | undefined {
-	const begun = text_of(values.begin)
+	const begun = cli_flags.string_of(values.begin)
 
 	if (begun !== undefined) return to_claim_request(begun, owner, false)
 
-	const adopted = text_of(values.resume)
+	const adopted = cli_flags.string_of(values.resume)
 
 	if (adopted !== undefined) return to_claim_request(adopted, owner, true)
 

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

@@ -447,11 +447,9 @@ const run_carry_cli = {
 	RESUMED_VERDICT,
 	STANDING_VERDICT,
 	UNKNOWN_VERDICT,
-	UNREADABLE_VERDICT,
 	// Re-exported rather than restated: the usage line belongs to the half that parses, and a second
 	// copy of it here would drift from the flags it describes.
 	USAGE: run_carry_args.USAGE,
-	main,
 	run,
 }
 

package/scripts/run/run-carry-stash.ts

@@ -1,5 +1,5 @@
-import { git_stash } from '#scripts/git/git-stash'
-import { stash_orphans } from '#scripts/git/stash-orphans'
+import { git_stash } from '#scripts/git/stash/git-stash'
+import { stash_orphans } from '#scripts/git/stash/stash-orphans'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 

package/scripts/run/run-carry-streak.ts

@@ -107,7 +107,7 @@ function next_state(carry: StreakCarry, change: StreakChange, now: Date): Streak
 	}
 }
 
-const run_carry_streak = { OUTAGE_FOLD_WINDOW_MS, next_state }
+const run_carry_streak = { next_state }
 
 export type { StreakCarry, StreakChange, StreakState }
 export { run_carry_streak }

package/scripts/run/run-cut-args.ts

@@ -47,12 +47,7 @@ type Request =
 	| { kind: 'end' }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	return cli_flags.parse_or_undefined({
-		args: [...argv],
-		options: OPTIONS,
-		strict: true,
-		allowPositionals: true,
-	})
+	return cli_flags.arguments_of(argv, OPTIONS)
 }
 
 // The issue is the sole positional, and it must be a real issue number: a cut relaunches

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

@@ -45,8 +45,6 @@ const {
 	STALE_VERDICT,
 	SUCCESS_EXIT_CODE,
 	UNDER_THRESHOLD_VERDICT,
-	UNKNOWN_VERDICT,
-	UNREADABLE_VERDICT,
 	UNREADY_VERDICT,
 	refuse_unready,
 	report,
@@ -423,18 +421,13 @@ const run_cut_cli = {
 	FAILED_VERDICT,
 	FRESH_VERDICT,
 	HANDED_OFF_VERDICT,
-	INCOMPLETE_VERDICT,
 	NOT_A_LANE_VERDICT,
 	OVER_VERDICT,
 	RESUME_IMPL_VERDICT,
 	RESUME_VERDICT,
 	STALE_VERDICT,
 	UNDER_THRESHOLD_VERDICT,
-	UNKNOWN_VERDICT,
-	UNREADABLE_VERDICT,
 	UNREADY_VERDICT,
-	USAGE: run_cut_args.USAGE,
-	main,
 	run,
 }
 

package/scripts/run/run-cut.ts

@@ -1,10 +1,8 @@
-import { execFileSync } from 'node:child_process'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { backlog_budget } from '#scripts/backlog/backlog-budget'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
-import { git_utilities } from '#scripts/git/constants'
 import { git_command } from '#scripts/git/git-command'
-import { git_location_environment } from '#scripts/git/git-location-environment'
+import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { lane_child_invocation } from '#scripts/lane/lane-child-invocation'
 import { z } from 'zod'
@@ -60,14 +58,6 @@ const IMPLEMENTATION_CONTEXT_THRESHOLD = CONTEXT_CUT_THRESHOLD
 const CUT_MAX_AGE_MS = backlog_budget.WHOLE_RUN_BUDGET_MS
 const CUT_MAX_AGE_HOURS = backlog_budget.WHOLE_RUN_BUDGET_HOURS
 
-// The synchronous git read runs inside a `PreToolUse` hook, which holds the tool call for as long as
-// it takes; `rev-parse` takes no lock, so anything past a second is a fault rather than slow work.
-const GIT_READ_TIMEOUT_MS = 5000
-
-// The two lines `GIT_DIRECTORY_ARGUMENTS` prints, in order: the work tree's own git directory, then the
-// common one every lane of a repository shares. `git_directories` reads the same two asynchronously.
-const WORKTREE_DIRECTORY_INDEX = 0
-
 const END_COMMAND = 'pnpm josh run:cut --end'
 const READ_COMMAND = 'pnpm josh run:cut --json'
 
@@ -224,10 +214,10 @@ function read_cut(target: string, now: Date = new Date()): CutRead {
 
 // **The same read as `read_cut(cut_path(await worktree_directory()))`, taken synchronously**
 // (joshuafolkken/kit#1864). The pre-gate cut is enforced from a `PreToolUse` guard, and a guard
-// answers synchronously or not at all — so the one git call the path derivation needs is made here
-// with `git_command.GIT_DIRECTORY_ARGUMENTS`, the same argument list the asynchronous reader uses,
-// rather than a second spelling of it. Everything after the path is already shared: `cut_path` keys
-// the record and `classify` parses and expires it.
+// answers synchronously or not at all — so the one git call the path derivation needs is
+// `git_common_directory.own()`, the synchronous twin of the asynchronous reader, rather than a second
+// spelling of it. Everything after the path is already shared: `cut_path` keys the record and
+// `classify` parses and expires it.
 //
 // **A fault reads as "no cut was taken", and that direction is deliberate rather than fail-open.** A
 // checkout git cannot describe, a record that will not parse and an expired one all come back
@@ -235,47 +225,11 @@ function read_cut(target: string, now: Date = new Date()): CutRead {
 // The alternative errs the other way: a read fault would be taken for "already cut" and the guard
 // would go quiet on exactly the run it exists for. The cost of this direction is one refusal a lane
 // can answer by reissuing, since that row is delivered once per run.
-function git_directories_sync(cwd?: string): ReadonlyArray<string> {
-	try {
-		// The binary is resolved through `git_utilities` exactly as `git-spawn.ts` resolves it, so this
-		// call does not answer to whatever `PATH` happens to hold. It runs the binary directly with an
-		// argument array and no `shell` option, and both are internally controlled, never untrusted
-		// input.
-		const output = execFileSync(
-			git_utilities.get_git_command_for_spawn(),
-			[...git_command.GIT_DIRECTORY_ARGUMENTS],
-			// git's own diagnostics are discarded: a checkout it cannot describe is already the
-			// `undefined` below, and a hook that let `fatal: not a git repository` through would print it
-			// in front of a tool call that is about to be allowed.
-			// A `PreToolUse` hook holds the tool call while it runs, so the read is bounded rather than
-			// left to whatever git does.
-			// `cwd` is set only by `lane_cut_sync`, which reads another lane's record from the parent.
-			// With a `cwd`, the git location variables are cleared so it is what git answers for: a hook
-			// exports `GIT_DIR`, which beats `cwd` and would name the hook's checkout instead
-			// (joshuafolkken/kit#2515). Without one the environment is kept, so this read resolves the same
-			// checkout as the asynchronous `git_directories` that writes the record.
-			{
-				cwd,
-				env:
-					cwd === undefined
-						? process.env
-						: { ...process.env, ...git_location_environment.location_free_environment() },
-				encoding: 'utf8',
-				stdio: ['ignore', 'pipe', 'ignore'],
-				timeout: GIT_READ_TIMEOUT_MS,
-			},
-		) // NOSONAR
-
-		return output.split('\n').filter((line) => line !== '')
-	} catch {
-		return []
-	}
-}
-
+//
 // The work tree's own git directory (index 0), the same read `git_directories` makes asynchronously —
 // the record and the pre-gate guard both key on it.
 function worktree_git_directory_sync(): string | undefined {
-	return git_directories_sync()[WORKTREE_DIRECTORY_INDEX]
+	return git_common_directory.own()
 }
 
 // **The directory is injectable so a test never has to write to the live record.** Keyed to the work
@@ -297,7 +251,7 @@ function carried_cut_sync(
 // lane's own git directory, so the parent — standing in the main checkout — resolves that directory
 // from the lane's path rather than its own, and gets the record path back to mark it.
 function lane_cut_sync(lane_directory: string): { target: string; cut: RunCut } | undefined {
-	const directory = git_directories_sync(lane_directory)[WORKTREE_DIRECTORY_INDEX]
+	const directory = git_common_directory.own(lane_directory)
 
 	if (directory === undefined) return undefined
 

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

@@ -56,10 +56,6 @@ interface ParsedArguments {
 	values: ParsedValues
 }
 
-function read_arguments(argv: ReadonlyArray<string>): ParsedArguments | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, allowPositionals: true })
-}
-
 function is_valid(parsed: ParsedArguments): boolean {
 	return (
 		parsed.positionals.length === 1 &&
@@ -78,7 +74,7 @@ function to_request(parsed: ParsedArguments): EndingRequest {
 }
 
 function parse_request(argv: ReadonlyArray<string>): EndingRequest | undefined {
-	const parsed = read_arguments(argv)
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 
 	if (parsed === undefined || !is_valid(parsed)) return undefined
 
@@ -101,7 +97,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_ending_cli = { USAGE, main, parse_request, run }
+const run_ending_cli = { USAGE, parse_request, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/run/run-ending.ts

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs'
 import { agent_exit_record } from '#scripts/agent/agent-exit-record'
 import { api_outage } from '#scripts/agent/api-outage'
 import type { ClaudeResultEvent } from '#scripts/agent/claude-result-event'
-import { git_gh_issue_read } from '#scripts/git/git-gh-issue-read'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { issue_state } from '#scripts/issue/issue-state'
 import { run_cut } from './run-cut'
 import { run_hold } from './run-hold'
@@ -222,9 +222,6 @@ async function check(request: EndingRequest): Promise<EndingDecision> {
 const run_ending = {
 	check,
 	decide,
-	describe_exit,
-	read_child_closed,
-	read_cut_taken,
 	read_exit,
 }