@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/hooks/format-edited-file.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
 import { ESLINT_EDIT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { json_value } from '#scripts/lib/json-value'
 import { HOOK_PROCESS_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { execa } from 'execa'
@@ -61,7 +62,7 @@ const PRETTIER_ARGUMENTS: ReadonlyArray<string> = ['--write', '--ignore-unknown'
 // nothing to say about it, and a non-zero exit here would be reported as a failed hook.
 //
 // The cache flags are not here to make the hook faster — they are here to stop it destroying the
-// gate's cache (joshuafolkken/kit#1332). ESLint started *without* `--cache` deletes the file at
+// gate's cache. ESLint started *without* `--cache` deletes the file at
 // `--cache-location`, so this hook wiped `.eslintcache` on every edit and the gate's lint ran cold
 // every time. Passing them points that deletion, and the hook's own reads and writes, at a location
 // of its own — its own rather than the gate's because the two run concurrently, and each eslint run
@@ -81,7 +82,7 @@ const ESLINT_ARGUMENTS: ReadonlyArray<string> = [
 // hope — behind a socket and forwards the same arguments to it, which is why the fixed output is
 // identical rather than merely similar. The config entry file is re-read per request; the modules it
 // imports are not, which `plan_daemon_restart` below is the answer to. The daemon exits after 15
-// minutes of inactivity (joshuafolkken/kit#1259).
+// minutes of inactivity.
 const ESLINT_DAEMON = 'eslint_d'
 const DAEMON_RESTART = 'restart'
 // The two shapes a flat config is built from here and in every consumer of this kit: the root
@@ -90,8 +91,7 @@ const ESLINT_CONFIG_DIR = 'eslint'
 const ESLINT_CONFIG_ENTRY = /^eslint\.config\.[cm]?[jt]s$/u
 
 // The problems eslint could not auto-fix are handed to the model verbatim from eslint's own stdout —
-// its default formatter already prints the file, the `line:col`, and the rule name the issue asks
-// for (joshuafolkken/kit#2275). A header names what the block is, since additionalContext arrives
+// its default formatter already prints the file, the `line:col`, and the rule name. A header names what the block is, since additionalContext arrives
 // with no framing of its own.
 const DIAGNOSTIC_HEADER =
 	'The edit hook could not auto-fix these lint problems; address them now rather than at the gate:'
@@ -129,7 +129,7 @@ interface BinRoutes {
 // on a half-written file. The stdout the spawn captured is what separates the two: eslint prints the
 // problems it is exiting non-zero about, while a daemon that could not start prints its reason to
 // stderr and leaves stdout empty. It is kept whole rather than reduced to a boolean because the
-// problems eslint could not fix are reported to the model from it (joshuafolkken/kit#2275).
+// problems eslint could not fix are reported to the model from it.
 interface CommandOutcome {
 	exit_code: number
 	stdout: string
@@ -138,13 +138,7 @@ interface CommandOutcome {
 type CommandRunner = (command: FormatCommand, project_root: string) => Promise<CommandOutcome>
 
 function parse_edited_path(raw_payload: string): string | undefined {
-	try {
-		const result = hook_payload_schema.safeParse(JSON.parse(raw_payload))
-
-		return result.success ? result.data.tool_input?.file_path : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw_payload, hook_payload_schema)?.tool_input?.file_path
 }
 
 // Read against the path relative to the project root, never the absolute one: a checkout that lives
@@ -352,7 +346,7 @@ function format_diagnostics(unfixed: string | undefined): string | undefined {
 }
 
 // The fixes eslint could apply are applied silently, as before; what it could not fix is returned so
-// the model sees it on this edit rather than at the gate (joshuafolkken/kit#2275). A `PostToolUse`
+// the model sees it on this edit rather than at the gate. A `PostToolUse`
 // hook still reports no failure — the edit already landed, and returning the problems is not the same
 // as failing the write.
 // Runs the planned commands in order, returning the last unfixed eslint output. Empty until eslint
@@ -410,7 +404,7 @@ async function format_edited_payload(
 const HOOK_EVENT_NAME = 'PostToolUse'
 
 // The live round-trip density line, riding this hook rather than one of its own
-// (joshuafolkken/kit#1329) — a `PostToolUse` matcher covering every tool would add a process start to
+//  — a `PostToolUse` matcher covering every tool would add a process start to
 // all ~250 calls of a run.
 //
 // **A `PostToolUse` hook's plain stdout never reaches the model**; only `additionalContext` inside
@@ -458,9 +452,9 @@ function report_no_payload(): void {
 // their processes have run; the density line is joined to them into the single envelope the harness
 // can parse, rather than written first on its own. The rewrite notice is read from the file itself —
 // its content before the formatters ran against its content after — so it too is known only once they
-// have (joshuafolkken/kit#2314). The rewrite, lint and spell blocks are composed together first, then
-// joined to the density line — one envelope, since a `PostToolUse` hook's stdout carries only one
-// (joshuafolkken/kit#2296). A hook killed at its 15s timeout is the one case this loses the density
+// have. The rewrite, lint and spell blocks are composed together first, then
+// joined to the density line — one envelope, since a `PostToolUse` hook's stdout carries only one.
+// A hook killed at its 15s timeout is the one case this loses the density
 // line to — a run already gone pathologically wrong, per HOOK_PROCESS_TIMEOUT_MS.
 async function run_hook(payload: string): Promise<void> {
 	const notice = time_density_hook.density_notice(payload)

package/scripts/hooks/format-rewrite-notice.ts

@@ -1,23 +1,24 @@
 import { file_reader } from '#scripts/lib/read-file'
 
-// The rewrite half of the edit hook (joshuafolkken/kit#2314). The format hook runs prettier and
+// The rewrite half of the edit hook. The format hook runs prettier and
 // `eslint --fix` in place after every edit, so a file the model just wrote can be rewritten out from
 // under the image the model holds — and the next `Edit` against that stale image misses, then pays for
-// a full re-read that rides every later request. joshuafolkken/kit#2275 built the `additionalContext`
-// path this rides and joshuafolkken/kit#2296 put cspell on it; this returns the fact that the file
+// a full re-read that rides every later request. Riding the same `additionalContext` path as the lint
+// and cspell halves, this returns the fact that the file
 // changed and the region that changed, so the model reissues against current text without re-reading
 // the whole file. Nothing is added when formatting left the file untouched.
 
-// additionalContext rides back on the edit, so the changed region is cut to this bound rather than
-// let a large reformat balloon the run's context — the notice is a cheaper hint than the full re-read
-// it replaces, and stays cheaper only while it is bounded.
-const MAX_REWRITE_CHARS = 1200
-const REWRITE_TRUNCATION_NOTICE = '\n…(rewrite preview truncated)'
+// additionalContext rides back on the edit, so the whole notice is cut to this bound rather than let
+// a large reformat balloon the run's context — the notice is a cheaper hint than the full re-read it
+// replaces, and stays cheaper only while it is bounded. The line range leads, so a cut preview still
+// says where to re-read.
+const MAX_REWRITE_CHARS = 600
+const REWRITE_TRUNCATION_NOTICE = '\n…(truncated)'
 // The header names what the block is, since additionalContext arrives with no framing of its own, and
 // says the one thing the model has to act on: its copy is stale, so re-read before the next edit.
 const REWRITE_HEADER =
-	'The format hook rewrote this file after your edit, so your in-memory copy is now stale — re-read it before the next Edit or the match will miss.'
-const REWRITE_RANGE_PREFIX = 'Changed around lines '
+	'The format hook rewrote this file, so your copy is stale; re-read these lines before the next Edit.'
+const REWRITE_RANGE_PREFIX = 'Lines '
 const LINE_SEPARATOR = '\n'
 const FIRST_LINE = 1
 
@@ -64,21 +65,22 @@ function changed_range(before: string, after: string): ChangedRange {
 	}
 }
 
-function cap_body(body: string): string {
-	if (body.length <= MAX_REWRITE_CHARS) return body
+// `budget` is what the header and the range left of the bound; the marker is paid out of it.
+function cap_body(body: string, budget: number): string {
+	if (body.length <= budget) return body
 
-	return `${body.slice(0, MAX_REWRITE_CHARS)}${REWRITE_TRUNCATION_NOTICE}`
+	return `${body.slice(0, Math.max(0, budget - REWRITE_TRUNCATION_NOTICE.length))}${REWRITE_TRUNCATION_NOTICE}`
 }
 
-// The block the model reads: the header, the line range, then the region's new text cut to the bound.
-// `undefined` when formatting changed nothing, so the ordinary edit adds nothing to additionalContext.
+// The block the model reads: the header, the line range, then the region's new text — the whole cut
+// to the bound. `undefined` when formatting changed nothing, so the ordinary edit adds nothing.
 function build(before: string, after: string): string | undefined {
 	if (before === after) return undefined
 
 	const range = changed_range(before, after)
-	const location = `${REWRITE_RANGE_PREFIX}${String(range.start_line)}-${String(range.end_line)}:`
+	const head = `${REWRITE_HEADER}\n${REWRITE_RANGE_PREFIX}${String(range.start_line)}-${String(range.end_line)}:\n`
 
-	return `${REWRITE_HEADER}\n${location}\n${cap_body(range.body)}`
+	return `${head}${cap_body(range.body, MAX_REWRITE_CHARS - head.length)}`
 }
 
 // The file content around a format run, read for the before/after comparison. A path the hook was

package/scripts/hooks/pre-push-unit.ts

@@ -5,22 +5,18 @@ import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
 import { hook_gate_reuse } from '#scripts/gate/hook-gate-reuse'
 import { test_unit_guard } from '#scripts/test/test-unit-guard'
 
-// The pre-push hook's unit run, which no longer re-runs a suite a green gate already covers
-// (joshuafolkken/kit#1334).
+// The pre-push hook's unit run, which does not re-run a suite a green gate already covers: the gate
+// writes its record down, and re-running `vitest run` on a tree it just printed green is the bulk of
+// what `pnpm josh git -y` would otherwise spend.
 //
-// Measured on joshuafolkken/kit#1326: `pnpm josh git -y` took 40 seconds, 15.9 of them the pre-push
-// `vitest run` — started 40 seconds after `pnpm josh gate` had printed all four checks green on that
-// same tree, with nothing edited in between. The gate had written the record down and the hook was
-// the one reader that never looked at it.
-//
-// **The decision is joshuafolkken/kit#1328's, imported rather than restated.** "There is a green
+// **The decision is the gate's, imported rather than restated.** "There is a green
 // record and nothing it covers has moved" is one question, and a hook answering it differently from
 // the gate beside it would be two commands disagreeing about the same tree — the clone `CLAUDE.md`
 // prohibits. So `gate_skip.reusable_green_gate` decides all three of its conditions here too: the
 // file map matches, the **base commit** the map is a diff against matches, and the map is non-empty.
 //
-// **What this hook shares with the pre-commit type check is `hook-gate-reuse.ts`**
-// (joshuafolkken/kit#1381): the escape hatch, the pre-filter in front of the record and the one
+// **What this hook shares with the pre-commit type check is `hook-gate-reuse.ts`**:
+// the escape hatch, the pre-filter in front of the record and the one
 // `git status` reading both narrow themselves from. Only the narrowing itself is written here, because
 // only it is about a push.
 //
@@ -41,7 +37,7 @@ const FORCE_ENV = 'JOSH_PRE_PUSH_FORCE'
 // `gate-tree.ts` rather than read a second way here — plus the one this hook adds.
 interface PushTree extends GateTree {
 	is_clean: boolean
-	// What a dirty tree reports as the reason the record was not reused (joshuafolkken/kit#3307) — the
+	// What a dirty tree reports as the reason the record was not reused — the
 	// paths name a lock file a hook's own `pnpm install` rewrote, the case that went unexplained.
 	carry_miss: string
 }
@@ -104,7 +100,7 @@ function push_reuse(
 // **The sentence claims the result, never merely the omission.** "unit tests skipped" reads as "not
 // verified", which is the one thing this line must not be mistaken for while the push it precedes
 // goes on to the remote. So it says what passed, on which tree, when, and how to run it anyway — in
-// the one sentence every reader of the record shares (joshuafolkken/kit#1381).
+// the one sentence every reader of the record shares.
 function format_skip(taken_at: string): string {
 	return gate_skip.format_reuse_notice({
 		subject: 'the unit tests',
@@ -118,9 +114,9 @@ function format_skip(taken_at: string): string {
 // The suite is run through the guard `josh test:unit` uses rather than a bare `vitest run`, so a
 // project with no vitest prints a skip notice instead of failing the push — the behavior the hook's
 // other commands already have. **A project that has vitest and no test file at all fails the push
-// instead** (joshuafolkken/kit#1224): the guard treats that half as a broken state rather than a
+// instead**: the guard treats that half as a broken state rather than a
 // young project, and the hook returns what the guard returns.
-// **A fall back to the whole suite says why, in one line** (joshuafolkken/kit#3307): under a crowded
+// **A fall back to the whole suite says why, in one line**: under a crowded
 // machine the suite costs minutes, and a silent miss left a moved merge base, a dirty tree and a
 // mismatched record indistinguishable from one another.
 function format_miss(reason: string): string {

package/scripts/hooks/pretool-guard-cli.ts

@@ -2,10 +2,10 @@
 import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
-import { pretool_guard, pretool_outcome_async } from './pretool-guard'
+import { pretool_guard } from './pretool-guard'
 
-// The `PreToolUse` hook's entry, kept apart from the composition in `pretool-guard.ts`
-// (joshuafolkken/kit#2922). The hook bundles are built with `splitting: true`, which moves a module
+// The `PreToolUse` hook's entry, kept apart from the composition in `pretool-guard.ts`.
+// The hook bundles are built with `splitting: true`, which moves a module
 // imported by two entries into a shared chunk — and `codex-hook-adapter.ts` imports `pretool-guard.ts`.
 // Its self-invoke went into that chunk, whose `import.meta.url` never equals the launched
 // `dist/hooks/pretool-guard.js`, so the bundled hook ran no guard at all and every refusal failed open.
@@ -16,6 +16,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 		const raw_payload = await text(process.stdin)
 
 		hook_decision.load_environment_file()
-		pretool_guard.emit(raw_payload, await pretool_outcome_async(raw_payload))
+		await pretool_guard.respond(raw_payload)
 	}
 }

package/scripts/hooks/pretool-guard.ts

@@ -1,15 +1,18 @@
 import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
 import { investigation_refusal } from '#scripts/delegation/investigation-guard'
 import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
+import { lane_phase } from '#scripts/lane/lane-phase'
+import { json_value } from '#scripts/lib/json-value'
 import { delivered_rules } from '#scripts/rules/delivered-rules'
 import { lane_background } from '#scripts/rules/lane-background'
+import { piped_verification } from '#scripts/rules/piped-verification'
 import { run_parent_cut_hook } from '#scripts/run/run-parent-cut-hook'
 import { run_watcher_hook } from '#scripts/run/run-watcher-hook'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { batch_outcome } from './batch-guard'
 import { step_zero_notice } from './step-zero-notice'
 
-// One PreToolUse process for the three guards that used to be three (joshuafolkken/kit#1930). A Bash
+// One PreToolUse process for the three guards that used to be three. A Bash
 // call used to spawn `batch:guard`, `investigation:guard` and `rule:guard` separately — three pnpm
 // launches on top of the tool call — while consumers paid that thrice on every guarded call. The
 // three share one shell (`hook-decision.ts`): the same payload schema, the same deny envelope, the
@@ -19,10 +22,10 @@ import { step_zero_notice } from './step-zero-notice'
 // **The verdict is identical to running the three in turn**, and that is the whole point. Each guard
 // self-gates on the tool name inside its own `is_candidate` / trigger, so running all three on the
 // union matcher (`Bash|Edit|Read|Write|AskUserQuestion`) refuses exactly what the three separate
-// entries did — `AskUserQuestion` is matched for the rule guard's lane-child interactive-ask row
-// (joshuafolkken/kit#2201), and the batching and investigation guards self-gate away from it. A
+// entries did — `AskUserQuestion` is matched for the rule guard's lane-child interactive-ask row,
+// and the batching and investigation guards self-gate away from it. A
 // refusal from any guard wins first; only when none refuses is the batch guard's non-blocking notice
-// (the whole-file-write notice, joshuafolkken/kit#1848) emitted. Each guard still honours its own
+// (the whole-file-write notice) emitted. Each guard still honours its own
 // switch (`JOSH_BATCH_GUARD` / `JOSH_INVESTIGATION_GUARD` / `JOSH_RULE_GUARD`) internally, so this
 // process needs no switch of its own.
 
@@ -44,7 +47,7 @@ function is_clear(outcome: GuardOutcome): boolean {
 }
 
 // The duplicate-read guard is `notice`-mode in a lane child, so it is the second guard that can raise a
-// non-refusal notice (joshuafolkken/kit#2298). Its notice is surfaced only where nothing else spoke —
+// non-refusal notice. Its notice is surfaced only where nothing else spoke —
 // a refusal from any guard, or the batch guard's own notice, wins first.
 function with_duplicate_notice(combined: GuardOutcome, notice: string | undefined): GuardOutcome {
 	if (notice === undefined || !is_clear(combined)) return combined
@@ -52,7 +55,7 @@ function with_duplicate_notice(combined: GuardOutcome, notice: string | undefine
 	return { reason: undefined, notice, fault: undefined }
 }
 
-// The Step 0 reminder is the last word (joshuafolkken/kit#2994): asked only where every guard stayed
+// The Step 0 reminder is the last word: asked only where every guard stayed
 // clear, so a refusal or another notice never spends its once-per-session stamp unseen.
 function with_step_zero_notice(outcome: GuardOutcome, raw_payload: string): GuardOutcome {
 	if (!is_clear(outcome)) return outcome
@@ -81,15 +84,22 @@ function pretool_outcome(raw_payload: string): GuardOutcome {
 	return with_step_zero_notice(guard_outcome(raw_payload), raw_payload)
 }
 
+// The Step 0 notice fires once, on the first runtime-file edit: the moment a lane child's plan turns
+// into code, which `run:board` draws as its `implement` phase. Both the Claude
+// path and the Codex adapter call this on their final outcome, so neither runtime skips the phase.
+async function mark_phase(outcome: GuardOutcome): Promise<void> {
+	if (outcome.notice === step_zero_notice.NOTICE) await lane_phase.mark_implement()
+}
+
 // The watcher guard is the one composed rule that cannot answer synchronously — it reads the lane
-// registry and the watcher's life record off disk (joshuafolkken/kit#2353). So it is asked after the
+// registry and the watcher's life record off disk. So it is asked after the
 // synchronous guards and only where they stayed clear: a refusal from any of them wins first, exactly
 // as `combine_outcomes` orders them, and the watcher's refusal fills a clear verdict rather than
 // overriding one. It fires once per run itself (`run-watcher-hook.ts`), so a stale watcher refuses the
 // first call but not the `pnpm josh run:progress --wait` that fixes it.
 //
-// **The parent hand-off guard is the second asynchronous rule, asked after the watcher's**
-// (joshuafolkken/kit#2947). It reads the carry record to tell the `backlogrun` parent apart, so it sits
+// **The parent hand-off guard is the second asynchronous rule, asked after the watcher's**.
+// It reads the carry record to tell the `backlogrun` parent apart, so it sits
 // beside the watcher rather than among the synchronous rows; a stale watcher is the cheaper fix and is
 // surfaced first.
 async function async_reason(raw_payload: string): Promise<string | undefined> {
@@ -107,7 +117,11 @@ async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome>
 
 	if (reason !== undefined) return { reason, notice: undefined, fault: undefined }
 
-	return with_step_zero_notice(base, raw_payload)
+	const outcome = with_step_zero_notice(base, raw_payload)
+
+	await mark_phase(outcome)
+
+	return outcome
 }
 
 function guarded_call(raw_payload: string): GuardedCall | undefined {
@@ -122,8 +136,13 @@ function guarded_call(raw_payload: string): GuardedCall | undefined {
 	}
 }
 
-// The envelope that replaces the outcome's own when a lane child backgrounded `josh ship` alone
-// (joshuafolkken/kit#3154): the call is run in the foreground instead of being refused. A refusal from
+// A rewrite's note first, so the transcript's context line opens with it; the outcome's notice after.
+function rewrite_context(note: string, outcome: GuardOutcome): string {
+	return [note, outcome.notice ?? outcome.fault].filter(Boolean).join('\n\n')
+}
+
+// The envelope that replaces the outcome's own when a lane child backgrounded `josh ship` alone:
+// the call is run in the foreground instead of being refused. A refusal from
 // any guard still wins, and a notice the outcome carried rides along in the same context.
 function foreground_rewrite(
 	outcome: GuardOutcome,
@@ -138,19 +157,75 @@ function foreground_rewrite(
 
 	if (input === undefined) return undefined
 
-	const context = [lane_background.FOREGROUND_NOTE, outcome.notice ?? outcome.fault]
+	return hook_decision.rewrite_envelope(
+		input,
+		rewrite_context(lane_background.FOREGROUND_NOTE, outcome),
+	)
+}
+
+interface PipefailRewrite {
+	payload: string
+	input: Record<string, unknown>
+}
+
+// A piped josh check the hook runs under `set -o pipefail` instead of refusing it:
+// the rewritten input, and the payload that carries it. The rewrite is the
+// rule guard's delivery, so the rule guard's switch turns it off too.
+function pipefail_rewrite(raw_payload: string): PipefailRewrite | undefined {
+	if (!delivered_rules.is_enabled()) return undefined
+
+	const call = guarded_call(raw_payload)
+	const input = call === undefined ? undefined : piped_verification.pipefail_input(call)
+	const payload = json_value.parse_or_undefined(raw_payload)
+
+	if (input === undefined || !json_value.is_record(payload)) return undefined
+
+	return { payload: JSON.stringify({ ...payload, tool_input: input }), input }
+}
+
+function pipefail_envelope(
+	outcome: GuardOutcome,
+	input: Record<string, unknown> | undefined,
+): string | undefined {
+	if (input === undefined || outcome.reason !== undefined) return undefined
 
-	return hook_decision.rewrite_envelope(input, context.filter(Boolean).join('\n\n'))
+	return hook_decision.rewrite_envelope(
+		input,
+		rewrite_context(piped_verification.PIPEFAIL_NOTE, outcome),
+	)
 }
 
-// The hook's one write: the foreground rewrite where it applies, the outcome's own envelope otherwise.
-function emit(raw_payload: string, outcome: GuardOutcome): void {
-	const rewrite = foreground_rewrite(outcome, raw_payload)
+// The hook's one write: a rewrite where one applies, the outcome's own envelope otherwise.
+function emit(
+	raw_payload: string,
+	outcome: GuardOutcome,
+	pipefail_input?: Record<string, unknown>,
+): void {
+	const rewrite =
+		pipefail_envelope(outcome, pipefail_input) ?? foreground_rewrite(outcome, raw_payload)
 
 	if (rewrite === undefined) hook_decision.emit_outcome(outcome)
 	else process.stdout.write(`${rewrite}\n`)
 }
 
-const pretool_guard = { combine_outcomes, emit, foreground_rewrite, pretool_outcome }
+// **The guards judge the call that will run.** A rewritable piped check reaches every guard already
+// prefixed, so the piped-verification row stays quiet on it while any other guard's refusal still wins
+// over the rewrite. The Codex adapter cannot rewrite a call, so it goes on judging the call as typed.
+async function respond(raw_payload: string): Promise<void> {
+	const pipefail = pipefail_rewrite(raw_payload)
+	const judged = pipefail?.payload ?? raw_payload
+
+	emit(judged, await pretool_outcome_async(judged), pipefail?.input)
+}
+
+const pretool_guard = {
+	combine_outcomes,
+	emit,
+	foreground_rewrite,
+	mark_phase,
+	pipefail_rewrite,
+	pretool_outcome,
+	respond,
+}
 
 export { pretool_guard, pretool_outcome, pretool_outcome_async }

package/scripts/hooks/reserved-run.ts

@@ -4,7 +4,7 @@ import { core_budget } from '#scripts/gate/core-budget'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { execa } from 'execa'
 
-// Runs a command while holding a place in the machine-wide core budget (joshuafolkken/kit#2351).
+// Runs a command while holding a place in the machine-wide core budget.
 //
 // **The pre-push hook's `pnpm install` and `pnpm josh audit` are heavy and were outside the ledger.**
 // The gate's checks reserve their cores, but a lefthook `pre-push` fires `pnpm install` on every push
@@ -70,7 +70,7 @@ async function run_reserved(argv: ReadonlyArray<string>): Promise<number> {
 	}
 
 	// **A command already inside a gate's unit suite takes no place, for the reason a nested gate does
-	// not** (joshuafolkken/kit#2351): this repository's own gate tests exercise the wrapper, and a place
+	// not**: this repository's own gate tests exercise the wrapper, and a place
 	// claimed there would wait on cores the outer gate is holding. In its real use — the pre-push hook —
 	// nothing has set the marker, so the reservation is taken.
 	if (unit_worker_share.is_nested_run()) return await run_command(parsed.command)

package/scripts/hooks/step-zero-notice.ts

@@ -4,7 +4,7 @@ import { json_value } from '#scripts/lib/json-value'
 import { test_declared_logic } from '#scripts/test/test-declared-logic'
 
 // The Code Change Rules Step 0 reminder, delivered at the moment implementation code is about to be
-// written rather than on every prompt (joshuafolkken/kit#2994). As a `UserPromptSubmit` echo it was
+// written rather than on every prompt. As a `UserPromptSubmit` echo it was
 // injected into every turn — a question that writes nothing included — and re-read as accumulated
 // context on each turn after it. The trigger the rule names is "before writing any implementation
 // code", so the hook that delivers it is the one that sees that write: the first `Edit` / `Write` of a

package/scripts/hooks/stop-guard.ts

@@ -23,7 +23,7 @@ import { run_stranded_detect } from '#scripts/run/run-stranded-detect'
 import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
 
-// The `Stop` hook entry: one process that delivers the three stop-time rules (joshuafolkken/kit#2121).
+// The `Stop` hook entry: one process that delivers the three stop-time rules.
 // It is the stop-time counterpart of `pretool-guard.ts` — a second entry on the same `hook_decision`
 // foundation, not a second copy of it.
 //
@@ -33,8 +33,8 @@ import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript
 // resolving (send the notify, release the hold) and `stop_hook_active` is the backstop, so failing
 // open here costs at most a missed nudge, never a stuck run.
 
-// The hold record for this working tree is still in place, and whether it is a `prrun` stop's
-// (joshuafolkken/kit#3023). `unreadable` reads as absent: the safe direction for a stop guard is not to
+// The hold record for this working tree is still in place, and whether it is a `prrun` stop's.
+// `unreadable` reads as absent: the safe direction for a stop guard is not to
 // block, and an unreadable record is not proof a run is holding.
 async function hold_facts(): Promise<Pick<StopContext, 'hold_present' | 'prrun_stopped'>> {
 	const directory = await run_hold.worktree_directory()
@@ -65,6 +65,19 @@ function session_lang(): string {
 	return session_language.resolve_session_lang().lang
 }
 
+// Which session this is — a headless parent, a lane child, a kit-launched agent, the `backlogrun`
+// parent — the facts that say whether a person is there to answer.
+async function session_role_facts(): Promise<
+	Pick<StopContext, 'backlog_parent' | 'headless_agent' | 'headless_waiting' | 'lane_child'>
+> {
+	return {
+		headless_waiting: await run_headless.must_keep_waiting(),
+		lane_child: lane_child_marker.is_child_of(process.cwd()),
+		headless_agent: agent_headless.is_headless(),
+		backlog_parent: await run_headless.is_backlog_parent(),
+	}
+}
+
 async function build_context(
 	transcript_path: string,
 	payload_tail: { stop_hook_active: boolean; message: string },
@@ -81,14 +94,12 @@ async function build_context(
 		cut_pending: run_cut.carried_cut_sync() !== undefined,
 		filed: was_filed(tail),
 		session_owner: repo_party.current_owner(),
-		headless_waiting: await run_headless.must_keep_waiting(),
+		...(await session_role_facts()),
 		headless_refusals: stop_rules.count_headless_refusals(tail),
-		lane_child: lane_child_marker.is_child_of(process.cwd()),
 		background_pending: lane_background.pending_background_ids(tail).length > 0,
 		agent_pending: lane_background.pending_agent_ids(tail).length > 0,
 		handed_off: lane_handoff.is_handed_off(process.cwd()),
 		session_lang: session_lang(),
-		headless_agent: agent_headless.is_headless(),
 	}
 }
 
@@ -117,7 +128,7 @@ async function outcome_of(raw_payload: string): Promise<StopOutcome> {
 // a carried run: the strand judge reads this very record and returns on anything but `carried`, and a
 // stall needs a backlog driver, which begins one before its plan. A spent (`expired`) or `unreadable`
 // record a crashed run left behind is no run either, so it does not re-arm the stall's backlog probe
-// on every stop (joshuafolkken/kit#2995).
+// on every stop.
 // A failed git read — outside a repository, `git rev-parse` exits non-zero — reads as no run, since this
 // gate sits ahead of the checks' own swallowing and must not throw into the stop decision either.
 async function has_run_record(): Promise<boolean> {
@@ -133,8 +144,8 @@ async function has_run_record(): Promise<boolean> {
 }
 
 // The stall check rides the Stop hook because the stop *is* the loop boundary: a run alive but not
-// advancing ends turns without dispatching (joshuafolkken/kit#2359). The strand check rides the same
-// boundary and is the step before the stall (joshuafolkken/kit#2375): it fires when the driver is gone
+// advancing ends turns without dispatching. The strand check rides the same
+// boundary and is the step before the stall: it fires when the driver is gone
 // — the budget handed off, the owner dead, no supervisor watching. Both only report and swallow their
 // own failures, so neither can change the stop decision. An ordinary stop with no run record skips
 // both, so it pays one directory read rather than their reads and a stale stream's backlog probe.
@@ -146,7 +157,7 @@ async function run_report_checks(): Promise<void> {
 }
 
 // Nothing reaches stdout on an ordinary stop, so what the harness parses stays empty unless the stop
-// is being held — all three rules block, so a bare `#N` is reported the same way (joshuafolkken/kit#2247).
+// is being held — all three rules block, so a bare `#N` is reported the same way.
 async function write_stop_decision(raw_payload: string): Promise<void> {
 	hook_decision.load_environment_file()
 	await run_report_checks()

package/scripts/init/basic-path-migration.ts

@@ -1,5 +1,5 @@
-// The two references `josh init` writes into a basic project, under the paths they had before
-// joshuafolkken/kit#2829 renamed the static profile. kit still ships both old paths so an earlier
+// The two references `josh init` writes into a basic project, under the paths they had while the
+// basic profile was named static. kit still ships both old paths so an earlier
 // project keeps working; re-running `josh init` moves the project onto the new ones, which is what
 // lets the old paths be retired once projects have moved.
 const RENAMED_REFERENCES: ReadonlyArray<readonly [RegExp, string]> = [

package/scripts/init/claude-kit-only-settings.ts

@@ -2,8 +2,8 @@ import { patch_json_key } from '#scripts/config-merge/patch-json-key'
 import { claude_plugin_config } from './claude-plugin-config'
 
 // Keys kit's own `.claude/settings.json` sets for its sessions but never ships. `enableArtifact:
-// false` keeps the Artifact tool's ~12k tokens out of every call of a kit run
-// (joshuafolkken/kit#3140), but Claude Code lets any layer that sets it to `false` win, so a
+// false` keeps the Artifact tool's ~12k tokens out of every call of a kit run,
+// but Claude Code lets any layer that sets it to `false` win, so a
 // consumer given it could not turn the tool back on from `.claude/settings.local.json`.
 const KIT_ONLY_SETTING_KEYS: ReadonlyArray<string> = ['enableArtifact']
 

package/scripts/init/claude-plugin-config.ts

@@ -1,7 +1,7 @@
 import path from 'node:path'
 import { init_logic_json_merge } from './init-logic-json-merge'
 
-// The Claude Code plugin that ships kit's distributed skills (joshuafolkken/kit#1879). A consumer no
+// The Claude Code plugin that ships kit's distributed skills. A consumer no
 // longer receives the five skill directories as a byte copy under its own `.claude/skills/`; it
 // receives this marketplace and plugin declaration in its `.claude/settings.json`, and the skills
 // load from the package as `kit:<name>`.
@@ -16,7 +16,7 @@ const CLAUDE_SETTINGS_DESTINATION = path.join('.claude', 'settings.json')
 // `enabledPlugins` declares the plugin; `extraKnownMarketplaces` says where to find it. Nothing needs
 // installing: in a trusted workspace Claude Code registers the marketplace from this declaration and
 // loads the skills — an interactive session from its first session, a headless one (`claude -p`) from
-// its second (joshuafolkken/kit#2990).
+// its second.
 const PLUGIN_SETTINGS: Record<string, unknown> = {
 	extraKnownMarketplaces: {
 		[MARKETPLACE_NAME]: { source: { source: 'directory', path: MARKETPLACE_PATH } },

package/scripts/init/distributed-paths.ts

@@ -1,5 +1,5 @@
 // The path transform that makes kit's distributed AI documents resolve in a consumer, and the
-// one-line CLAUDE.md import that replaces the old byte-copy (joshuafolkken/kit#1878). Applied at
+// one-line CLAUDE.md import that replaces the old byte-copy. Applied at
 // publish time to CLAUDE.md (scripts/build/build-claude-md.ts) and at copy time to the pointer files kit
 // still ships whole (AGENTS.md / GEMINI.md / .cursorrules, via init-copy-content.ts).
 
@@ -28,7 +28,7 @@ const CLAUDE_MD_BOOTSTRAP =
 // A span containing `*` is excluded: it is a **glob**, not a reference to a file a consumer can
 // open. A distributed document that writes a directory set as `prompts/**` means "anything beneath
 // it", and rewriting that to `node_modules/@joshuafolkken/kit/prompts/**` would print a path that can
-// never appear in a consumer's diff and is not what the set matches (joshuafolkken/kit#907).
+// never appear in a consumer's diff and is not what the set matches.
 function transform_prompt_paths(content: string): string {
 	return content.replaceAll(
 		/`prompts\/([^`*]+)`/gu,
@@ -97,8 +97,8 @@ function ensure_claude_md_import(existing: string | undefined): string {
 	return `${CLAUDE_MD_BOOTSTRAP}\n\n${CLAUDE_MD_IMPORT_LINE}\n\n${updated}`
 }
 
-// The lines `ensure_claude_md_import` writes. A basic project imports other rules, so a sync from
-// before joshuafolkken/kit#2827, or a switch from full, leaves these behind for it to remove.
+// The lines `ensure_claude_md_import` writes. A basic project imports other rules, so an older sync,
+// or a switch from full, leaves these behind for it to remove.
 const FULL_CLAUDE_MD_LINES = new Set([
 	CLAUDE_MD_BOOTSTRAP,
 	OLD_CLAUDE_MD_BOOTSTRAP,

package/scripts/init/hook-command-rewrite.ts

@@ -2,9 +2,9 @@ import { claude_plugin_config } from './claude-plugin-config'
 import { hook_launch } from './hook-launch'
 
 // The consumer's `.claude/settings.json` runs its hooks off the published package directly, not
-// through `pnpm josh` (joshuafolkken/kit#1930, joshuafolkken/kit#2023). Two paths inside a hook
-// command are rebased onto the installed package: the hook launcher `scripts/hooks/run-hook.sh`
-// (joshuafolkken/kit#3184), which picks the bundle or the dispatcher from where it is installed, and a
+// through `pnpm josh`. Two paths inside a hook
+// command are rebased onto the installed package: the hook launcher `scripts/hooks/run-hook.sh`,
+// which picks the bundle or the dispatcher from where it is installed, and a
 // plain `pnpm josh <command>`, which becomes the `dist/josh.js` dispatcher — the published package
 // always ships `dist`, and a `pnpm` launch would only add the wrapper this exists to remove.
 //