@joshuafolkken/kit 1.1240.0 → 1.1370.0

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

@@ -1,20 +1,24 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { agent_session_role } from '#scripts/agent/agent-session-role'
 import { cost_cli } from '#scripts/cost-runtime/cost-cli'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { git_command } from '#scripts/git/git-command'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { session_cite } from '#scripts/issue/session-cite'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { openai_lane_supervisor } from '#scripts/lane/openai-lane-supervisor'
 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 { run_cli_fault } from '#scripts/run/run-cli-fault'
 import { run_cut, type CutState, type RunCut } from './run-cut'
 import { run_cut_args, type Request } from './run-cut-args'
 import { run_cut_handoff } from './run-cut-handoff'
 import { run_cut_report } from './run-cut-report'
 
 // `josh run:cut` — the record that lets a lane child end its process before the gate and a fresh one
-// resume from it (joshuafolkken/kit#1839). `run:cut <N>` writes the record and relaunches a fresh
+// resume from it. `run:cut <N>` writes the record and relaunches a fresh
 // `fullrun #<N>`; the fresh process runs `run:cut --resume <N>` at its entry, which verifies the tree
 // against the record and hands the run on to the gate. **Turning `argv` into a request is
 // `run-cut-args.ts`'s**; what is here acts on the record and relaunches.
@@ -25,6 +29,7 @@ import { run_cut_report } from './run-cut-report'
 // session.
 
 const ARGV_OFFSET = 2
+const COMMAND = 'run:cut'
 
 const {
 	BAD_HANDOFF_VERDICT,
@@ -50,20 +55,21 @@ const {
 	report,
 	report_bad_handoff,
 	report_busy,
+	report_fault,
 	report_handed_off,
 	report_incomplete,
 	report_over,
+	report_reviewer,
 	report_stale,
 	report_under_threshold,
 	report_unknown,
 	report_unreadable,
 } = run_cut_report
 
-// **The pre-gate cut is conditional on the same statistic the implementation-phase cut reads**
-// (joshuafolkken/kit#2312). `cost_cli.session_verdict` prices the newest request
-// against `CONTEXT_CUT_THRESHOLD`, so no second threshold is introduced — an `under` session skips the
-// cut, and an unmeasurable one keeps the old unconditional cut as the safety net joshuafolkken/kit#1933
-// relies on. Only the pre-gate phase is checked here; the implementation-phase caller gates its own
+// **The pre-gate cut is conditional on the same statistic the implementation-phase cut reads**.
+// `cost_cli.session_verdict` prices the newest request against `CONTEXT_CUT_THRESHOLD`, so no second
+// threshold is introduced — an `under` session skips the cut, and an unmeasurable one still cuts as
+// the safety net. Only the pre-gate phase is checked here; the implementation-phase caller gates its own
 // `--impl` cut on `pnpm josh cost --cut` before it is ever issued.
 function skips_pre_gate_cut(phase: string): boolean {
 	if (phase !== run_cut.PRE_GATE_PHASE) return false
@@ -96,14 +102,14 @@ function report_relaunch_failure(target: string, note: string): number {
 
 function report_missing_supervisor(issue: string): number {
 	console.error(
-		`The OpenAI supervisor for #${issue} is not live, so this nested process was not cut and can continue. Re-dispatch the lane to recover the supervisor.`,
+		`The OpenAI supervisor for ${session_cite.issue(issue)} is not live, so this nested process was not cut and can continue. Re-dispatch the lane to recover the supervisor.`,
 	)
 
 	return report(FAILED_VERDICT, FAILURE_EXIT_CODE)
 }
 
-// **The relaunched child is started at the effort of the phase it is resuming into**
-// (joshuafolkken/kit#2382). A pre-gate resume drives the gate, commit, PR and merge — the mechanical
+// **The relaunched child is started at the effort of the phase it is resuming into**.
+// A pre-gate resume drives the gate, commit, PR and merge — the mechanical
 // ship/bookkeeping region, lowered — while an implementation resume keeps the role default. The
 // phase-aware profile is `agent_argv.resume_argv`'s; a person's `JOSH_WORKER_EFFORT` still wins over it.
 function relaunch(target: string, lane: LaneInfo, phase: string): number {
@@ -142,18 +148,18 @@ interface CutRequest {
 	issue: string
 	phase: string
 	// The `--handoff` path whose instruction and work state the record carries, absent for a pre-gate
-	// cut that resumes into the gate rather than into implementation (joshuafolkken/kit#2354).
+	// cut that resumes into the gate rather than into implementation.
 	handoff_path?: string | undefined
 }
 
-// **Every cut appends a `cut` event to the run's stream** (joshuafolkken/kit#2346). It is what advances
+// **Every cut appends a `cut` event to the run's stream**. It is what advances
 // `run:step` past the phase boundary — a cut emitted here is why the run's next position reads as
 // `run:cut --resume`. Best-effort by the stream's contract, so a failed append never fails the cut it
 // reports.
 async function emit_cut_event(request: CutRequest): Promise<void> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.CUT,
-		`#${request.issue} cut (${request.phase})`,
+		`${issue_cite.plain(request.issue)} cut (${request.phase})`,
 	)
 }
 
@@ -202,16 +208,16 @@ async function finish_cut(target: string, lane: LaneInfo, request: CutRequest):
 // person is watching, so the run is handed on the way `fullrun`'s entry `over` stop hands it on.
 function report_held_cut(issue: string): number {
 	console.error(
-		`The cut is recorded for #${issue} outside a lane, so nothing was relaunched. Keep the hold, send a \`confirmation\` Telegram whose body names the resume command \`fullrun #${issue}\`, and end the turn; the fresh session's \`pnpm josh run:cut --resume ${issue}\` answers \`resume-impl\` with the handoff.`,
+		`The cut is recorded for ${session_cite.issue(issue)} outside a lane, so nothing was relaunched. Keep the hold, send a \`confirmation\` Telegram whose body names the resume command \`fullrun ${issue_cite.plain(issue)}\`, and end the turn; the fresh session's \`pnpm josh run:cut --resume ${issue}\` answers \`resume-impl\` with the handoff.`,
 	)
 
 	return report(CUT_VERDICT, SUCCESS_EXIT_CODE)
 }
 
-// **A `fullrun` held in its own checkout takes the implementation cut too** (joshuafolkken/kit#2760).
-// The cut was lane-only, so a run a person started had no bound on its context mid-implementation. The
-// hold naming this issue is what marks the run — a tree nobody holds for it, and the pre-gate phase
-// (which a held run's gate reaches in the same session), stay `not-a-lane` exactly as before.
+// **A `fullrun` held in its own checkout takes the implementation cut too**, so a run a person started
+// has a bound on its context mid-implementation. The hold naming this issue is what marks the run — a
+// tree nobody holds for it, and the pre-gate phase (which a held run's gate reaches in the same
+// session), stay `not-a-lane`.
 async function cut_outside_lane(
 	target: string,
 	request: Omit<CutRequest, 'branch'>,
@@ -256,18 +262,16 @@ async function cut(
 // **The adoption is the resume-uniqueness guarantee**: it removes and creates exclusively, so of two
 // racing resumes only one wins the create and the loser is answered `busy`.
 // An implementation cut resumes back into implementation; a pre-gate one into the gate. The resuming
-// child is told which by the verdict rather than reconstructing it from the record
-// (joshuafolkken/kit#1933).
+// child is told which by the verdict rather than reconstructing it from the record.
 function resume_verdict_for(cut_record: RunCut): string {
 	return run_cut.resumes_into_implementation(cut_record.phase)
 		? RESUME_IMPL_VERDICT
 		: RESUME_VERDICT
 }
 
-// **An implementation resume removes the record; a pre-gate one marks it handed off**
-// (joshuafolkken/kit#2310). The cuts have different multiplicities sharing one
-// record: the pre-gate cut fires once per lane, so its record must survive to answer a second resume
-// `handed-off` (joshuafolkken/kit#1935); the implementation cut is guarded by the run's
+// **An implementation resume removes the record; a pre-gate one marks it handed off**.
+// The cuts have different multiplicities sharing one record: the pre-gate cut fires once per lane, so
+// its record must survive to answer a second resume `handed-off`; the implementation cut is guarded by the run's
 // event stream rather than the cut record, so its record is cleared on resume — a lingering record
 // would keep the pre-gate guard, which reads `carried_cut_sync`, silent for the rest of the run. A double
 // cut stays impossible either way: `begin_cut`'s exclusive create is what prevents it.
@@ -282,21 +286,24 @@ function take_over(target: string, cut_record: RunCut): RunCut | undefined {
 }
 
 // The carried instruction and work state, printed to standard error so the resumed session continues
-// on what the run was told to do rather than on the tree alone (joshuafolkken/kit#2354). The record is
-// cleared on adoption, so this is where it reaches the fresh process.
+// on what the run was told to do rather than on the tree alone. The record is cleared
+// on adoption, so this is where it reaches the fresh process.
 function announce_handoff(cut_record: RunCut): void {
 	if (cut_record.handoff !== undefined) {
 		console.error(run_cut_handoff.describe_handoff(cut_record.handoff))
 	}
 }
 
-// **An implementation resume appends a `resume` event** (joshuafolkken/kit#3375). It clears the record
+// **An implementation resume appends a `resume` event**. It clears the record
 // the `cut` event stood for, so the stream is what moves `run:step` back to implementation; a pre-gate
 // resume keeps its record and appends nothing. Best-effort, as the cut's own append is.
 async function emit_resume_event(issue: string, verdict: string): Promise<void> {
 	if (verdict !== RESUME_IMPL_VERDICT) return
 
-	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.RESUME, `#${issue} resumed`)
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.RESUME,
+		`${issue_cite.plain(issue)} resumed`,
+	)
 }
 
 async function adopt(target: string, cut_record: RunCut): Promise<number> {
@@ -314,7 +321,7 @@ async function adopt(target: string, cut_record: RunCut): Promise<number> {
 }
 
 // A relaunched lane child and a fresh session both measure `under`, so only the session that took an
-// implementation cut resumes over the threshold (joshuafolkken/kit#2760); unmeasurable is not refused.
+// implementation cut resumes over the threshold; unmeasurable is not refused.
 function is_over_threshold_resume(cut_record: RunCut): boolean {
 	if (!run_cut.resumes_into_implementation(cut_record.phase)) return false
 
@@ -372,15 +379,25 @@ function end(target: string): number {
 	return report(ENDED_VERDICT, SUCCESS_EXIT_CODE)
 }
 
-// A bare cut is the pre-gate boundary and `--impl` the implementation-phase one (joshuafolkken/kit#1933).
+type CutCommand = Extract<Request, { kind: 'cut' }>
+
+// A bare cut is the pre-gate boundary and `--impl` the implementation-phase one.
 function cut_phase(request: { is_implementation: boolean }): string {
 	return request.is_implementation ? run_cut.IMPLEMENTATION_PHASE : run_cut.PRE_GATE_PHASE
 }
 
+// **A ship reviewer's cut is answered before the lane is looked up**: it
+// runs in the implementing child's lane and under its hold, so every check below would read it as the
+// run and relaunch a second child beside it. Asking about a cut (`--resume`, `--json`, `--end`) is
+// untouched — only taking one is refused.
+async function take_cut(target: string, request: CutCommand): Promise<number> {
+	if (agent_session_role.is_reviewer()) return report_reviewer()
+
+	return await cut(target, request.issue, cut_phase(request), request.handoff_path)
+}
+
 async function act(target: string, request: Request): Promise<number> {
-	if (request.kind === 'cut') {
-		return await cut(target, request.issue, cut_phase(request), request.handoff_path)
-	}
+	if (request.kind === 'cut') return await take_cut(target, request)
 
 	if (request.kind === 'resume') return await resume(target, request.issue)
 
@@ -390,7 +407,7 @@ async function act(target: string, request: Request): Promise<number> {
 }
 
 async function answer(request: Request): Promise<number> {
-	const directory = await run_cut.worktree_directory()
+	const directory = await run_cli_fault.directory_of(COMMAND, run_cut.worktree_directory)
 
 	if (directory === undefined) return report_unknown()
 
@@ -405,7 +422,8 @@ function refuse(): number {
 
 // Every path out prints exactly one token, including the ones nobody planned: an empty standard
 // output matches no verdict, which a resume entry check reads as "not a resume" and would let a fresh
-// process re-implement over a cut it should have carried.
+// process re-implement over a cut it should have carried. The token stays `unknown`, and the failure
+// says what it was rather than borrowing the unreadable-git-directory message.
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const parsed = run_cut_args.read_arguments(argv)
 
@@ -417,8 +435,8 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	try {
 		return await answer(request)
-	} catch {
-		return report_unknown()
+	} catch (error) {
+		return report_fault(run_cli_fault.message(COMMAND, error))
 	}
 }
 

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

@@ -1,7 +1,8 @@
 import { readFileSync } from 'node:fs'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 
-// The session state a cut carries across the process boundary (joshuafolkken/kit#2354). `RunCut`'s six
+// The session state a cut carries across the process boundary. `RunCut`'s six
 // scalar fields say *which* tree a fresh process resumes into — the branch, the issue, that a declared
 // cut put it here. This says *what the run was told to do* there, which nothing else recovers: the
 // user's instruction is not on GitHub, and what was done — or deliberately left alone — is not written
@@ -9,8 +10,8 @@ import { z } from 'zod'
 // instruction, and is put under the refactoring limits `CLAUDE.md` sets, so the shortest path out is to
 // restructure or delete code it does not understand.
 //
-// **This is not the conversation the cut exists to drop.** joshuafolkken/kit#1839 measured 176K of a
-// lane's 204K output as accumulated thinking, and the cut's whole point is to shed it. The instruction
+// **This is not the conversation the cut exists to drop.** Most of a lane's output is accumulated
+// thinking, and the cut's whole point is to shed it. The instruction
 // and a curated list of what is done, left, and untouched is the irreducible intent under that
 // thinking — a few short lines, bounded by `MAX_HANDOFF_BYTES` in `run-cut.ts` — so carrying it keeps
 // the resume on course without re-establishing the context the cut dropped.
@@ -50,21 +51,15 @@ function describe_key(key: HandoffKey): string {
 }
 
 // The shape a handoff file must have, derived from `handoff_schema` so the refusal that asks for the file
-// and the error that rejects it can never name a key the parser does not read (joshuafolkken/kit#3195).
-// A refusal that listed the four items in prose was answered with Markdown, which `parse_handoff` rejects.
+// and the error that rejects it can never name a key the parser does not read — a refusal listing the
+// items in prose invites Markdown, which `parse_handoff` rejects.
 const HANDOFF_FORMAT = `a JSON object {${handoff_schema
 	.keyof()
 	.options.map((key) => describe_key(key))
 	.join(', ')}}`
 
 function parse_handoff(raw: string): Handoff | undefined {
-	try {
-		const parsed = handoff_schema.safeParse(JSON.parse(raw))
-
-		return parsed.success ? parsed.data : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw, handoff_schema)
 }
 
 // A path given but unreadable, or holding text that is not a well-formed handoff, is `undefined` — the
@@ -78,8 +73,7 @@ function read_handoff_file(handoff_path: string): Handoff | undefined {
 }
 
 // A complete handoff carries a non-empty instruction; the lists may be empty. This is the required
-// field the resume checks so a session is never silently continued without the instruction it needs
-// (joshuafolkken/kit#2354).
+// field the resume checks so a session is never silently continued without the instruction it needs.
 function is_complete_handoff(handoff: Handoff | undefined): boolean {
 	return handoff !== undefined && handoff.instruction.trim() !== ''
 }
@@ -93,7 +87,7 @@ function is_within_bound(handoff: Handoff, max_bytes: number): boolean {
 }
 
 // A path is read into a handoff, refused when it will not parse or would push the record past its
-// bound — the cut is only worth its resume while the record stays small (joshuafolkken/kit#2354).
+// bound — the cut is only worth its resume while the record stays small.
 function load_handoff(handoff_path: string | undefined, max_bytes: number): HandoffLoad {
 	if (handoff_path === undefined) return { kind: 'ok', handoff: undefined }
 
@@ -132,8 +126,14 @@ function describe_handoff(handoff: Handoff): string {
 	].join('\n\n')
 }
 
+// Where a handoff file is written: `.claude/tmp/` is ignored, so `josh git`, which stages every
+// untracked non-ignored file, cannot commit the note with the code. A refusal that asked for "a file"
+// and named no place got one written beside the code and committed (joshuafolkken/kit#3603).
+const HANDOFF_PATH = '.claude/tmp/handoff-<N>.json'
+
 const run_cut_handoff = {
 	HANDOFF_FORMAT,
+	HANDOFF_PATH,
 	describe_handoff,
 	handoff_schema,
 	is_complete_handoff,

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

@@ -1,8 +1,9 @@
 import { run_cut, type CutState, type RunCut } from './run-cut'
+import { run_cut_handoff } from './run-cut-handoff'
 
-// The verdict tokens `josh run:cut` answers with and the reports that print them, split out of
-// `run-cut-cli.ts` so the CLI keeps to acting on the record. The contract is unchanged: **standard
-// output carries exactly one token** and every explanation goes to standard error.
+// The verdict tokens `josh run:cut` answers with and the reports that print them, kept apart from
+// `run-cut-cli.ts` so the CLI keeps to acting on the record. **Standard output carries exactly one
+// token** and every explanation goes to standard error.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -10,17 +11,16 @@ const FAILURE_EXIT_CODE = 1
 const CUT_VERDICT = 'cut'
 const RESUME_VERDICT = 'resume'
 // An implementation-phase resume: the fresh process continues implementing rather than going to the
-// gate (joshuafolkken/kit#1933). It is a distinct token so the resuming child branches on it without
-// re-reading the record.
+// gate. It is a distinct token so the resuming child branches on it without re-reading the record.
 const RESUME_IMPL_VERDICT = 'resume-impl'
 const FRESH_VERDICT = 'fresh'
 // The current context is under the shared cut threshold, so the pre-gate cut was not worth its
-// resume and nothing was cut (joshuafolkken/kit#2312). A benign, non-failing answer: the run carries
+// resume and nothing was cut. A benign, non-failing answer: the run carries
 // on to the gate itself, exactly as `not-a-lane` does.
 const UNDER_THRESHOLD_VERDICT = 'under-threshold'
 const STALE_VERDICT = 'stale'
 // The record matched the tree but carried no instruction to resume on, so the run was refused rather
-// than continued blind to what it was told to do (joshuafolkken/kit#2354).
+// than continued blind to what it was told to do.
 const INCOMPLETE_VERDICT = 'incomplete'
 // The `--handoff` path was given but could not be read as a handoff, or was too large for the record;
 // the cut is refused rather than taken without the instruction it was meant to carry.
@@ -34,7 +34,7 @@ const ENDED_VERDICT = 'ended'
 const UNREADABLE_VERDICT = 'unreadable'
 const UNKNOWN_VERDICT = 'unknown'
 // The asking session is over the shared context-cut threshold, so an implementation cut was not
-// resumed into it (joshuafolkken/kit#2760) — the same refusal `run:carry` answers `over` with.
+// resumed into it — the same refusal `run:carry` answers `over` with.
 const OVER_VERDICT = 'over'
 
 function report(verdict: string, code: number): number {
@@ -56,7 +56,7 @@ function report_busy(cut_record: RunCut): number {
 }
 
 // The record matched the tree but carried no instruction; the run is refused rather than continued
-// without what it was told to do (joshuafolkken/kit#2354).
+// without what it was told to do.
 function report_incomplete(cut_record: RunCut): number {
 	console.error(run_cut.incomplete_message(cut_record))
 
@@ -64,21 +64,23 @@ function report_incomplete(cut_record: RunCut): number {
 }
 
 // The `--handoff` file parsed but the assembled record would not fit the byte bound — the scalar fields
-// carry a handoff that fit alone past the cap (joshuafolkken/kit#2354).
+// carry a handoff that fit alone past the cap.
 const HANDOFF_OVERFLOW_NOTE = '--handoff <path> would grow the cut record past its byte bound'
 // An implementation cut resumes into implementation, and that resume refuses a record with no
 // instruction (`incomplete`) — so the cut is refused here instead of relaunching a successor that can
-// only stop (joshuafolkken/kit#2484).
+// only stop.
 const HANDOFF_MISSING_NOTE = 'this cut resumes into implementation and needs --handoff <path>'
 
 function report_bad_handoff(note: string): number {
-	console.error(`${note}. Nothing was cut; write the handoff file and reissue.`)
+	console.error(
+		`${note}. Nothing was cut; write the handoff file at ${run_cut_handoff.HANDOFF_PATH} and reissue.`,
+	)
 
 	return report(BAD_HANDOFF_VERDICT, FAILURE_EXIT_CODE)
 }
 
 // A successor already resumed this cut; a process woken after its own hand-off is told to stop rather
-// than to investigate (joshuafolkken/kit#1935). It is a benign, non-failing stop.
+// than to investigate. It is a benign, non-failing stop.
 function report_handed_off(cut_record: RunCut): number {
 	console.error(run_cut.handed_off_message(cut_record))
 
@@ -91,12 +93,17 @@ function report_unreadable(): number {
 	return report(UNREADABLE_VERDICT, FAILURE_EXIT_CODE)
 }
 
-function report_unknown(): number {
-	console.error(run_cut.unknown_message())
+// `unknown` with the reason it was answered: nothing was established, so nothing may be concluded.
+function report_fault(message: string): number {
+	console.error(message)
 
 	return report(UNKNOWN_VERDICT, FAILURE_EXIT_CODE)
 }
 
+function report_unknown(): number {
+	return report_fault(run_cut.unknown_message())
+}
+
 // A cut is only meaningful on a lane branch whose implementation is uncommitted. On the default
 // branch, or with a clean tree, there is nothing to carry across the boundary.
 function refuse_unready(state: CutState): number {
@@ -117,7 +124,19 @@ function report_under_threshold(): number {
 	return report(UNDER_THRESHOLD_VERDICT, SUCCESS_EXIT_CODE)
 }
 
-// **An implementation cut is never resumed by a session over the threshold** (joshuafolkken/kit#2760).
+// **A ship reviewer takes no cut, of either phase** (joshuafolkken/kit#3623). Its supervisor is waiting
+// on the findings file it has yet to write, so a relaunch would stand a second child in the lane beside
+// the one the supervisor repairs with. Answered `not-a-lane`, the verdict that already means "nothing
+// was cut and this process carries on".
+function report_reviewer(): number {
+	console.error(
+		'This session is a ship reviewer, which its supervisor is waiting on, so nothing was cut and nothing was relaunched. Write the findings file and finish the review in this process.',
+	)
+
+	return report(NOT_A_LANE_VERDICT, SUCCESS_EXIT_CODE)
+}
+
+// **An implementation cut is never resumed by a session over the threshold**.
 // The cut outside a lane leaves the session that took it open, so a person retyping `fullrun #N` there
 // would be answered `resume-impl`, keep implementing over the threshold, and be cut again on the next
 // edit — a loop that sheds no context. The record is left intact for a fresh session.
@@ -155,9 +174,11 @@ const run_cut_report = {
 	report,
 	report_bad_handoff,
 	report_busy,
+	report_fault,
 	report_handed_off,
 	report_incomplete,
 	report_over,
+	report_reviewer,
 	report_stale,
 	report_under_threshold,
 	report_unknown,