@joshuafolkken/kit 1.1166.0 → 1.1178.0

package/scripts/run/run-ship-sync.ts

@@ -0,0 +1,114 @@
+import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
+import { is_merge_conflict } from '#scripts/gh/git-pr-checks-eval'
+import { git_command } from '#scripts/git/git-command'
+import { main_merge, type MergeOutcome } from '#scripts/git/main-merge'
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { error_text } from '#scripts/lib/error-message'
+import { run_ship_scoped } from './run-ship-scoped'
+
+// `josh ship` keeps the branch current with the default branch itself (joshuafolkken/kit#3221). The
+// lane merged it once, before the hand-off, and nothing merged it again while the pull request opened
+// and CI ran — so a default branch that moved meanwhile stopped the followup as `interrupted`, and a
+// relaunched session spent its first turns finding out that the cause was a conflict. Most of those
+// conflicts were not conflicts at all to git: merging the default branch again resolved them.
+//
+// So the merge happens twice more, mechanically: once before the commit (`sync_stage`), and once when
+// the followup fails on a pull request GitHub reports `DIRTY` (`followup_stage`). Only a merge git
+// itself cannot finish stops the ship, and it stops as `conflict`, naming the unmerged paths so the
+// resumed session goes straight to them.
+
+const should_forward_stderr = true
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+// A default branch that keeps moving under a pull request is merged again at most this often per ship;
+// past it the followup failure stands, so a busy default branch cannot hold a ship in a loop.
+const MAX_MERGE_RETRIES = 2
+const CONFLICT_NOTE = 'merging the default branch left unmerged paths:'
+const DEFERRED_PREFIX = 'merge deferred to the followup: '
+const CURRENT_SUFFIX = ' brings nothing in'
+
+// A stage's result, plus the paths a stopped merge left unmerged — carried to the stop prompt.
+interface StepResult extends JoshResult {
+	conflicts?: ReadonlyArray<string>
+}
+
+async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
+	return await josh_command.josh_run(argv, should_forward_stderr)
+}
+
+// A merge that could not even be attempted — a fetch that failed — reads as a refusal: nothing was
+// changed, and the followup still finds a real conflict on GitHub's side.
+async function merge_outcome(): Promise<MergeOutcome> {
+	try {
+		return await main_merge.merge()
+	} catch (error) {
+		return { kind: 'refused', message: error_text.message_of(error) }
+	}
+}
+
+function conflict_result(files: ReadonlyArray<string>, lead: string): StepResult {
+	const out = [lead, CONFLICT_NOTE, ...files].filter((line) => line !== '').join('\n')
+
+	return { code: FAILURE_EXIT_CODE, out, conflicts: files }
+}
+
+// A refusal does not stop the commit: the guard refuses only uncommitted work the default branch also
+// touches, and once that work is committed the followup merges again on a clean tree. A merge that changed
+// the tree meets the scoped pair again, so the commit never carries an unchecked merge.
+async function sync_stage(): Promise<StepResult> {
+	const outcome = await merge_outcome()
+
+	if (outcome.kind === 'conflict') return conflict_result(outcome.files, '')
+	if (outcome.kind === 'merged') return await run_ship_scoped.scoped_pair()
+
+	const out =
+		outcome.kind === 'current'
+			? `${outcome.branch}${CURRENT_SUFFIX}`
+			: `${DEFERRED_PREFIX}${outcome.message}`
+
+	return { code: SUCCESS_EXIT_CODE, out }
+}
+
+// Any read that fails answers "not conflicting": the followup failure then stands as it was.
+async function is_conflicting(): Promise<boolean> {
+	try {
+		const state = await git_gh_pr_read.pr_get_merge_state(await git_command.branch())
+
+		return is_merge_conflict(state?.merge_state_status)
+	} catch {
+		return false
+	}
+}
+
+// The result to stop on, or `undefined` once a clean merge is pushed and the followup can wait again.
+async function merge_again(title: string, failed: JoshResult): Promise<StepResult | undefined> {
+	if (!(await is_conflicting())) return failed
+
+	const outcome = await merge_outcome()
+
+	if (outcome.kind === 'conflict') return conflict_result(outcome.files, failed.out)
+	if (outcome.kind !== 'merged') return failed
+
+	const push = await josh(['git', '-y', '--skip-commit', '--skip-pr', title])
+
+	return push.code === SUCCESS_EXIT_CODE ? undefined : push
+}
+
+async function followup_stage(
+	title: string,
+	notify: ReadonlyArray<string>,
+	retries = 0,
+): Promise<StepResult> {
+	const result = await josh(['followup', title, ...notify])
+
+	if (result.code === SUCCESS_EXIT_CODE || retries >= MAX_MERGE_RETRIES) return result
+
+	const stop = await merge_again(title, result)
+
+	return stop ?? (await followup_stage(title, notify, retries + 1))
+}
+
+const run_ship_sync = { CONFLICT_NOTE, MAX_MERGE_RETRIES, followup_stage, sync_stage }
+
+export type { StepResult }
+export { run_ship_sync }

package/scripts/run/run-ship.ts

@@ -10,8 +10,10 @@
 // composite ends at the failure, and the report names the step that failed so the run reads only it.
 
 const PREFLIGHT_HEADER = '=== preflight ==='
+const PRE_DETACH_HEADER = '=== pre-detach checks ==='
 const REVIEW_HEADER = '=== review ==='
 const GATE_HEADER = '=== gate ==='
+const SYNC_HEADER = '=== sync origin/main ==='
 const COMMIT_HEADER = '=== commit/push/PR ==='
 const ROUND_TWO_HEADER = '=== round-2 review ==='
 const FOLLOWUP_HEADER = '=== followup ==='
@@ -29,6 +31,8 @@ interface ShipSection {
 	header: string
 	body: string
 	code: number
+	// The paths a stopped merge left unmerged (joshuafolkken/kit#3221), handed to the stop prompt.
+	conflicts?: ReadonlyArray<string>
 }
 
 function section_report(section: ShipSection): string {
@@ -65,10 +69,12 @@ const run_ship = {
 	FOLLOWUP_HEADER,
 	GATE_HEADER,
 	PREFLIGHT_HEADER,
+	PRE_DETACH_HEADER,
 	REPORT_HEADER,
 	REVIEW_HEADER,
 	ROUND_TWO_HEADER,
 	SKIPPED_BODY,
+	SYNC_HEADER,
 	STOPPED_PREFIX,
 	exit_code,
 	failed_section,

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

@@ -209,10 +209,16 @@ function log_hint(context: WakeContext): string {
 	return `The output of every session this supervisor started is in ${context.log_target}.`
 }
 
+// The log hint goes ahead of the note: the Telegram length limit cuts the tail, and a long failure note
+// (stdout tail plus stderr tail) would otherwise take the one line that says where to look next.
+function warning_body(stop: LoopStop, body: string, context: WakeContext): string {
+	return [body, log_hint(context), stop.note].filter(Boolean).join('\n')
+}
+
 async function warn_of_stop(stop: LoopStop, body: string, context: WakeContext): Promise<void> {
 	await telegram_notify.warn({
 		issue_title: WARNING_TITLE,
-		body: [body, stop.note, log_hint(context)].filter(Boolean).join('\n'),
+		body: warning_body(stop, body, context),
 		recovery: WARNING_RECOVERY,
 	})
 }
@@ -408,6 +414,7 @@ const run_wake_cli = {
 	USAGE,
 	run,
 	stop_body,
+	warning_body,
 }
 
 if (process.argv[1] === SCRIPT_PATH) await main(process.argv.slice(ARGV_OFFSET))

package/scripts/run/run-wake-driver.ts

@@ -8,6 +8,8 @@ const FIRST_LINE = 0
 const RESUME_PREFIX = 'resume: '
 const DETAILS_TAIL_LENGTH = 2048
 const TRUNCATION_MARK = '... '
+// The prefix `backlog-drive-cli.ts` gives the exception it catches.
+const ERROR_PREFIX = 'error '
 
 function driver_args(invocation: string): ReadonlyArray<string> | undefined {
 	const rebuilt = run_invocation.rebuild(invocation)
@@ -40,6 +42,11 @@ function details_tail(details: string): string {
 // **The hand-off names its next move, so the woken session never searches the procedure for it**
 // (joshuafolkken/kit#3156). Whatever the branch, the session acts on it and hands the loop back to the
 // supervisor with a cut; only a person's stop ends the run instead.
+//
+// **The claim comes first** (joshuafolkken/kit#3238). The supervisor hands the record off before the
+// wake, so until the session adopts it with `--resume` every count it writes — `--merged`, `--done`,
+// the closing `--cut` — is refused as advancing a handed-off budget, and the supervisor, seeing no
+// claim, ends the run as a failed wake.
 const HAND_BACK = 'then hand the loop back with pnpm josh run:carry --cut --owner "$PPID"'
 const NEXT_BY_VERDICT: ReadonlyArray<readonly [string, string]> = [
 	[
@@ -48,28 +55,38 @@ const NEXT_BY_VERDICT: ReadonlyArray<readonly [string, string]> = [
 	],
 	[
 		'merge human-review',
-		'the child stopped before its commit for a person; stop the run (needs-human-review.md)',
+		'stop the run, because the child stopped before its commit for a person (needs-human-review.md)',
 	],
 	['epic #', `follow backlogrun-steps.md → "Named issues run first, in order", ${HAND_BACK}`],
 ]
 const NEXT_DEFAULT = `act on the result by backlogrun-steps.md → "The loop", ${HAND_BACK}`
 
-function next_move(verdict: string): string {
+function next_move(verdict: string, invocation: string): string {
 	const found = NEXT_BY_VERDICT.find(([prefix]) => verdict.startsWith(prefix))
 
-	return `\nNext: ${found?.[1] ?? NEXT_DEFAULT}`
+	return `\nNext: first claim the carry record with ${run_carry.claim_command(invocation)}, then ${found?.[1] ?? NEXT_DEFAULT}`
 }
 
-function handoff_material(verdict: string, resume: string, details: string): string {
+function handoff_material(
+	verdict: string,
+	resume: string,
+	invocation: string,
+	details: string,
+): string {
 	const context = details === '' ? '' : `\nDetails: ${details_tail(details)}`
 	const epic = verdict.startsWith('epic #')
 		? '\nThe named item is an epic. Follow backlogrun-steps.md named epic procedure; do not launch the epic root as a fullrun child. After all children merge or park, record the root with pnpm josh run:carry --done <epic-number> --owner "$PPID" before continuing to the next named item.'
 		: ''
 
-	return `Driver result: ${verdict}\n${resume}${epic}${next_move(verdict)}${context}`
+	return `Driver result: ${verdict}\n${resume}${epic}${next_move(verdict, invocation)}${context}`
 }
 
-function driver_result(out: string, read: CarryRead, details = ''): DriveResult {
+function driver_result(
+	out: string,
+	read: CarryRead,
+	invocation: string,
+	details = '',
+): DriveResult {
 	const lines = out.split('\n')
 	const verdict = lines[FIRST_LINE]
 
@@ -80,13 +97,27 @@ function driver_result(out: string, read: CarryRead, details = ''): DriveResult
 		return { kind: 'failed', note: `backlog:drive returned an incomplete result: ${out}` }
 	}
 
-	return { kind: 'judgment', material: handoff_material(verdict, resume, details) }
+	return { kind: 'judgment', material: handoff_material(verdict, resume, invocation, details) }
 }
 
-function read_result(result: JoshResult, target: string): DriveResult {
-	if (result.code !== SUCCESS) return { kind: 'failed', note: result.err ?? result.out }
+// **The cause is the driver's stdout `error …` line, so it leads the note** (joshuafolkken/kit#3242).
+// `backlog:drive` prints an exception only to stdout, and its stderr is never empty — every command it
+// ran is there — so reading `err ?? out` dropped the one line that said why. The stderr follows as its
+// tail, for the same reason `details_tail` cuts a judgment's details.
+function cause_of(out: string): string {
+	const errors = out.split('\n').filter((line) => line.startsWith(ERROR_PREFIX))
 
-	return driver_result(result.out, run_carry.read_carry(target), result.err)
+	return errors.length > 0 ? errors.join('\n') : details_tail(out)
+}
+
+function failure_note(result: JoshResult): string {
+	return [cause_of(result.out), details_tail(result.err ?? '')].filter(Boolean).join('\n')
+}
+
+function read_result(result: JoshResult, target: string, invocation: string): DriveResult {
+	if (result.code !== SUCCESS) return { kind: 'failed', note: failure_note(result) }
+
+	return driver_result(result.out, run_carry.read_carry(target), invocation, result.err)
 }
 
 function claim_record(target: string, invocation: string): boolean {
@@ -110,7 +141,7 @@ async function drive(target: string): Promise<DriveResult> {
 
 	const result = await josh_command.josh_run(args, true)
 
-	return read_result(result, target)
+	return read_result(result, target, read.carry.invocation)
 }
 
 export const run_wake_driver = { drive, driver_args, driver_result }

package/scripts/test/test-red-logic.ts

@@ -1,4 +1,5 @@
 import { issue_bug_label } from '#scripts/issue/issue-bug-label'
+import { observation_ledger } from '#scripts/observations/observation-ledger'
 import { z } from 'zod'
 import { test_declared_logic } from './test-declared-logic'
 
@@ -11,7 +12,7 @@ import { test_declared_logic } from './test-declared-logic'
 // that test catches anything — the added and changed tests run against the merge-base, and at least one
 // of them has to fail there.
 
-type RedVerdict = 'red' | 'green' | 'no-test'
+type RedVerdict = 'red' | 'green' | 'no-test' | 'test-only'
 
 // The declaration a bug-fix Issue carries under its background heading, in the same slot as the
 // behavior-change declaration (`behavior-change-lint.ts`). Read from the declaration, never inferred,
@@ -33,6 +34,18 @@ function unit_test_files(paths: ReadonlyArray<string>): Array<string> {
 		.filter((path) => test_declared_logic.is_test_file(path) && path.endsWith(UNIT_TEST_SUFFIX))
 }
 
+// **A change whose every path is a test file has no pre-fix code to run against**
+// (joshuafolkken/kit#3214). The merge-base then runs the same code as HEAD, so its result equals HEAD's
+// and says nothing about the fix. Exempt paths do not count: a document-rule test reads `*.md` and
+// `prompts/` files, so a change to one of those is pre-fix content the test can be red against.
+// Observation ledger paths do not count either way (joshuafolkken/kit#3230): a run commits its own
+// ledger entry, and no test reads it as pre-fix content.
+function is_test_only(paths: ReadonlyArray<string>): boolean {
+	const counted = paths.filter((path) => !observation_ledger.is_ledger_path(path))
+
+	return counted.length > 0 && counted.every((path) => test_declared_logic.is_test_file(path))
+}
+
 // Vitest's JSON report carries one `testResults` entry per file it loaded — a file that failed to load
 // included — and none for a file its config excluded, so this is how many files actually ran. The
 // changed-path count cannot stand in for it: a file the merge-base config does not include runs nothing
@@ -58,7 +71,8 @@ function verdict_for(test_count: number, is_failed: boolean): RedVerdict {
 }
 
 // Only `green` on a declared bug fix is refused. `no-test` is already `josh test:declared`'s refusal
-// when a runtime file changed, and a declared fix that touched only docs has nothing to reproduce.
+// when a runtime file changed, a declared fix that touched only docs has nothing to reproduce, and a
+// `test-only` fix runs the same code on the merge-base as on HEAD.
 function is_refused(body: string, verdict: RedVerdict): boolean {
 	return verdict === 'green' && is_bug_fix(body)
 }
@@ -67,6 +81,7 @@ const test_red_logic = {
 	BUG_DECLARATION_LINE,
 	is_bug_fix,
 	is_refused,
+	is_test_only,
 	ran_file_count,
 	unit_test_files,
 	verdict_for,

package/scripts/test/test-red.ts

@@ -11,7 +11,7 @@ import { execa } from 'execa'
 import { test_red_logic, type RedVerdict } from './test-red-logic'
 
 // `josh test:red` — run the added and changed Vitest files against the pre-fix tree and print `red`,
-// `green` or `no-test` (joshuafolkken/kit#2448).
+// `green`, `no-test` or `test-only` (joshuafolkken/kit#2448).
 //
 // **The pre-fix tree is a detached worktree at the merge-base, never the caller's checkout.** The tests
 // are copied in from the working tree, so what runs is the new test against the old code, and the
@@ -26,7 +26,7 @@ const REPORT_NAME = 'report.json'
 const NODE_MODULES = 'node_modules'
 const VITEST_BIN = path.join(NODE_MODULES, '.bin', 'vitest')
 const USAGE =
-	'Usage: josh test:red — prints red / green / no-test for the changed tests on the merge-base'
+	'Usage: josh test:red — prints red / green / no-test / test-only for the changed tests on the merge-base'
 
 interface RedRun {
 	verdict: RedVerdict
@@ -34,9 +34,7 @@ interface RedRun {
 }
 
 // The changed Vitest files that still exist — a deleted test has nothing to run.
-async function changed_tests(): Promise<Array<string>> {
-	const paths = await changed_paths.read_changed_paths(false)
-
+function changed_tests(paths: ReadonlyArray<string>): Array<string> {
 	return test_red_logic.unit_test_files(paths).filter((file) => existsSync(file))
 }
 
@@ -126,12 +124,15 @@ async function verdict_on(base: string, files: ReadonlyArray<string>): Promise<R
 }
 
 // The verdict over the current checkout. No merge-base (not a repository, no default branch) reads as
-// `no-test` — there is no pre-fix tree to run against, and a guard fails open.
+// `no-test` — there is no pre-fix tree to run against, and a guard fails open. A change whose every path
+// is a test file is `test-only` without a run: the merge-base runs the same code as HEAD.
 async function run(): Promise<RedRun> {
 	const base = await change_base.resolved()
-	const files = await changed_tests()
+	const paths = await changed_paths.read_changed_paths(false)
+	const files = changed_tests(paths)
 
 	if (base === undefined || files.length === 0) return { verdict: 'no-test', files }
+	if (test_red_logic.is_test_only(paths)) return { verdict: 'test-only', files }
 
 	return { verdict: await verdict_on(base, files), files }
 }

package/scripts/time-runtime/time-transcript-line.ts

@@ -79,6 +79,13 @@ const ERROR_TEXT_LIMIT = 256
 // shared constant exists because each guard writes the literal in its own reason, so the one place a
 // refusal is *detected* names it here.
 const REFUSAL_MARKER = '⛔'
+// The label the harness puts in front of a PreToolUse hook's deny reason, naming the hook and the tool.
+const HOOK_ERROR_LABEL = /^PreToolUse:\S+ hook error: /u
+// A line that is one bare verdict token — `cut`, `busy`, `not-a-lane` — the single word a josh verdict
+// command prints on standard output (joshuafolkken/kit#3223). How many are kept bounds the field the
+// way `ERROR_TEXT_LIMIT` bounds `error_text`.
+const TOKEN_LINE = /^[a-z][a-z-]*$/u
+const TOKEN_LINE_LIMIT = 8
 
 interface Block {
 	type: string
@@ -111,6 +118,11 @@ interface Block {
 	// the parsed block rather than by re-scanning the body downstream. `''` where the result was not a
 	// `⛔` refusal, so a reader tells "no guard spoke" from "this guard spoke" without a second parse.
 	refusal_guard: string
+	// The bare-token lines of a result that did not fail, and `[]` for every other block
+	// (joshuafolkken/kit#3223). It obeys the same prohibition as `error_text` — what is kept is a few
+	// single words, never the body — and it exists so the verdict a josh command answered with
+	// (`run:cut`'s `cut`) is read from the parsed block rather than by searching the raw line.
+	token_lines: ReadonlyArray<string>
 	// The id the harness assigned to a command it took into the background, and `''` for every other
 	// block (joshuafolkken/kit#1662). It is the fourth field read off the body under the same
 	// prohibition as the three above — what is kept is the id, never the text it was read from — and
@@ -159,8 +171,12 @@ function block_names(
 // before the first `:` — `⛔ pre-gate cut: …` is `pre-gate cut`. A reason with no colon (a headline
 // like `⛔ scoped checks not green on this tree`) is taken whole. Reading the opening rather than
 // searching the body is what stops a result that merely quoted a reason being read as a refusal.
+//
+// **The harness writes the reason behind its own label** — `PreToolUse:Edit hook error: ⛔ …` — so that
+// label is stripped before the opening is read (joshuafolkken/kit#3223). Without it no live refusal
+// carried a guard: the fixtures wrote the bare `⛔` body and passed while every recorded one read `''`.
 function guard_from_refusal(text: string): string {
-	const trimmed = text.trimStart()
+	const trimmed = text.trimStart().replace(HOOK_ERROR_LABEL, '')
 	if (!trimmed.startsWith(REFUSAL_MARKER)) return ''
 
 	const headline = trimmed.slice(REFUSAL_MARKER.length).split('\n', 1)[0]?.trimStart() ?? ''
@@ -169,6 +185,14 @@ function guard_from_refusal(text: string): string {
 	return (colon === -1 ? headline : headline.slice(0, colon)).trim()
 }
 
+function token_lines_of(text: string): Array<string> {
+	return text
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => TOKEN_LINE.test(line))
+		.slice(0, TOKEN_LINE_LIMIT)
+}
+
 // **The body is flattened once and both readers are handed the text.** `result_text` is what turns a
 // content field that may be a string or a list of blocks into one string, and it is idempotent on a
 // string — so passing its own output back to `has_failure_line` reads exactly as passing the raw
@@ -185,6 +209,7 @@ function to_block(raw: z.infer<typeof BLOCK_SCHEMA>): Block {
 		followup_stages: time_followup_stage.read_stages(text),
 		error_text: is_error === true ? text.slice(0, ERROR_TEXT_LIMIT) : '',
 		refusal_guard: is_error === true ? guard_from_refusal(text) : '',
+		token_lines: is_error === true ? [] : token_lines_of(text),
 		background_id: time_background.launch_id(text),
 		agent_id: time_background.agent_launch_id(text),
 	}
@@ -248,6 +273,7 @@ function parse_line(line: string): TranscriptLine | undefined {
 const time_transcript_line = {
 	ERROR_TEXT_LIMIT,
 	NO_MESSAGE_ID,
+	TOKEN_LINE_LIMIT,
 	guard_from_refusal,
 	parse_line,
 }