@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -6,8 +6,7 @@ import { time_followup_stage } from './time-followup-stage'
 import { time_instant } from './time-instant'
 import { time_reported_failure } from './time-reported-failure'
 
-// One line of a session transcript, read into the shape the span walk works on
-// (joshuafolkken/kit#1406).
+// One line of a session transcript, read into the shape the span walk works on.
 //
 // It moved out of `time-spans.ts` when that file passed its length limit — the seam that file is
 // already cut along elsewhere (`time-shell.ts`, `time-single-check.ts`), where the *reading* of a
@@ -27,22 +26,22 @@ const BLOCK_SCHEMA = z.object({
 
 	tool_use_id: z.string().nullish(),
 	input: z.unknown().nullish(),
-	// Whether the harness wrote this result back as a failure (joshuafolkken/kit#1309). Present on a
+	// Whether the harness wrote this result back as a failure. Present on a
 	// `tool_result` block and on nothing else, and absent even there for the tools that never report
 	// one — which is why it is read as three answers rather than as a boolean with a default.
 	is_error: z.boolean().nullish(),
-	// What the call printed. Read only to recover the outcome a pipeline threw away
-	// (joshuafolkken/kit#1361): it is kept as flattened text rather than as blocks, because that is
+	// What the call printed. Read only to recover the outcome a pipeline threw away:
+	// it is kept as flattened text rather than as blocks, because that is
 	// the whole of what `time-reported-failure.ts` asks of it.
 	content: z.unknown().nullish(),
 })
 
 const CONTENT_SCHEMA = z.union([z.string(), z.array(BLOCK_SCHEMA)])
 // `id` is the assistant *message* the line belongs to, and Claude Code writes one line per content
-// block — a turn that thought and then issued two calls is three lines carrying one id
-// (joshuafolkken/kit#1329). Anything asking "how many calls did that turn make" therefore has to
-// group by this field; counting one line's blocks answers one, whatever the turn actually did. Since
-// joshuafolkken/kit#1406 the same field is what says how many *turns* a run had.
+// block — a turn that thought and then issued two calls is three lines carrying one id.
+// Anything asking "how many calls did that turn make" therefore has to
+// group by this field; counting one line's blocks answers one, whatever the turn actually did. The
+// same field is what says how many *turns* a run had.
 const MESSAGE_SCHEMA = z.object({ id: z.string().nullish(), content: CONTENT_SCHEMA.nullish() })
 
 const LINE_SCHEMA = z.object({
@@ -50,10 +49,10 @@ const LINE_SCHEMA = z.object({
 	timestamp: z.string().nullish(),
 	// The branch the line was written on, which is where the issue number lives — `josh git` names a
 	// branch `<N>-<slug>`. Read here rather than re-parsed by a second reader so `josh time --issue`
-	// and `josh cost --issue` answer from the same field (joshuafolkken/kit#1268).
+	// and `josh cost --issue` answer from the same field.
 	gitBranch: z.string().nullish(),
-	// The two fields outside `message` that the harness writes an end-of-task notice on
-	// (joshuafolkken/kit#1696). **Both are read as `unknown` rather than as strings**: a schema
+	// The two fields outside `message` that the harness writes an end-of-task notice on.
+	// **Both are read as `unknown` rather than as strings**: a schema
 	// insisting on a string here would reject every line whose `content` is a list of blocks — which is
 	// most of them — and a rejected line is dropped from the timeline entirely, so the shares would stop
 	// reconstructing the elapsed time. The shape is checked at the read below instead.
@@ -63,17 +62,14 @@ const LINE_SCHEMA = z.object({
 })
 
 const UNKNOWN_BRANCH = ''
-// The field an attachment line carries the notice in. Named rather than written as a literal for the
-// reason `time-background.ts`'s `BASH_ID_KEY` is: `dot-notation` rewrote `record['prompt']` into
-// `record.prompt`, which a value read as an index-signature record does not have — until
-// joshuafolkken/kit#1783 switched that fix off. The name is kept for its own sake.
+// The field an attachment line carries the notice in, named rather than written as a literal.
 const PROMPT_KEY = 'prompt'
 const NO_MESSAGE_ID = ''
-// How much of an errored body is kept (joshuafolkken/kit#1642). A refusal's body *is* the reason the
+// How much of an errored body is kept. A refusal's body *is* the reason the
 // harness wrote back, from its first character, so an opening this long identifies the speaker
 // without retaining the output of every failed command a session ran.
 const ERROR_TEXT_LIMIT = 256
-// The icon every guard refusal opens with (joshuafolkken/kit#1913). It is not `status_icons.FAIL_ICON`
+// The icon every guard refusal opens with. It is not `status_icons.FAIL_ICON`
 // — that one (`✗`) marks a josh check's failing item, which `has_failure_line` scans for; this one
 // marks a PreToolUse hook's *deny* reason, which is a different body carried in a different result. No
 // shared constant exists because each guard writes the literal in its own reason, so the one place a
@@ -81,8 +77,11 @@ const ERROR_TEXT_LIMIT = 256
 const REFUSAL_MARKER = '⛔'
 // The label the harness puts in front of a PreToolUse hook's deny reason, naming the hook and the tool.
 const HOOK_ERROR_LABEL = /^PreToolUse:\S+ hook error: /u
+// The label the harness puts in front of a Stop hook's block reason when it sends the turn back.
+// The reason follows on the next line, opening with the same `⛔` a deny does.
+const STOP_FEEDBACK_LABEL = /^Stop hook feedback:\s*/u
 // A line that is one bare verdict token — `cut`, `busy`, `not-a-lane` — the single word a josh verdict
-// command prints on standard output (joshuafolkken/kit#3223). How many are kept bounds the field the
+// command prints on standard output. How many are kept bounds the field the
 // way `ERROR_TEXT_LIMIT` bounds `error_text`.
 const TOKEN_LINE = /^[a-z][a-z-]*$/u
 const TOKEN_LINE_LIMIT = 8
@@ -97,40 +96,40 @@ interface Block {
 	// `false`: one is a tool that reports no outcome, the other a call that succeeded.
 	is_error: boolean | undefined
 	// Whether the body carried a line opening with josh's failure icon — the one bit of it anything
-	// reads (joshuafolkken/kit#1361). The text itself is deliberately not kept: a field holding it
+	// reads. The text itself is deliberately not kept: a field holding it
 	// would retain every byte the session's tools printed for the length of the parse.
 	has_failure_line: boolean
-	// The stage rows a `pnpm josh followup` call printed into its own output
-	// (joshuafolkken/kit#1445). Read here for the same reason the bit above is, and it obeys the same
+	// The stage rows a `pnpm josh followup` call printed into its own output.
+	// Read here for the same reason the bit above is, and it obeys the same
 	// prohibition: what is kept is the ten-odd parsed laps, never the body they were read from. Empty
 	// for every other tool result, which is nearly all of them.
 	followup_stages: ReadonlyArray<FollowupStage>
 	// The opening of the body of a result the harness wrote back as a failure, and `''` for every
-	// other block (joshuafolkken/kit#1642). It obeys the same prohibition as the two fields above —
+	// other block. It obeys the same prohibition as the two fields above —
 	// what is kept is a bounded opening, never the whole body — and it exists so a reader asking
 	// which refusal a line carried can be answered from the parsed block rather than by matching
 	// `"is_error":true` against the raw line, a test one whitespace in the serializer defeats and
 	// which cannot tell one errored block from another on the same line.
 	error_text: string
 	// Which guard refused this call, read off the opening of an errored result and `''` for every other
-	// block (joshuafolkken/kit#1913). It obeys the same prohibition as `error_text` — what is kept is a
+	// block. It obeys the same prohibition as `error_text` — what is kept is a
 	// short label, never the body — and it exists so the per-guard refusal breakdown can be answered from
 	// the parsed block rather than by re-scanning the body downstream. `''` where the result was not a
 	// `⛔` refusal, so a reader tells "no guard spoke" from "this guard spoke" without a second parse.
 	refusal_guard: string
-	// The bare-token lines of a result that did not fail, and `[]` for every other block
-	// (joshuafolkken/kit#3223). It obeys the same prohibition as `error_text` — what is kept is a few
+	// The bare-token lines of a result that did not fail, and `[]` for every other block.
+	// It obeys the same prohibition as `error_text` — what is kept is a few
 	// single words, never the body — and it exists so the verdict a josh command answered with
 	// (`run:cut`'s `cut`) is read from the parsed block rather than by searching the raw line.
 	token_lines: ReadonlyArray<string>
 	// The id the harness assigned to a command it took into the background, and `''` for every other
-	// block (joshuafolkken/kit#1662). It is the fourth field read off the body under the same
+	// block. It is the fourth field read off the body under the same
 	// prohibition as the three above — what is kept is the id, never the text it was read from — and
 	// it is what pairs a launch with the call that later reads its output, so the minutes the command
 	// actually ran can be placed on the timeline instead of only the seconds its launch call took.
 	background_id: string
 	// The id of a subagent this block launched into the background, and `''` for every other block
-	// (joshuafolkken/kit#2774) — apart from `background_id` so the timeline windows stay commands only.
+	// — apart from `background_id` so the timeline windows stay commands only.
 	agent_id: string
 }
 
@@ -139,7 +138,7 @@ interface TranscriptLine {
 	timestamp_ms: number
 	branch: string
 	// The background run this line is the harness's end-of-task notice for, and `''` for every other
-	// line (joshuafolkken/kit#1696). It is read here rather than downstream for the reason every
+	// line. It is read here rather than downstream for the reason every
 	// derived field above is: the notice is the line's whole content, which a span does not keep, and
 	// it is the only thing in a transcript that says a command had *finished* rather than merely been
 	// looked at.
@@ -149,6 +148,9 @@ interface TranscriptLine {
 	// every line lacking an id would otherwise fall into one bucket spanning the whole file.
 	message_id: string
 	blocks: Array<Block>
+	// The guard whose Stop-hook block sent this turn back, or `''` for every other line
+	// — read the way `Block.refusal_guard` is, off the reason's opening.
+	stop_guard: string
 }
 
 // The four string fields, defaulted together and apart from the two that are not strings. Split out
@@ -165,15 +167,15 @@ function block_names(
 	}
 }
 
-// **A refusal is identified by what its body opens with, never by what it carries inside**
-// (joshuafolkken/kit#1913). The hook denies a call on behalf of the one guard whose trigger fired and
+// **A refusal is identified by what its body opens with, never by what it carries inside**.
+// The hook denies a call on behalf of the one guard whose trigger fired and
 // writes that guard's reason back as the whole result, so the speaker is the token after the `⛔` and
 // before the first `:` — `⛔ pre-gate cut: …` is `pre-gate cut`. A reason with no colon (a headline
 // like `⛔ scoped checks not green on this tree`) is taken whole. Reading the opening rather than
 // searching the body is what stops a result that merely quoted a reason being read as a refusal.
 //
 // **The harness writes the reason behind its own label** — `PreToolUse:Edit hook error: ⛔ …` — so that
-// label is stripped before the opening is read (joshuafolkken/kit#3223). Without it no live refusal
+// label is stripped before the opening is read. Without it no live refusal
 // carried a guard: the fixtures wrote the bare `⛔` body and passed while every recorded one read `''`.
 function guard_from_refusal(text: string): string {
 	const trimmed = text.trimStart().replace(HOOK_ERROR_LABEL, '')
@@ -185,6 +187,16 @@ function guard_from_refusal(text: string): string {
 	return (colon === -1 ? headline : headline.slice(0, colon)).trim()
 }
 
+// **Only the harness's own feedback line counts.** It writes a Stop block back as a user turn whose
+// whole body is `Stop hook feedback:` and the reason, so a prompt that merely quotes one never opens
+// with the label and reads `''`.
+function stop_guard_of(data: z.infer<typeof LINE_SCHEMA>): string {
+	const content = data.message?.content
+	if (typeof content !== 'string' || !STOP_FEEDBACK_LABEL.test(content)) return ''
+
+	return guard_from_refusal(content.replace(STOP_FEEDBACK_LABEL, ''))
+}
+
 function token_lines_of(text: string): Array<string> {
 	return text
 		.split('\n')
@@ -196,7 +208,7 @@ function token_lines_of(text: string): Array<string> {
 // **The body is flattened once and both readers are handed the text.** `result_text` is what turns a
 // content field that may be a string or a list of blocks into one string, and it is idempotent on a
 // string — so passing its own output back to `has_failure_line` reads exactly as passing the raw
-// field did, at one flattening instead of two (joshuafolkken/kit#1445).
+// field did, at one flattening instead of two.
 function to_block(raw: z.infer<typeof BLOCK_SCHEMA>): Block {
 	const text = time_reported_failure.result_text(raw.content)
 	const is_error = raw.is_error ?? undefined
@@ -235,7 +247,7 @@ function message_fields(
 }
 
 // **One notice reaches the transcript on any of three line kinds, and which of them a session holds
-// varies** (joshuafolkken/kit#1696). The harness writes it on a `queue-operation` line when the notice
+// varies**. The harness writes it on a `queue-operation` line when the notice
 // is generated, on an `attachment` line when it is delivered, and on a `user` line where it enters the
 // conversation — and a run measured against one carrier alone came back unmeasured whenever the
 // session happened to hold a different one. All three are read, and `time_background.finished_at`
@@ -260,6 +272,7 @@ function to_line(data: z.infer<typeof LINE_SCHEMA>): TranscriptLine | undefined
 		timestamp_ms,
 		branch: data.gitBranch ?? UNKNOWN_BRANCH,
 		finished_background: time_background.finished_id(notice_text(data)),
+		stop_guard: stop_guard_of(data),
 		...message_fields(data.message),
 	}
 }
@@ -270,12 +283,18 @@ function parse_line(line: string): TranscriptLine | undefined {
 	return parsed.success ? to_line(parsed.data) : undefined
 }
 
+// A whole transcript's text read as its parsed lines, the unparseable ones dropped.
+function parse_text(text: string): Array<TranscriptLine> {
+	return text.split('\n').flatMap((line) => parse_line(line) ?? [])
+}
+
 const time_transcript_line = {
 	ERROR_TEXT_LIMIT,
 	NO_MESSAGE_ID,
 	TOKEN_LINE_LIMIT,
 	guard_from_refusal,
 	parse_line,
+	parse_text,
 }
 
 export type { Block, TranscriptLine }

package/scripts/time-runtime/time-writes.ts

@@ -1,7 +1,7 @@
 import { time_bundle_call } from './time-bundle-call'
 import { time_markers } from './time-markers'
 
-// Which files one tool call **wrote** (joshuafolkken/kit#1472).
+// Which files one tool call **wrote**.
 //
 // **A span keeps no tool input**, so anything read off the input has to be read while the input is
 // still in hand — the reason `marker`, `targets` and `check_key` are already carried on `ToolCall`
@@ -22,11 +22,11 @@ import { time_markers } from './time-markers'
 // **This module is the one place that answers the question**, so the two callers cannot come to
 // disagree about it, and it reuses the extraction `time-bundle-call.ts` already owns rather than
 // writing a second one: `tool_targets` for a tool's own path fields, `targets_in` for a shell line.
-// Nothing here widens `BUNDLEABLE_TOOLS` — that set is what the batching measurement of
-// joshuafolkken/kit#1390 is defined over, and a call that writes is deliberately not bundleable.
+// Nothing here widens `BUNDLEABLE_TOOLS` — that set is what the batching measurement is
+// defined over, and a call that writes is deliberately not bundleable.
 
-// **Whether a line is an in-place `sed` is `time-bundle-call.ts`'s answer, not a second one here**
-// (joshuafolkken/kit#1509). That module needs the same test as a boolean for the batching sequences,
+// **Whether a line is an in-place `sed` is `time-bundle-call.ts`'s answer, not a second one here**.
+// That module needs the same test as a boolean for the batching sequences,
 // and while the two were written separately they disagreed in both directions at once — one read the
 // whole line, so a piped `grep -i` made a read into a write; the other missed a bundled `sed -ni`, so
 // one span could carry `writes: ['x.ts']` beside `is_writing: false`. The segment scoping and the

package/scripts/ui/ui-routes-cli.ts

@@ -7,8 +7,7 @@ import { git_command } from '#scripts/git/git-command'
 import { file_reader } from '#scripts/lib/read-file'
 import { ui_routes } from './ui-routes'
 
-// `josh ui:routes [--staged]` — list the screenshot-target routes the current change touches
-// (joshuafolkken/kit#2182).
+// `josh ui:routes [--staged]` — list the screenshot-target routes the current change touches.
 //
 // The derivation lives in `ui-routes.ts`; this file is the I/O around it: read the changed paths
 // (the branch diff, or the staged diff with `--staged`), and resolve a shared component to the routes

package/scripts/ui/ui-routes.ts

@@ -1,5 +1,4 @@
-// The screenshot-target routes a change touches, derived from the diff rather than chosen by eye
-// (joshuafolkken/kit#2182).
+// The screenshot-target routes a change touches, derived from the diff rather than chosen by eye.
 //
 // The `verify-ui` skill's §1 asked the reader to read `git diff` and name the routes whose
 // components, styles or copy it touches — but in SvelteKit a file path maps to a route path

package/scripts/version/bump-version.ts

@@ -25,7 +25,7 @@ function package_json_path(): string {
 
 // **Set the version to an already-decided number.** `bump_version` below is this plus the decision;
 // `pnpm josh release` supplies its own, because a release raises the version by as many minors as
-// main has taken merges rather than by one (joshuafolkken/kit#1169). Written once so the two agree
+// main has taken merges rather than by one. Written once so the two agree
 // on the file's shape and indentation.
 function write_version(new_version: string): void {
 	const package_path = package_json_path()

package/scripts/version/fresh-metadata-cache.ts

@@ -16,8 +16,8 @@ function with_cache_directory(
 
 // A cached metadata file written through safe-chain lacks every version that was under 24 hours old
 // at the time, and with `minimumReleaseAge` set pnpm reuses a cache file younger than that age
-// instead of refetching it — so a version that has since aged in stays invisible for up to a day
-// (joshuafolkken/kit#2805). A fresh directory per run means nothing filtered earlier is ever read.
+// instead of refetching it — so a version that has since aged in stays invisible for up to a day.
+// A fresh directory per run means nothing filtered earlier is ever read.
 function run_in_fresh_cache<T>(
 	stages: ReadonlyArray<ReadonlyArray<string>>,
 	run_stages: (stages: Array<Array<string>>) => T,

package/scripts/version/latest-corepack.ts

@@ -5,34 +5,34 @@
  * The target version is resolved from the registry's publish timestamps
  * (`pnpm view pnpm time --json`) instead of a dist-tag, because pnpm publishes its
  * per-major tag `latest-<major>` only for SUPERSEDED majors — while <major> is the newest
- * major, the only tag covering it is `latest` (kit#750). The former `latest-<major>` pin
- * (kit#444) therefore failed on every run in the common case, and `latest` itself can
- * momentarily point below the devEngines floor. Picking the newest registry version whose
- * major equals the `packageManager` pin keeps both invariants: never below the adopted
- * major, and advancing while that major is the current one.
+ * major, the only tag covering it is `latest`, so a `latest-<major>` pin would fail on every
+ * run in the common case, and `latest` itself can momentarily point below the devEngines
+ * floor. Picking the newest registry version whose major equals the `packageManager` pin keeps
+ * both invariants: never below the adopted major, and advancing while that major is the
+ * current one.
  *
- * The `minimumReleaseAge` quarantine is applied natively from `pnpm-workspace.yaml` (kit#768,
- * #3267). safe-chain filters the registry only when the process tree was launched through one
- * of its wrapped shell commands, so `josh latest` and `pnpm josh latest` used to resolve
- * different answers and the pin oscillated. Reading the window from the repo-managed
+ * The `minimumReleaseAge` quarantine is applied natively from `pnpm-workspace.yaml`.
+ * safe-chain filters the registry only when the process tree was launched through one of its
+ * wrapped shell commands, so `josh latest` and `pnpm josh latest` would resolve different
+ * answers and the pin would oscillate. Reading the window from the repo-managed
  * `pnpm-workspace.yaml` and filtering by publish timestamp makes the resolution identical in
  * every invocation context; right after a pnpm release the answer is simply the previous
- * release, exactly as the filtered view behaved.
+ * release, exactly as the filtered view behaves.
  *
  * The resolved version is floored at the current `packageManager` pin: a filtered registry
  * view legitimately answers below a freshly adopted pin for the first 24 hours after every
- * pnpm release, and writing that answer would downgrade the protected toolchain pin
- * (kit#766). Not-newer answers skip the bump non-fatally instead.
+ * pnpm release, and writing that answer would downgrade the protected toolchain pin.
+ * Not-newer answers skip the bump non-fatally instead.
  *
  * `devEngines.packageManager.version` is realigned with the `packageManager` pin on every
- * path — bumped, skipped, or unresolvable (kit#773). Alignment used to run only after a
- * successful bump, which never fires in the steady state of an up-to-date repository, so a
- * manifest that arrived with the two fields out of step kept the pnpm dual-declaration
- * warning forever. The alignment is idempotent, so running it unconditionally is free.
+ * path — bumped, skipped, or unresolvable. A bump never fires in the steady state of an
+ * up-to-date repository, so alignment gated on one would leave a manifest that arrived with
+ * the two fields out of step warning forever. The alignment is idempotent, so running it
+ * unconditionally is free.
  *
- * A failed bump exits non-zero with its cause, the manifest restored (#3361). It used to be
- * swallowed as a skip, so `latest:scope --record` marked the run fresh and a pnpm that could not
- * self-update (the Corepack shim refuses it) stayed pinned silently. `josh latest` runs this step
+ * A failed bump exits non-zero with its cause, the manifest restored — a skip would let
+ * `latest:scope --record` mark the run fresh while a pnpm that could not self-update (the
+ * Corepack shim refuses it) stayed pinned silently. `josh latest` runs this step
  * last, right before the record, so the dependency update and the audit still finish and only the
  * record is withheld. A registry answer not newer than the pin, or nothing aged past the
  * quarantine window yet, remains a non-fatal skip.
@@ -60,7 +60,7 @@ const INTEGRITY_RE = /^sha512-([A-Za-z0-9+/]+={0,2})$/u
 const PACKAGE_MANAGER_VALUE_RE = /("packageManager"\s*:\s*")pnpm@[^"]+(")/u
 
 // `target` is undefined both when the registry did not answer and when it answered but nothing has
-// aged past the quarantine window yet; only the first is a failure (#3361).
+// aged past the quarantine window yet; only the first is a failure.
 interface TargetResolution {
 	target: string | undefined
 	is_registry_reachable: boolean
@@ -70,7 +70,7 @@ const PNPM_DEVELOPMENT_MANAGER_SCHEMA = z.object({ name: z.literal('pnpm'), vers
 const DEV_ENGINES_SCHEMA = z.object({ packageManager: PNPM_DEVELOPMENT_MANAGER_SCHEMA })
 const DEV_ENGINES_PNPM_SCHEMA = z.object({ devEngines: DEV_ENGINES_SCHEMA.optional() })
 const COREPACK_REMEDY =
-	'pnpm runs through the Corepack shim, where pnpm 11+ refuses self-update (ERR_PNPM_CANT_SELF_UPDATE_IN_COREPACK). Run `corepack disable pnpm`, install a standalone pnpm (https://pnpm.io/installation), then rerun josh latest.'
+	'pnpm runs through the Corepack shim, where pnpm 11+ refuses self-update (ERR_PNPM_CANT_SELF_UPDATE_IN_COREPACK). Run `corepack disable pnpm`, install a standalone pnpm (https://pnpm.io/installation), run josh sync so a devEngines.packageManager.onFail of "error" becomes "download" (the standalone pnpm then fetches the pinned version), then rerun josh latest.'
 
 function extract_development_engines_version(package_json_content: string): string | undefined {
 	const parsed = DEV_ENGINES_PNPM_SCHEMA.safeParse(
@@ -108,7 +108,7 @@ function extract_pinned_version(package_json_content: string): string | undefine
 
 // Never move the pin backwards. A filtered registry view (safe-chain's minimum-release-age
 // proxy) answers below a freshly adopted pin for 24 hours after every pnpm release, and an
-// equal answer would only rewrite the same value — both skip instead (kit#766).
+// equal answer would only rewrite the same value — both skip instead.
 function is_target_not_newer_than_pin(target: string, pinned_version: string | undefined): boolean {
 	if (pinned_version === undefined) return false
 	const target_version = target.slice(TARGET_PREFIX.length)
@@ -160,7 +160,7 @@ function resolve_major_target(major: string): TargetResolution {
 	// The project's own `pnpm-workspace.yaml`, deliberately not the upward walk the version check
 	// uses: `josh latest` reads `package.json` and writes the pnpm pin relative to the working
 	// directory, so it has no subdirectory case — and honouring an ancestor's policy here could freeze
-	// pnpm bumps in a project that declares none (joshuafolkken/kit#808).
+	// pnpm bumps in a project that declares none.
 	const version = release_age.select_aged_version(
 		times,
 		major,
@@ -238,7 +238,7 @@ function run_pnpm_update(target: string): number {
 // fields keep matching (pnpm suppresses the dual-declaration warning only on an exact
 // match). Runs on every path, not just after a successful bump: a repository that arrives
 // with the two fields already out of step sits in the no-bump steady state forever, so an
-// alignment gated on a bump would never repair it (kit#773).
+// alignment gated on a bump would never repair it.
 function sync_development_engines(package_json_path: string = PACKAGE_JSON_PATH): void {
 	const content = readFileSync(package_json_path, 'utf8')
 	const aligned = package_manager_version.align_development_engines_version(content)
@@ -311,7 +311,7 @@ function restore_integrity(target: string, integrity: string): void {
 }
 
 // The equal case is the steady state of every up-to-date run, so it logs as success; only
-// an answer strictly below the pin is the anomaly worth a warning (kit#766).
+// an answer strictly below the pin is the anomaly worth a warning.
 function notify_skipped_bump(target: string, pinned_version: string): void {
 	if (target === `${TARGET_PREFIX}${pinned_version}`) {
 		console.info(`✔ pnpm pin ${pinned_version} already matches the newest registry release.`)
@@ -376,7 +376,7 @@ function bump_package_manager(original: string, target: string): number {
 }
 
 // An unreachable registry fails, so the unrecorded run is retried. A reachable one with nothing
-// aged past the quarantine window is the kit#768 skip — like a not-newer answer, there is nothing
+// aged past the quarantine window is the quarantine skip — like a not-newer answer, there is nothing
 // to adopt yet, and failing would stall every run for up to the whole window.
 function report_unresolved(major: string | undefined, is_registry_reachable: boolean): number {
 	const label = `pnpm ${major ?? ''}`.trimEnd()

package/scripts/version/latest-lane-guard.ts

@@ -2,7 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { lane_paths, type LaneEnvironment } from '#scripts/lane/lane-paths'
 
-// Refuse a dependency update inside a lane (joshuafolkken/kit#2135).
+// Refuse a dependency update inside a lane.
 //
 // `latest:scope` reads how long ago `josh latest` last finished, and that stamp is keyed to the
 // project root. A lane is a linked work tree whose project root is its own directory, so a fresh

package/scripts/version/latest-scope-cli.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { latest_lane_guard } from './latest-lane-guard'
 import { latest_stamp, type LatestStamp } from './latest-stamp'
 
-// `josh latest:scope` — say whether this run has to update dependencies (joshuafolkken/kit#1215).
+// `josh latest:scope` — say whether this run has to update dependencies.
 //
 // A command rather than a paragraph in a procedure, for the reason `josh review:level` is a command:
 // a rule an agent applies from memory is a rule an agent can talk itself out of, and this one is
@@ -65,7 +65,7 @@ function decide(): Decision {
 	}
 }
 
-// A lane is answered `skip` before the stamp is even read (joshuafolkken/kit#2135): the stamp is
+// A lane is answered `skip` before the stamp is even read: the stamp is
 // keyed to the project root, so a lane always reads as stale, and every lane would otherwise run its
 // own dependency update. `latest_lane_guard` is the single source of the reason and of the refusal
 // `josh latest` prints.

package/scripts/version/latest-stamp.ts

@@ -1,8 +1,7 @@
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
 
-// When `josh latest` last finished in this checkout, and whether that is recent enough to skip
-// (joshuafolkken/kit#1215).
+// When `josh latest` last finished in this checkout, and whether that is recent enough to skip.
 //
 // `josh latest` is a network-bound chain — pnpm update, every dependency, `ranges`, `pnpm audit` — that
 // took 60–120 seconds at the head of every `fullrun` / `halfrun` and of every child a batch ran, and

package/scripts/version/latest-update.ts

@@ -63,8 +63,8 @@ function report_kept_back(regressions: ReadonlyArray<VersionRegression>): void {
 
 // The direct-dependency `--latest` bump lifts the package.json ranges; this second, argument-less
 // pass then re-resolves every tier the lockfile carries within those ranges, which is the only stage
-// that reaches the indirect packages a direct-only update leaves pinned at a stale resolution
-// (joshuafolkken/kit#2200). `pnpm update` defaults to depth Infinity, so no flag is needed to reach
+// that reaches the indirect packages a direct-only update leaves pinned at a stale resolution.
+// `pnpm update` defaults to depth Infinity, so no flag is needed to reach
 // the whole tree. The re-resolution stage always runs — even when every direct dependency is
 // overridden and the `--latest` stage is absent, the indirect tiers still need re-resolving.
 const PNPM_UPDATE_ALL_TIERS = ['pnpm', 'update']

package/scripts/version/npm-registry.ts

@@ -7,7 +7,7 @@ import { z } from 'zod'
 import { release_age } from './release-age'
 
 // The public npm registry, read without credentials so a consumer who installed from public npm
-// can see the latest release without a `read:packages` GitHub token (joshuafolkken/kit#2882). The
+// can see the latest release without a `read:packages` GitHub token. The
 // GitHub Packages versions API stays the source for a scope routed there, and the fallback for a
 // package public npm does not carry.
 const PUBLIC_REGISTRY = 'https://registry.npmjs.org'
@@ -99,7 +99,7 @@ function read_release_times(package_name: string): Record<string, string> | unde
 // Whether public npm already carries `<name>@<version>`. **Asked of public npm regardless of how this
 // checkout routes the scope**, unlike the two readers above: `josh release` waits for `publish.yml`'s
 // `publish-npm` job and links the npmjs.com page, so GitHub Packages answering would not be the
-// question it asks (joshuafolkken/kit#3193).
+// question it asks.
 function has_public_version(package_name: string, version: string): boolean {
 	const parsed = times_schema.safeParse(read_packument(package_name, FULL_ACCEPT))
 

package/scripts/version/package-manager-version.ts

@@ -14,6 +14,12 @@ const PNPM_PIN_REGEX = /^pnpm@(.+)$/u
 const DEV_ENGINES_NAME_FIRST_REGEX = /("name":\s*"pnpm"\s*,\s*"version":\s*")[^"]+(")/u
 const DEV_ENGINES_VERSION_FIRST_REGEX = /("version":\s*")[^"]+("\s*,\s*"name":\s*"pnpm")/u
 
+// An `onFail: "error"` inside a `"packageManager": { … }` object — in a manifest that is only
+// `devEngines.packageManager`, since the top-level `packageManager` is a string — and never
+// `devEngines.runtime`, because `[^{}]` cannot cross into another block.
+const DEV_ENGINES_ON_FAIL_ERROR_REGEX = /("packageManager":\s*\{[^{}]*"onFail":\s*")error(")/u
+const ON_FAIL_DOWNLOAD = 'download'
+
 const optional_version_schema = z.object({ version: z.string().optional() }).optional()
 
 const alignment_read_schema = z.object({
@@ -86,10 +92,22 @@ function align_development_engines_version(content: string): string {
 	return set_development_engines_version(content, target)
 }
 
+// `onFail: "error"` rejects any pnpm that is not byte-for-byte the pin, so a machine that left
+// Corepack for a standalone pnpm cannot run pnpm at all; `"download"` fetches the pinned version
+// instead. Only `"error"` is rewritten — a `"warn"` / `"ignore"` the
+// project chose itself is kept, and the rest of the file is preserved byte-for-byte.
+function upgrade_development_engines_on_fail(content: string): string {
+	return content.replace(
+		DEV_ENGINES_ON_FAIL_ERROR_REGEX,
+		(_match: string, prefix: string, suffix: string) => `${prefix}${ON_FAIL_DOWNLOAD}${suffix}`,
+	)
+}
+
 const package_manager_version = {
 	extract_pnpm_pin,
 	align_development_engines_version,
 	set_development_engines_version,
+	upgrade_development_engines_on_fail,
 }
 
 export { package_manager_version }

package/scripts/version/publishable-range-check.ts

@@ -24,7 +24,8 @@ const FAILURE_EXIT_CODE = 1
 // consumer can resolve — the exact blind spot this guard exists to close.
 //
 // `pnpm view` rather than `npm view` because npm refuses to run at all inside a project whose
-// `devEngines.packageManager` names pnpm with `onFail: "error"`, failing every probe with
+// `devEngines.packageManager` names pnpm with an `onFail` other than `"warn"` / `"ignore"` (kit
+// ships `"download"`, which npm refuses on just the same), failing every probe with
 // EBADDEVENGINES instead of answering. Both are shimmed, so the filtered view is preserved.
 function probe_range(name: string, range: string): ProbeResult {
 	const result = execaSync('pnpm', ['view', `${name}@${range}`, 'version'], {

package/scripts/version/publishable-range.ts

@@ -4,7 +4,7 @@ import semver from 'semver'
 // kit ships a `preinstall` hook that installs @aikidosec/safe-chain, whose minimum-age policy hides
 // releases younger than its window from every install running behind it. A range whose floor sits
 // inside that window has no satisfying version for a consumer, so `pnpm install` fails with
-// ERR_PNPM_NO_MATCHING_VERSION naming a version that demonstrably exists and is tagged latest (#742).
+// ERR_PNPM_NO_MATCHING_VERSION naming a version that demonstrably exists and is tagged latest.
 //
 // The check asks the registry through that same filtered view instead of modelling the policy:
 // `pnpm view <name>@<range> version` prints no version and exits non-zero

package/scripts/version/release-age.ts

@@ -4,14 +4,14 @@ import { yaml_document } from '#scripts/lib/yaml-document'
 import semver from 'semver'
 import { z } from 'zod'
 
-// The minimum-release-age quarantine (kit#768), applied natively instead of inherited from
-// safe-chain's interception. safe-chain filters the registry only when the process tree was
-// started through one of its six wrapped shell commands, so `josh latest` and
-// `pnpm josh latest` used to resolve different "newest release" answers. These functions
-// make the resolution deterministic: the policy comes from the repo-managed `pnpm-workspace.yaml`,
-// the publish timestamps from the registry, and the selection is a pure computation over both.
-// pnpm 12 reads its settings from `pnpm-workspace.yaml` — a `minimum-release-age` line in `.npmrc`
-// is ignored there, so reading it would report a window pnpm does not apply (kit#3267).
+// The minimum-release-age quarantine, applied natively instead of inherited from safe-chain's
+// interception. safe-chain filters the registry only when the process tree was started through one
+// of its wrapped shell commands, so `josh latest` and `pnpm josh latest` would resolve different
+// "newest release" answers. These functions make the resolution deterministic: the policy comes
+// from the repo-managed `pnpm-workspace.yaml`, the publish timestamps from the registry, and the
+// selection is a pure computation over both. pnpm 12 reads its settings from `pnpm-workspace.yaml`
+// — a `minimum-release-age` line in `.npmrc` is ignored there, so reading it would report a window
+// pnpm does not apply.
 
 const NO_QUARANTINE_MINUTES = 0
 const WORKSPACE_PATH = 'pnpm-workspace.yaml'
@@ -78,7 +78,7 @@ function is_eligible(
 // `major` pins the search to one major line — what `josh latest` needs, since corepack validates the
 // resolved pnpm version against `devEngines`. Pass `undefined` to search every major, which is what
 // an "is this installable at all" question wants: `pnpm add pkg@latest` resolves to the newest
-// permitted release regardless of major (joshuafolkken/kit#808).
+// permitted release regardless of major.
 function select_aged_version(
 	times: Record<string, string>,
 	major: string | undefined,
@@ -112,7 +112,7 @@ function read_declared_minimum_release_age(workspace_path: string): number | und
 //
 // Deliberately not the upward walk below: `josh latest` resolves this against the working directory
 // it also writes `corepack use` into, and honouring an ancestor's policy there could freeze pnpm
-// bumps in a project that declares none (joshuafolkken/kit#808).
+// bumps in a project that declares none.
 function read_minimum_release_age(workspace_path: string = WORKSPACE_PATH): number {
 	return read_declared_minimum_release_age(workspace_path) ?? NO_QUARANTINE_MINUTES
 }
@@ -121,7 +121,7 @@ function read_minimum_release_age(workspace_path: string = WORKSPACE_PATH): numb
 //
 // This walks rather than reading one path because `josh version` and `josh latest` both run from
 // anywhere inside a project — and from outside one — so resolving against the working directory
-// alone would silently read "no quarantine" in every subdirectory (joshuafolkken/kit#808). pnpm
+// alone would silently read "no quarantine" in every subdirectory. pnpm
 // finds its workspace root the same way, by walking up to the nearest `pnpm-workspace.yaml`.
 //
 // `boundary` stops the walk at a known root. Production passes none, while tests bound the search

package/scripts/version/release-hold.ts

@@ -5,7 +5,7 @@ import { release_age } from './release-age'
 // *unpinned* resolution, so anything resolved without an explicit version stops one or more releases
 // short of `latest`. Reporting that as a bare `⚠ → <latest>` is indistinguishable from an install the
 // user forgot to upgrade — and it recurs after every successful upgrade, because the newest release
-// is by definition the youngest (joshuafolkken/kit#808).
+// is by definition the youngest.
 //
 // **The window binds unpinned resolution only.** Measured on pnpm 11.22.0 with
 // `minimumReleaseAge: 1440` and a release published 3.5 h earlier:
@@ -14,7 +14,7 @@ import { release_age } from './release-age'
 //   pnpm add pkg          ->  1.78.0   (the newest release past the window)
 //
 // So a pinned `Run:` hint always works and is never suppressed. What the window actually holds back
-// is peer resolution — the mechanism behind an upstream's effective install (joshuafolkken/kit#698),
+// is peer resolution — the mechanism behind an upstream's effective install,
 // which is why this explanation is attached there and nowhere else.
 
 const MINUTES_PER_HOUR = 60