@joshuafolkken/kit 1.1094.0 → 1.1128.0

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

@@ -1,11 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { api_outage } from '#scripts/agent/api-outage'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { lane_handoff } from '#scripts/lane/lane-handoff'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryOwner, type RunCarry } from './run-carry'
 import { run_ending } from './run-ending'
 import { run_event_stream } from './run-event-stream'
@@ -69,14 +69,6 @@ interface ParsedArguments {
 	values: Partial<Record<'epic' | 'output' | 'over' | 'owner' | 'repo', string>>
 }
 
-function read_args(argv: ReadonlyArray<string>): ParsedArguments | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true, strict: true })
-	} catch {
-		return undefined
-	}
-}
-
 // Absent owner is "no owner declared", which the carry guard reads as not provably foreign; a present
 // but malformed pid invalidates the invocation rather than silently counting unguarded.
 function to_owner(raw: string | undefined): CarryOwner | undefined {
@@ -170,7 +162,7 @@ function to_context(parsed: ParsedArguments): MergeContext | undefined {
 }
 
 function parse(argv: ReadonlyArray<string>): MergeContext | undefined {
-	const parsed = read_args(argv)
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 
 	return parsed === undefined ? undefined : to_context(parsed)
 }

package/scripts/run/run-parent-cut-hook.ts

@@ -3,6 +3,7 @@ import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
 import { cost_format } from '#scripts/cost-runtime/cost-format'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { hook_decision } from '#scripts/josh/hook-decision'
+import { error_text } from '#scripts/lib/error-message'
 import { implementation_cut_verdict } from '#scripts/rules/implementation-cut-verdict'
 import { run_carry, type RunCarry } from './run-carry'
 import { run_headless } from './run-headless'
@@ -104,7 +105,9 @@ async function refusal_for(
 function is_unit_call(raw_payload: string): boolean {
 	try {
 		return (hook_decision.parse_hook_payload(raw_payload)?.agent_id ?? '') !== ''
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('run_parent_cut_hook.is_unit_call', error)
+
 		return false
 	}
 }

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

@@ -4,6 +4,7 @@ import { git_stash } from '#scripts/git/stash/git-stash'
 import { issue_read_cli, type BlockRead } from '#scripts/issue/issue-read-cli'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { error_text } from '#scripts/lib/error-message'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_locate } from './run-prep-locate'
@@ -82,7 +83,9 @@ async function lane_has_changes(): Promise<boolean> {
 
 	try {
 		return await git_stash.has_changes(process.cwd())
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('run_prep_cli.lane_has_changes', error)
+
 		return false
 	}
 }

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

@@ -12,6 +12,12 @@ import { run_progress_config } from './run-progress-config'
 // only a heartbeat the caller restarts on the next interval, so the two guard different things and
 // only one has anything to lose by being short.
 const DEFAULT_MAX_HOURS = 1
+// **`--wait` is bounded by a run, not by three intervals** (joshuafolkken/kit#3102). It no longer exits
+// at its first report — the reports go to the event stream — so its one-hour bound would be the last
+// wake that asks the parent for no judgement, a restart an hour. Eight hours is `run:hold`'s expiry;
+// what ends a finished run's watcher sooner is `josh followup` removing its life record, and a stop
+// tearing it down in the same turn.
+const DEFAULT_WAIT_MAX_HOURS = 8
 const MS_PER_HOUR = 3_600_000
 
 const OPTIONS = {
@@ -37,7 +43,7 @@ interface ParsedValues {
 }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS })?.values
+	return cli_flags.values_of(argv, OPTIONS)
 }
 
 // A hand-typed `--interval` outranks the environment, the environment outranks the interval the
@@ -48,14 +54,24 @@ function to_interval_ms(raw: string | undefined): number {
 	return run_progress_config.resolve_interval_ms(raw)
 }
 
-function to_max_ms(raw: string | undefined): number {
+function default_hours(is_wait: boolean): number {
+	return is_wait ? DEFAULT_WAIT_MAX_HOURS : DEFAULT_MAX_HOURS
+}
+
+function to_max_ms(raw: string | undefined, is_wait = false): number {
 	const hours = Number(raw)
 	const is_usable = raw !== undefined && Number.isFinite(hours) && hours > 0
 
-	return (is_usable ? hours : DEFAULT_MAX_HOURS) * MS_PER_HOUR
+	return (is_usable ? hours : default_hours(is_wait)) * MS_PER_HOUR
 }
 
-const run_progress_args = { DEFAULT_MAX_HOURS, read_arguments, to_interval_ms, to_max_ms }
+const run_progress_args = {
+	DEFAULT_MAX_HOURS,
+	DEFAULT_WAIT_MAX_HOURS,
+	read_arguments,
+	to_interval_ms,
+	to_max_ms,
+}
 
 export type { ParsedValues }
 export { run_progress_args }

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

@@ -51,7 +51,7 @@ const TICK_SECONDS = 30
 const DECLINE_RETRY_SECONDS = 120
 // The clock a fresh loop starts with: nothing has declined yet, so nothing is being waited out.
 const NO_RETRY = 0
-const { DEFAULT_MAX_HOURS } = run_progress_args
+const { DEFAULT_WAIT_MAX_HOURS } = run_progress_args
 const ENVIRONMENT_KEY = 'JOSH_PROGRESS'
 const DISABLED_VALUE = '0'
 
@@ -74,7 +74,7 @@ const UNREADABLE_NOTICE =
 	'The `in-progress` listing could not be read, so nothing is reported. That is not "nothing is running" — check `gh auth status` and ask again.'
 const FAILED_TICK_PREFIX =
 	'A progress reading failed, so nothing is reported for it. The watcher is still running, and will read again after the cooldown:'
-const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_MAX_HOURS)} by default) ran out before the run had been quiet for a whole interval, so there is nothing to report. Starting another \`--wait\` resumes the same clock.`
+const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_WAIT_MAX_HOURS)} by default for \`--wait\`) ran out with no newly runnable work arriving. Every report it made is already on the run's event stream (\`pnpm josh run:event --watch\`), so there is nothing to relay. Starting another \`--wait\` resumes the same clock.`
 // The repository name is only ever printed, never written against, so the bounded lookup is the right
 // one: a `gh` call that hangs would otherwise block the synchronous read at startup and leave the
 // watcher neither running nor saying so.
@@ -104,6 +104,10 @@ interface WatchOptions {
 	output_paths: ReadonlyArray<string>
 	repo: string
 	tick_ms: number
+	// `--wait` alone: the line goes to the run's event stream and the ambient log, never to standard
+	// output, because a background command's output reaches the session only as a wake
+	// (joshuafolkken/kit#3102).
+	is_stream_only?: boolean
 }
 
 interface EmitContext {
@@ -202,7 +206,7 @@ async function emit(options: WatchOptions, context: EmitContext): Promise<EmitRe
 		unchanged_since_ms: state.unchanged_since_ms,
 	})
 
-	console.info(line)
+	if (options.is_stream_only !== true) console.info(line)
 
 	return { kind: 'observed', state, line }
 }
@@ -287,8 +291,8 @@ async function step(options: WatchOptions, target: string, loop: WatchLoop): Pro
 /**
  * The loop both reporting forms are, with one difference between them.
  *
- * `watch` runs until `--hours` expires; `--wait` stops at the first line it prints
- * (joshuafolkken/kit#1576). Everything else — where the clock is seeded from, the tick, the decline
+ * `watch` runs until `--hours` expires; `--wait` stops at the first arrival and keeps its lines off
+ * standard output (joshuafolkken/kit#3102). Everything else — where the clock is seeded from, the tick, the decline
  * cooldown `step` keeps — is one implementation on purpose: two copies would let a fix to the bound or
  * to the initial silence reach one form and not the other, and `--wait` is the form a run starts.
  */
@@ -301,17 +305,14 @@ function seed_loop(target: string, started_ms: number): WatchLoop {
 // Why the loop stopped, so `drive` prints the bound-expired notice only when the bound is what
 // expired — not when `josh followup` ended the watcher, which is a clean stop with nothing to report.
 // `arrived` is a `--wait` ended early by newly runnable work (joshuafolkken/kit#2503).
-type WatchExit = 'reported' | 'arrived' | 'ended' | 'bound'
+type WatchExit = 'arrived' | 'ended' | 'bound'
 
-// `wait` is present for `--wait` alone, which ends at the first line it prints or at the first arrival
-// its probe sees. `state` is set by the one branch of `step` that printed a line and by no other, so
-// this asks "was anything reported" without keeping a second copy of the loop's own bookkeeping.
-async function wait_exit(
-	loop: WatchLoop,
-	wait: ArrivalProbe | undefined,
-): Promise<WatchExit | undefined> {
+// `wait` is present for `--wait` alone, which ends at the first arrival its probe sees. **A report is
+// not an exit** (joshuafolkken/kit#3102): every exit wakes the session that started it, and a wake
+// spent relaying a line the event stream already carries is the most expensive turn a run takes, so
+// only what the parent has to act on ends the wait.
+async function wait_exit(wait: ArrivalProbe | undefined): Promise<WatchExit | undefined> {
 	if (wait === undefined) return undefined
-	if (loop.state !== undefined) return 'reported'
 
 	return (await wait.has_arrived(Date.now())) ? 'arrived' : undefined
 }
@@ -335,8 +336,8 @@ function final_exit(life: string): WatchExit {
 // The loop both reporting forms share, reading its own liveness record at the top of each pass — the
 // `run-wake-loop.ts` `run_loop` shape (joshuafolkken/kit#1727). A record gone means `josh followup`
 // removed it at the merge, so the watcher stops at once instead of waiting out its bound
-// (joshuafolkken/kit#1821); `--wait` also stops at the first line it prints, and otherwise the loop
-// runs until `--hours` expires.
+// (joshuafolkken/kit#1821); `--wait` also stops at the first arrival, and otherwise the loop runs
+// until `--hours` expires.
 async function run_ticks(
 	options: WatchOptions,
 	target: string,
@@ -354,7 +355,7 @@ async function run_ticks(
 		loop = await step(options, target, loop)
 
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		const exit = await wait_exit(loop, wait)
+		const exit = await wait_exit(wait)
 
 		if (exit !== undefined) return exit
 	}
@@ -397,14 +398,16 @@ async function once(options: WatchOptions): Promise<number> {
 }
 
 /**
- * One interval of silence, one line, and then exit — the form that reports where a long-running
- * command cannot (joshuafolkken/kit#1576).
+ * The form a run starts in the background: it reports on its own and wakes the caller only for work
+ * (joshuafolkken/kit#3102).
  *
- * **The exit is the whole point.** A harness that only delivers a background command's standard
- * output *when that command exits* — Claude Code is one — relays nothing at all from `watch`, which
- * by design never exits: `epicrun #1474` was measured at 2h36m without a single progress line while
- * children were in flight. This form waits the same clock out and then ends, so the line it printed
- * is delivered; the caller relays it and starts the next one.
+ * **A report is not a wake.** It once ended at its first line so a harness that delivers a background
+ * command's output only on exit would relay it (joshuafolkken/kit#1576) — which cost the orchestrating
+ * session one turn per heartbeat, re-reading a hundred thousand tokens of context to pass on a line it
+ * was forbidden to change. Every line already reaches the run's event stream as a `heartbeat` and the
+ * ambient log, which a person's `run:event --watch` pane reads with no model in between, so this form
+ * keeps its lines off standard output and exits only on an arrival, on `josh followup` ending its life
+ * record, or on its bound. The caller starts it once and restarts it only after one of those.
  *
  * **The clock is still this command's, not the caller's.** It is the watch loop itself, a tick at a
  * time, rather than a second reading of the same record — so a real report elsewhere pushes the next
@@ -419,10 +422,10 @@ async function once(options: WatchOptions): Promise<number> {
  * carried budget, no lane, and no `in-progress` child — so a genuinely idle repository keeps the loop
  * waiting instead of ending it; returning there would hand the caller an instant answer to restart,
  * and the documented restart makes that a poll rather than a heartbeat. Once a run has started the
- * loop reports and exits even before the first child carries `in-progress` (joshuafolkken/kit#1900).
+ * loop reports even before the first child carries `in-progress` (joshuafolkken/kit#1900).
  */
 async function wait_once(options: WatchOptions): Promise<number> {
-	return await drive(options, true)
+	return await drive({ ...options, is_stream_only: true }, true)
 }
 
 async function mark_now(): Promise<number> {
@@ -448,7 +451,7 @@ function to_options(values: ParsedValues): WatchOptions | undefined {
 
 	return {
 		interval_ms: run_progress_args.to_interval_ms(values.interval),
-		max_ms: run_progress_args.to_max_ms(values.hours),
+		max_ms: run_progress_args.to_max_ms(values.hours, values.wait === true),
 		output_paths: values.output ?? [],
 		repo,
 		tick_ms: TICK_SECONDS * run_progress.MS_PER_SECOND,
@@ -494,7 +497,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const run_progress_cli = {
-	DEFAULT_MAX_HOURS,
+	DEFAULT_WAIT_MAX_HOURS,
 	DISABLED_NOTICE,
 	FAILED_TICK_PREFIX,
 	FRESH_LOOP,
@@ -508,7 +511,6 @@ const run_progress_cli = {
 	run,
 	step,
 	to_interval_ms: run_progress_args.to_interval_ms,
-	to_max_ms: run_progress_args.to_max_ms,
 	wait_once,
 }
 

package/scripts/run/run-progress-clock.ts

@@ -1,5 +1,6 @@
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { error_text } from '#scripts/lib/error-message'
 import { z } from 'zod'
 
 // The report clock `josh run:progress` keeps, in the one form both of its readers can use
@@ -232,7 +233,9 @@ function is_life_fresh(target: string, threshold_ms: number): boolean {
 		const pinged_ms = parse_pinged_at(raw)
 
 		return pinged_ms !== undefined && Date.now() - pinged_ms < threshold_ms
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('run_progress_clock.is_life_fresh', error)
+
 		return false
 	}
 }

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
 import { run_ship, type ShipSection } from './run-ship'
@@ -121,13 +121,6 @@ interface ParsedValues extends NotifyValues {
 	cite?: Array<string>
 }
 
-function parse_values(argv: ReadonlyArray<string>): {
-	values: ParsedValues
-	positionals: Array<string>
-} {
-	return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true, strict: true })
-}
-
 function ship_args(
 	title: string,
 	rest: ReadonlyArray<string>,
@@ -155,9 +148,10 @@ function log_command(number: string, positionals: ReadonlyArray<string>): ShipCo
 	return CITE_PATTERN.test(number) && positionals.length === 0 ? { kind: 'log', number } : undefined
 }
 
-function read_args(argv: ReadonlyArray<string>): ShipCommand | undefined {
-	const { values, positionals } = parse_values(argv)
-
+function command_of(
+	values: ParsedValues,
+	positionals: ReadonlyArray<string>,
+): ShipCommand | undefined {
 	if (values.log !== undefined) return log_command(values.log, positionals)
 
 	const title = positionals[FIRST]
@@ -170,11 +164,9 @@ function read_args(argv: ReadonlyArray<string>): ShipCommand | undefined {
 // Numbers-only tail and a strict parse, so a title with no `#<N>` or a stray flag is refused rather
 // than shipped past the wrong step.
 function parse(argv: ReadonlyArray<string>): ShipCommand | undefined {
-	try {
-		return read_args(argv)
-	} catch {
-		return undefined
-	}
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	return parsed === undefined ? undefined : command_of(parsed.values, parsed.positionals)
 }
 
 async function run_step(step: Step, args: ShipArguments, state: ShipState): Promise<ShipSection> {

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

@@ -1,5 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { error_text } from '#scripts/lib/error-message'
 import { run_hold } from './run-hold'
 import { run_preflight } from './run-preflight'
 import { run_ship_stage, type ShipState } from './run-ship-stage'
@@ -20,7 +21,9 @@ const HEAD_REFERENCE = 'HEAD'
 async function or_false(is_true: () => Promise<boolean>): Promise<boolean> {
 	try {
 		return await is_true()
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('run_ship_probe.or_false', error)
+
 		return false
 	}
 }

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

@@ -1,8 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryRead } from './run-carry'
 import { run_status, type StatusParts } from './run-status'
 
@@ -41,19 +41,6 @@ interface StatusReads {
 	cost: CostVerdict
 }
 
-interface ParsedArguments {
-	positionals: ReadonlyArray<string>
-	values: { repo?: string }
-}
-
-function read_args(argv: ReadonlyArray<string>): ParsedArguments | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true, strict: true })
-	} catch {
-		return undefined
-	}
-}
-
 // Exactly one issue number, or the call is refused: `run:status` reports one run, and a second number
 // would print a second issue's state a caller reads as this run's own.
 function valid_issue(positionals: ReadonlyArray<string>): string | undefined {
@@ -65,7 +52,7 @@ function valid_issue(positionals: ReadonlyArray<string>): string | undefined {
 }
 
 function parse(argv: ReadonlyArray<string>): StatusRequest | undefined {
-	const parsed = read_args(argv)
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 
 	if (parsed === undefined) return undefined
 

package/scripts/run/run-tidy-lanes.ts

@@ -2,6 +2,7 @@ import { git_spawn } from '#scripts/git/git-spawn'
 import { git_stash } from '#scripts/git/stash/git-stash'
 import { lane_close } from '#scripts/lane/lane-close'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { error_text } from '#scripts/lib/error-message'
 import { run_hold } from './run-hold'
 import { run_tidy, type Outcome, type Verdict } from './run-tidy'
 
@@ -31,7 +32,9 @@ async function has_unpushed(directory: string): Promise<boolean> {
 		])
 
 		return count !== '0'
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('run_tidy_lanes.has_unpushed', error)
+
 		return true
 	}
 }

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

@@ -119,14 +119,6 @@ function note_to_stderr(note: string): void {
 	console.error(`wake: ${note}`)
 }
 
-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: string | boolean | undefined): string | undefined {
-	return typeof value === 'string' ? value : undefined
-}
-
 function to_interval_ms(value: string | boolean | undefined): number | undefined {
 	if (typeof value !== 'string') return DEFAULT_INTERVAL_SECONDS * MS_PER_SECOND
 	if (!INTERVAL_PATTERN.test(value)) return undefined
@@ -379,14 +371,14 @@ async function dispatch(
 	interval_ms: number,
 ): Promise<number> {
 	if (values.loop === true) return await loop(context, interval_ms)
-	if (values.start === true) return start(context, text_of(values.interval))
+	if (values.start === true) return start(context, cli_flags.string_of(values.interval))
 	if (values.stop === true) return stop_supervisor(context)
 
 	return list(context)
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const values = read_arguments(argv)
+	const values = cli_flags.values_of(argv, OPTIONS)
 
 	if (values === undefined || group_count(values) !== ONE_GROUP) return usage()
 

package/scripts/run/run-watcher-guard.ts

@@ -2,13 +2,15 @@ import { lane_registry } from '#scripts/lane/lane-registry'
 import { run_headless } from './run-headless'
 import { run_progress_clock } from './run-progress-clock'
 
-// A watcher that stopped while children are still in-flight leaves the parent blind to completions
-// for up to the full heartbeat interval. This guard detects that state so a hook can refuse the
-// calls that follow a missed restart (joshuafolkken/kit#2113).
+// A watcher that stopped while children are still in-flight leaves the run's event stream without a
+// heartbeat and the parent without the wake an arrival would deliver. This guard detects that state so
+// a hook can refuse the calls that follow a missed restart (joshuafolkken/kit#2113).
 //
 // **Staleness threshold is `TICK_MULTIPLIER` watcher ticks.** The watcher pings its life record on
 // every tick (every 30 s), so a gap wider than three ticks means the process has almost certainly
-// stopped: either the bound expired or the session was cut without a restart. Three gives one missed
+// stopped: it exited on an arrival, its bound expired, or the session was cut without a restart. A
+// report is no longer one of those (joshuafolkken/kit#3102) — `--wait` streams its reports and keeps
+// running — so a restart is owed only after an exit the parent was woken for. Three gives one missed
 // tick of slack before the guard fires.
 //
 // **It watches no relay** (joshuafolkken/kit#2492). A session following the run's event stream after a
@@ -24,7 +26,9 @@ const STALE_THRESHOLD_S = STALE_THRESHOLD_MS / MS_PER_SECOND
 
 const STALE_NOTE =
 	`Lane children are in-flight but the progress watcher has not pinged in the last ` +
-	`${String(STALE_THRESHOLD_S)}s — run \`pnpm josh run:progress --wait\` in the background before proceeding`
+	`${String(STALE_THRESHOLD_S)}s — run \`pnpm josh run:progress --wait\` in the background before proceeding. ` +
+	'It reports to the run event stream on its own and exits only when newly runnable work arrives, so ' +
+	'start it once and relay nothing'
 
 type GuardResult = { kind: 'ok' } | { kind: 'stale'; note: string }
 

package/scripts/safe-chain/pack-hook.ts

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs'
+import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
+import { file_content } from '#scripts/sync/file-content'
+import { z } from 'zod'
+
+// kit writes the Safe Chain `preinstall` into every project it sets up, and a package that publishes
+// would ship it: the consumer's pnpm then refuses it as an unapproved build script and `pnpm add`
+// exits 1 (joshuafolkken/kit#3110). kit's own `.pnpmfile.mjs` strips it at pack time
+// (joshuafolkken/kit#2693), so that one file is what a publishing project receives — never a copy of
+// its logic.
+//
+// A private package is left alone: it never packs, and a new pnpmfile changes the lockfile's
+// `pnpmfileChecksum`, which fails a frozen install until the lockfile is refreshed.
+const PACK_HOOK_FILE = '.pnpmfile.mjs'
+const MANAGED_LINE = '// josh-managed-pnpmfile: @joshuafolkken/kit'
+const MANIFEST_FILE = 'package.json'
+// pnpm loads `.pnpmfile.mjs` in preference to `.pnpmfile.cjs`, and neither once a `pnpmfile` setting
+// names another file — so writing ours beside either would silently drop the project's hooks, or
+// report a hook pnpm never runs.
+const LEGACY_HOOK_FILE = '.pnpmfile.cjs'
+const CONFIG_FILES: ReadonlyArray<string> = ['pnpm-workspace.yaml', '.npmrc']
+const PNPMFILE_SETTINGS: ReadonlySet<string> = new Set(['pnpmfile', 'pnpmfiles'])
+const SETTING_KEY_END = /[\s:=]/u
+const manifest_schema = z.looseObject({ private: z.boolean().optional() })
+
+type PackHookResult = 'written' | 'unchanged' | 'private' | 'owned' | 'withdrawn'
+
+function is_published(manifest_text: string): boolean {
+	return manifest_schema.parse(JSON.parse(manifest_text)).private !== true
+}
+
+function sets_pnpmfile(config_text: string): boolean {
+	return config_text
+		.split('\n')
+		.some((line) => PNPMFILE_SETTINGS.has(line.trimStart().split(SETTING_KEY_END, 1)[0] ?? ''))
+}
+
+function has_own_hook_source(project_root: string): boolean {
+	if (existsSync(path.join(project_root, LEGACY_HOOK_FILE))) return true
+
+	return CONFIG_FILES.some((name) =>
+		sets_pnpmfile(file_reader.read_file_or_empty(path.join(project_root, name))),
+	)
+}
+
+function write_hook(destination: string, package_directory: string): PackHookResult {
+	const source = readFileSync(path.join(package_directory, PACK_HOOK_FILE), 'utf8')
+
+	return file_content.write_text_if_changed(destination, source) ? 'written' : 'unchanged'
+}
+
+// A copy kit wrote before the project added its own pnpmfile would still shadow that one.
+function withdraw(destination: string, existing: string | undefined): PackHookResult {
+	if (existing === undefined) return 'owned'
+	rmSync(destination)
+
+	return 'withdrawn'
+}
+
+// A pnpmfile without the managed line is the project's own; overwriting it would drop its hooks.
+function apply(project_root: string, package_directory: string): PackHookResult {
+	const destination = path.join(project_root, PACK_HOOK_FILE)
+	const existing = file_reader.read_optional(destination)
+	if (existing !== undefined && !existing.startsWith(MANAGED_LINE)) return 'owned'
+	if (has_own_hook_source(project_root)) return withdraw(destination, existing)
+
+	return write_hook(destination, package_directory)
+}
+
+const MESSAGES: Readonly<Record<PackHookResult, string | undefined>> = {
+	written: `  ✔ synced    ${PACK_HOOK_FILE} (run \`pnpm install\` to refresh pnpmfileChecksum)`,
+	unchanged: `  ✔ unchanged ${PACK_HOOK_FILE}`,
+	private: undefined,
+	owned: `  ⚠ skipped   ${PACK_HOOK_FILE} — the project has its own pnpmfile; strip the safe-chain preinstall at pack time there`,
+	withdrawn: `  ⚠ removed   ${PACK_HOOK_FILE} — it shadowed the project's own pnpmfile; strip the safe-chain preinstall at pack time there`,
+}
+
+function sync_pack_hook(project_root: string, package_directory: string): PackHookResult {
+	const manifest_text = file_reader.read_optional(path.join(project_root, MANIFEST_FILE))
+	const is_private = manifest_text === undefined || !is_published(manifest_text)
+	const result = is_private ? 'private' : apply(project_root, package_directory)
+	const message = MESSAGES[result]
+	if (message !== undefined) console.info(message)
+
+	return result
+}
+
+const pack_hook = { MANAGED_LINE, sync_pack_hook }
+
+export { pack_hook, PACK_HOOK_FILE }
+export type { PackHookResult }

package/scripts/sync/sync-ai-files.ts

@@ -6,6 +6,7 @@ import { init_logic } from '#scripts/init/init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import type { ProjectShape } from '#scripts/init/project-profile'
 import { file_reader } from '#scripts/lib/read-file'
+import { pack_hook } from '#scripts/safe-chain/pack-hook'
 import { copy_directory_failure, directory_copy_blocker } from './directory-copy-guard'
 import { file_content } from './file-content'
 import { REMOVED_SKILL_MANIFEST } from './removed-skill-manifest'
@@ -189,6 +190,9 @@ function sync_ai_copy_all(is_force: boolean, shape?: ProjectShape): void {
 	}
 
 	migrate_removed_skills()
+	// Both profiles write the Safe Chain `preinstall`, so both get the hook that keeps it out of a
+	// published package (joshuafolkken/kit#3110).
+	pack_hook.sync_pack_hook(PROJECT_ROOT, PACKAGE_DIR)
 }
 
 const sync_ai_files = {

package/scripts/test/test-declared-changed.ts

@@ -1,5 +1,6 @@
-import { execFileSync } from 'node:child_process'
 import { project_checks } from '#scripts/gate/project-checks'
+import { PORCELAIN_FLAG } from '#scripts/git/constants'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { test_declared_logic, type Verdict } from './test-declared-logic'
 
 // The working-tree change set and the verdict over it, read **synchronously** for the `PreToolUse`
@@ -30,21 +31,17 @@ function path_of(line: string): string {
 }
 
 function read_changed_paths_sync(): Array<string> {
-	try {
-		// stderr is discarded: outside a repository git prints `fatal: not a git repository`, which the
-		// catch below already handles as an empty change set — surfacing it would only be noise.
-		const output = execFileSync('git', ['status', '--porcelain'], {
-			encoding: 'utf8',
-			stdio: ['ignore', 'pipe', 'ignore'],
-		})
-
-		return output
-			.split('\n')
-			.filter((line) => line.length > STATUS_PREFIX_LENGTH)
-			.map((line) => path_of(line))
-	} catch {
-		return []
-	}
+	// Outside a repository git fails with `fatal: not a git repository`, which reads as an empty change
+	// set; its stderr is captured rather than surfaced, since it would only be noise.
+	// Unbounded (`timeout: 0`) on purpose: a timed-out status would read as an empty change set, and so
+	// as `exempt`, letting an untested runtime change through on a slow checkout.
+	const output = git_spawn_sync.run(['status', PORCELAIN_FLAG], { timeout: 0 })
+	if (output.exit_code !== 0) return []
+
+	return output.stdout
+		.split('\n')
+		.filter((line) => line.length > STATUS_PREFIX_LENGTH)
+		.map((line) => path_of(line))
 }
 
 // The working-tree read behind `current_verdict`, injectable so the delivery path can be exercised