@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/hooks/pretool-guard.ts

@@ -3,14 +3,15 @@ import { investigation_outcome } from '#scripts/delegation/investigation-guard'
 import { issue_watch_hook } from '#scripts/issue/issue-watch-hook'
 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 { rule_rewrite, type RuleRewrite } from '#scripts/rules/rule-rewrite'
 import { run_parent_cut_hook } from '#scripts/run/run-parent-cut-hook'
+import { run_poll_hook } from '#scripts/run/run-poll-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 { shell_rules_notice } from './shell-rules-notice'
 import { step_zero_notice } from './step-zero-notice'
 
 // One PreToolUse process for the three guards that used to be three. A Bash
@@ -22,11 +23,12 @@ 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,
-// and the batching and investigation guards self-gate away from it. A
-// refusal from any guard wins first; only when none refuses is a guard's non-blocking notice or fault
-// (the whole-file-write notice, a lane child's investigation notice) emitted. Each guard still honours its own
+// union matcher (`Bash|Edit|Read|Write|AskUserQuestion|Agent|Task`) refuses exactly what the three
+// separate entries did — `AskUserQuestion` is matched for the rule guard's lane-child interactive-ask
+// row and `Agent|Task` for its `agent-model` row, and the batching and investigation guards self-gate
+// away from both. A refusal from any guard wins first; only when none refuses is a guard's non-blocking
+// notice or fault (the whole-file-write notice, a lane child's duplicate-read 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.
 
@@ -51,12 +53,13 @@ function combine_outcomes(
 	return outcomes.find((outcome) => !is_clear(outcome)) ?? CLEAR
 }
 
-// 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 {
+// The once-per-session reminders are the last word: asked only where every guard stayed clear, so a
+// refusal or another notice never spends their stamps unseen. Step 0 answers an edit and the shell
+// rules a Bash call, so at most one of them speaks on a call.
+function with_session_notice(outcome: GuardOutcome, raw_payload: string): GuardOutcome {
 	if (!is_clear(outcome)) return outcome
 
-	const notice = step_zero_notice.notice(raw_payload)
+	const notice = step_zero_notice.notice(raw_payload) ?? shell_rules_notice.notice(raw_payload)
 
 	return notice === undefined ? outcome : { reason: undefined, notice, fault: undefined }
 }
@@ -74,9 +77,9 @@ function guard_outcome(raw_payload: string): GuardOutcome {
 	return combine_outcomes(outcomes, delivered_rules.delivery(raw_payload))
 }
 
-// The synchronous verdict the Codex adapter asks for, with the Step 0 reminder as its last layer.
+// The synchronous verdict the Codex adapter asks for, with the session reminders as its last layer.
 function pretool_outcome(raw_payload: string): GuardOutcome {
-	return with_step_zero_notice(guard_outcome(raw_payload), raw_payload)
+	return with_session_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
@@ -96,12 +99,14 @@ async function mark_phase(outcome: GuardOutcome): Promise<void> {
 // **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.
+// surfaced first. **The poll guard is third**: it reads the same carry record, and only for a call that
+// repeats a state read, so the hand-off still wins over it.
 async function async_reason(raw_payload: string): Promise<string | undefined> {
 	const watcher = await run_watcher_hook.watcher_hook_reason(raw_payload)
 	const cut = watcher ?? (await run_parent_cut_hook.parent_cut_reason(raw_payload))
+	const poll = cut ?? (await run_poll_hook.safe_poll_reason(raw_payload))
 
-	return cut ?? (await issue_watch_hook.watch_reason())
+	return poll ?? (await issue_watch_hook.watch_reason())
 }
 
 async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome> {
@@ -113,7 +118,7 @@ async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome>
 
 	if (reason !== undefined) return { reason, notice: undefined, fault: undefined }
 
-	const outcome = with_step_zero_notice(base, raw_payload)
+	const outcome = with_session_notice(base, raw_payload)
 
 	await mark_phase(outcome)
 
@@ -137,81 +142,65 @@ 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_input_of(
+	raw_payload: string,
+	is_lane_child?: () => boolean,
+): Record<string, unknown> | undefined {
+	const call = guarded_call(raw_payload)
+
+	return call === undefined ? undefined : lane_background.foreground_input(call, is_lane_child)
+}
+
+// The envelope that replaces the outcome's own when a lane child runs `josh ship` alone: the call is
+// run in the foreground at the cap instead of being refused or moved aside. A refusal from any guard
+// still wins, and a notice the outcome carried rides along in the same context. On top of a row's
+// rewrite — `raw_payload` is then the rewritten call — it keeps that row's notes and its lack of a
+// permission decision, so the cap is never lost to a pipefail or tail rewrite (joshuafolkken/kit#4101).
 function foreground_rewrite(
 	outcome: GuardOutcome,
 	raw_payload: string,
 	is_lane_child?: () => boolean,
+	rewrite?: RuleRewrite,
 ): string | undefined {
-	if (outcome.reason !== undefined) return undefined
-
-	const call = guarded_call(raw_payload)
 	const input =
-		call === undefined ? undefined : lane_background.foreground_input(call, is_lane_child)
+		outcome.reason === undefined ? foreground_input_of(raw_payload, is_lane_child) : undefined
 
 	if (input === undefined) return undefined
 
-	return hook_decision.rewrite_envelope(
-		input,
-		rewrite_context(lane_background.FOREGROUND_NOTE, outcome),
-	)
-}
+	const note = [rewrite?.note, lane_background.FOREGROUND_NOTE].filter(Boolean).join('\n\n')
+	const envelope_of =
+		rewrite === undefined ? hook_decision.rewrite_envelope : hook_decision.flow_rewrite_envelope
 
-interface PipefailRewrite {
-	payload: string
-	input: Record<string, unknown>
+	return envelope_of(input, rewrite_context(note, outcome))
 }
 
-// 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(
+// The rows' rewrite carries no permission decision: whatever else the line runs meets its own prompt.
+function rule_envelope(
 	outcome: GuardOutcome,
-	input: Record<string, unknown> | undefined,
+	rewrite: RuleRewrite | undefined,
 ): string | undefined {
-	if (input === undefined || outcome.reason !== undefined) return undefined
+	if (rewrite === undefined || outcome.reason !== undefined) return undefined
 
-	return hook_decision.flow_rewrite_envelope(
-		input,
-		rewrite_context(piped_verification.PIPEFAIL_NOTE, outcome),
-	)
+	return hook_decision.flow_rewrite_envelope(rewrite.input, rewrite_context(rewrite.note, outcome))
 }
 
 // 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)
+function emit(raw_payload: string, outcome: GuardOutcome, rewrite?: RuleRewrite): void {
+	const envelope =
+		foreground_rewrite(outcome, raw_payload, undefined, rewrite) ?? rule_envelope(outcome, rewrite)
 
-	if (rewrite === undefined) hook_decision.emit_outcome(outcome)
-	else process.stdout.write(`${rewrite}\n`)
+	if (envelope === undefined) hook_decision.emit_outcome(outcome)
+	else process.stdout.write(`${envelope}\n`)
 }
 
-// **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.
+// **The guards judge the call that will run.** A rewritten call reaches every guard already made
+// right, so the rewriting 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
+	const rewrite = rule_rewrite.rewrite(raw_payload)
+	const judged = rewrite?.payload ?? raw_payload
 
-	emit(judged, await pretool_outcome_async(judged), pipefail?.input)
+	emit(judged, await pretool_outcome_async(judged), rewrite)
 }
 
 const pretool_guard = {
@@ -219,7 +208,6 @@ const pretool_guard = {
 	emit,
 	foreground_rewrite,
 	mark_phase,
-	pipefail_rewrite,
 	pretool_outcome,
 	respond,
 }

package/scripts/hooks/reserved-run.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { command_memory } from '#scripts/gate/command-memory'
 import { core_budget } from '#scripts/gate/core-budget'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { execa } from 'execa'
@@ -18,6 +19,11 @@ import { execa } from 'execa'
 // being rewritten around it — and a second copy of the claim-run-release dance is the clone
 // `CLAUDE.md` prohibits. The weight is the caller's, passed on the command line beside the command, so
 // the reservation these two conservative numbers stand for lives at the one place a person reads them.
+//
+// **The memory is read off the command, not left at zero** (joshuafolkken/kit#4582): a lane wrapped a
+// four-worker typed eslint here and the 12 GB it held was admitted beside four other lanes. The
+// wrapped command's tool and worker count give its `MEMORY_MB` (`command-memory.ts`); `--memory <MB>`
+// overrides that estimate.
 
 // `process.argv` is [runner, script, ...arguments].
 const FIRST_ARGUMENT_INDEX = 2
@@ -30,24 +36,74 @@ const FAIL_EXIT_CODE = 1
 // cumulative sum and let a later reservation admit past the budget the ledger exists to hold.
 const MIN_WEIGHT = 1
 
+const MEMORY_FLAG = '--memory'
+// `--memory <MB>`: the flag and its value.
+const MEMORY_OPTION_LENGTH = 2
+// An explicit `--memory` claims at least one MB; zero is the absence the estimate already stands for.
+const MIN_MEMORY_MB = 1
+// An argument that is one shell word with no quoting.
+const PLAIN_WORD = /^[\w./=:@%+,-]+$/u
+// A single quote inside a single-quoted word: close, escaped quote, reopen.
+const ESCAPED_QUOTE = String.raw`'\''`
+
 interface ReservedCommand {
 	weight: number
+	// The explicit `--memory <MB>`, which overrides the estimate read off the command.
+	memory_mb: number | undefined
 	command: ReadonlyArray<string>
 }
 
-// `<weight> -- <command> [args...]`. `undefined` is a usage error: a missing separator, a weight that
-// is not an integer of at least one core, or nothing to run.
+function is_integer_from(value: number, floor: number): boolean {
+	return Number.isSafeInteger(value) && value >= floor
+}
+
+// The options between the weight and the separator: none, or `--memory <MB>` with a positive integer.
+// `undefined` is a usage error.
+function parse_memory(
+	options: ReadonlyArray<string>,
+): { memory_mb: number | undefined } | undefined {
+	if (options.length === 0) return { memory_mb: undefined }
+
+	const memory_mb = Number(options[1])
+	const is_memory_option = options.length === MEMORY_OPTION_LENGTH && options[0] === MEMORY_FLAG
+
+	return is_memory_option && is_integer_from(memory_mb, MIN_MEMORY_MB) ? { memory_mb } : undefined
+}
+
+// `<weight> [--memory <MB>] -- <command> [args...]`. `undefined` is a usage error: a missing
+// separator, a weight that is not an integer of at least one core, a malformed `--memory`, or nothing
+// to run.
 function parse_arguments(argv: ReadonlyArray<string>): ReservedCommand | undefined {
 	const NOT_FOUND = -1
 	const separator = argv.indexOf(COMMAND_SEPARATOR)
 	const weight = Number(argv[WEIGHT_INDEX])
-	const is_valid_weight = Number.isSafeInteger(weight) && weight >= MIN_WEIGHT
+	const memory = parse_memory(argv.slice(WEIGHT_INDEX + 1, Math.max(separator, 0)))
+	const command = argv.slice(separator + 1)
 
-	if (separator === NOT_FOUND || !is_valid_weight) return undefined
+	if (separator === NOT_FOUND || !is_integer_from(weight, MIN_WEIGHT)) return undefined
 
-	const command = argv.slice(separator + 1)
+	return memory !== undefined && command.length > 0 ? { weight, ...memory, command } : undefined
+}
+
+// An argument as one shell word: a plain one as written, anything else single-quoted. **The estimate
+// re-reads the command as a shell line**, so `git commit -m "a; eslint ."` joined bare would be cut at
+// the `;` and reserved as an eslint run.
+function shell_word(argument: string): string {
+	if (PLAIN_WORD.test(argument)) return argument
+
+	return `'${argument.split("'").join(ESCAPED_QUOTE)}'`
+}
+
+// What the claim carries to the ledger: the command named on the waiting line, and the memory it
+// holds — the explicit `--memory`, else the estimate read off the command (`command-memory.ts`), else
+// none, the 0 MB a command the table does not know counted before.
+function reservation_options(parsed: ReservedCommand): {
+	command: string
+	memory_mb: number | undefined
+} {
+	const command = parsed.command.map((argument) => shell_word(argument)).join(' ')
 
-	return command.length > 0 ? { weight, command } : undefined
+	return { command, memory_mb: parsed.memory_mb ?? command_memory.estimated_memory_mb(command) }
 }
 
 // `stdio: 'inherit'` so the command's own progress reaches the push, and `reject: false` so a failing
@@ -64,7 +120,9 @@ async function run_reserved(argv: ReadonlyArray<string>): Promise<number> {
 	const parsed = parse_arguments(argv)
 
 	if (parsed === undefined) {
-		process.stderr.write('reserved-run: usage: reserved-run <weight> -- <command> [args...]\n')
+		process.stderr.write(
+			'reserved-run: usage: reserved-run <weight> [--memory <MB>] -- <command> [args...]\n',
+		)
 
 		return FAIL_EXIT_CODE
 	}
@@ -78,6 +136,7 @@ async function run_reserved(argv: ReadonlyArray<string>): Promise<number> {
 	return await core_budget.with_core_reservation(
 		parsed.weight,
 		async () => await run_command(parsed.command),
+		reservation_options(parsed),
 	)
 }
 
@@ -85,6 +144,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_reserved(process.argv.slice(FIRST_ARGUMENT_INDEX))
 }
 
-const reserved_run = { parse_arguments, run_reserved }
+const reserved_run = { parse_arguments, reservation_options, run_reserved }
 
 export { reserved_run }

package/scripts/hooks/run-hook.sh

@@ -5,38 +5,45 @@
 # A hook command in `.claude/settings.json` / `.codex/hooks.json` only moves to the project root
 # (`scripts/init/hook-launch.ts`) and calls this script, so everything every hook shares lives here once:
 #
-# - The git location variables a git hook exports are cleared when the root resolves without them, so
-#   the hook's own git calls act on the checkout it stands in. They are kept when the checkout needs
-#   them — git metadata outside the work tree.
+# - The git location variables a git hook exports are cleared when the checkout resolves without
+#   them, so the hook's own git calls act on the checkout it stands in, and kept when the git metadata
+#   lives outside the work tree. `git` starts only when one of them is set — a hook runs on every tool
+#   call (joshuafolkken/kit#3946, joshuafolkken/kit#4187). The list is `GIT_LOCATION_VARIABLES`
+#   (`scripts/git/git-location-environment.ts`), held to it by `run-hook.test.ts`.
 # - The pre-built bundle `dist/hooks/<name>.js` runs once its gate passes; otherwise the live source
 #   runs through josh, whose command is the name with its first `-` turned into `:`
 #   (`pretool-guard` → `pretool:guard`).
-# - In kit's own checkout the gate is `hook-bundle-ready.ts`, which rebuilds stale bundles
+# - In kit's own checkout the gate is the kit-only `tools/hooks/hook-bundle-ready.ts`, which rebuilds stale bundles
 #   (joshuafolkken/kit#2984) and then runs the bundle — or the josh fallback — itself, so a hook call
 #   starts node once (joshuafolkken/kit#3327). In an installed package it is a presence check: the
 #   published bundles cannot be stale against a source the consumer never edits, and Node strips no
 #   types under `node_modules`.
+# - Nothing is spawned that the shell can do itself: the directory is a parameter expansion rather than
+#   `dirname`, and `node` replaces this shell through `exec` rather than running beside it.
 # - An `if`/`else`, never `&&`/`||`: a guard's refusal is a non-zero exit, and a chain would read it as
 #   a missing bundle and run the hook twice.
 
 location_variables='GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE'
-unset_options=''
-for variable in $location_variables; do unset_options="$unset_options -u $variable"; done
-# shellcheck disable=SC2086
-if env $unset_options git rev-parse --show-toplevel >/dev/null 2>&1; then unset $location_variables; fi
+if [ -n "$GIT_ALTERNATE_OBJECT_DIRECTORIES$GIT_COMMON_DIR$GIT_DIR$GIT_INDEX_FILE$GIT_NAMESPACE$GIT_OBJECT_DIRECTORY$GIT_WORK_TREE" ] &&
+	(unset $location_variables && git rev-parse --show-toplevel >/dev/null 2>&1); then
+	unset $location_variables
+fi
 
 hook_name=$1
 shift
-hooks_dir=$(dirname "$0")
+case $0 in
+*/*) hooks_dir=${0%/*} ;;
+*) hooks_dir=. ;;
+esac
 package_dir="$hooks_dir/../.."
 bundle="$package_dir/dist/hooks/$hook_name.js"
 josh_command="${hook_name%%-*}:${hook_name#*-}"
 
 case $0 in
 *node_modules/*)
-	if [ -d "$package_dir/dist/hooks" ]; then node "$bundle" "$@"; else node "$package_dir/dist/josh.js" "$josh_command" "$@"; fi
+	if [ -d "$package_dir/dist/hooks" ]; then exec node "$bundle" "$@"; else exec node "$package_dir/dist/josh.js" "$josh_command" "$@"; fi
 	;;
 *)
-	node --disable-warning=ExperimentalWarning "$hooks_dir/hook-bundle-ready.ts" "$hook_name" "$josh_command" "$@"
+	exec node --disable-warning=ExperimentalWarning "$package_dir/tools/hooks/hook-bundle-ready.ts" "$hook_name" "$josh_command" "$@"
 	;;
 esac

package/scripts/hooks/shell-rules-notice.ts

@@ -0,0 +1,37 @@
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { hook_decision } from '#scripts/josh/hook-decision'
+
+// The two most-refused Bash rows, `file-body` and `piped-verification`, delivered ahead of the call
+// that would break them. A refusal teaches the rule only after the call was composed, and each
+// refusal is a round trip spent rewriting it (joshuafolkken/kit#3996). The first Bash call of a
+// session comes before any of those, so the hook that sees it carries the two rules as a notice.
+//
+// **The rows themselves are unchanged.** They still refuse on every occurrence; this only puts their
+// text in front of the first call, the way `step-zero-notice.ts` delivers Step 0 at the first edit.
+//
+// **Once per session**, on a stamp keyed by the transcript. A stamp that cannot be written stays
+// silent rather than repeating the notice on every call.
+const STAMP_PREFIX = 'josh-shell-rules-notice-'
+
+const NOTICE =
+	'Shell rules: change an existing file with Edit or Write, never a script or heredoc that writes it (file-edits.md); run a josh check with no pipe or under `set -o pipefail`, never `| head` (output-bounds.md).'
+
+const STAMP = hook_decision.create_refusal_stamp(STAMP_PREFIX)
+
+function notice(raw_payload: string): string | undefined {
+	const payload = hook_decision.parse_hook_payload(raw_payload)
+
+	if (payload?.tool_name !== cost_blocks.BASH_TOOL) return undefined
+
+	const target = STAMP.path(payload.transcript_path)
+
+	if (STAMP.last_ms(target) !== hook_decision.NEVER_MS || !STAMP.record(target, Date.now())) {
+		return undefined
+	}
+
+	return NOTICE
+}
+
+const shell_rules_notice = { NOTICE, notice, stamp_path: STAMP.path }
+
+export { shell_rules_notice }

package/scripts/hooks/stop-actions.ts

@@ -0,0 +1,185 @@
+import { git_gh_repo } from '#scripts/gh/git-gh-repo'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_cite_cli } from '#scripts/issue/issue-cite-cli'
+import { session_cite } from '#scripts/issue/session-cite'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { stdout_on_stderr } from '#scripts/lib/stdout-on-stderr'
+import { telegram_test } from '#scripts/notify/telegram-test'
+import type { CliValues } from '#scripts/notify/telegram-test-logic'
+import { issue_citation } from '#scripts/rules/issue-citation'
+import { stop_rules, type StopAction, type StopOutcome } from '#scripts/rules/stop-rules'
+import { run_hold } from '#scripts/run/hold/run-hold'
+import { run_hold_cli } from '#scripts/run/hold/run-hold-cli'
+import { run_hold_session } from '#scripts/run/hold/run-hold-session'
+
+type NotifyAction = Extract<StopAction, { kind: 'notify' }>
+
+// The `Stop` hook running the operations whose answer is fixed (joshuafolkken/kit#3919): the
+// `confirmation` notify, the hold release and the citation lines, through the very calls
+// `josh notify`, `josh run:release` and `josh issue:cite` make — in process, since three `pnpm`
+// launches would spend most of the hook's 20-second budget. What each did reaches the person as a
+// `systemMessage`; one that did not take falls back to the refusal it replaced (`stop_rules.fallback_reason`).
+
+const SUCCESS_EXIT_CODE = 0
+const NOTICE_SEPARATOR = '\n'
+// The reply is the stop's reason, but a Telegram is read at a glance — its opening is enough.
+const SUMMARY_CHARS = 600
+// A `#N`, `owner/repo#N` or URL is a run of printable ASCII; a cut inside one would link the wrong Issue.
+const TOKEN_CHAR = /^[!-~]$/u
+const EMPTY_SUMMARY = 'The run stopped and is waiting for you.'
+
+interface Settled {
+	notices: ReadonlyArray<string>
+	failure: string | undefined
+}
+
+// One action at a time — the order is the rule order.
+const SEQUENTIAL = 1
+
+// Where the run of token characters `text` ends with starts.
+function token_start(text: string): number {
+	let index = text.length
+
+	while (index > 0 && TOKEN_CHAR.test(text.charAt(index - 1))) index -= 1
+
+	return index
+}
+
+// Cut before linking, on a boundary that keeps every reference whole: the character past the cut shows
+// whether the last token ran on, and a token that did is dropped rather than halved.
+function summary_of(message: string): string {
+	const trimmed = message.trim()
+	if (trimmed === '') return EMPTY_SUMMARY
+	if (trimmed.length <= SUMMARY_CHARS) return trimmed
+
+	const overshoot = trimmed.slice(0, SUMMARY_CHARS + 1)
+	const cut = overshoot.slice(0, Math.min(token_start(overshoot), SUMMARY_CHARS))
+
+	return cut === '' ? trimmed.slice(0, SUMMARY_CHARS) : cut
+}
+
+// The held Issue's URL, or `undefined` for a `new` entry or a repository that cannot be read.
+async function issue_url_of(issue: string): Promise<string | undefined> {
+	if (issue === run_hold.UNNUMBERED_ISSUE) return undefined
+
+	const slug = await git_gh_repo.repo_get_name_with_owner()
+
+	return slug === undefined ? undefined : issue_cite.issue_url(slug, issue)
+}
+
+// The body is the reply's opening copied into a Telegram, so its bare `#N` are linked (`issue-citation.md`).
+// The choices are the reply's own decision lines (joshuafolkken/kit#3961).
+function notify_values(issue_url: string | undefined, action: NotifyAction): CliValues {
+	const { recommended, alternative } = action.decision
+	const values: CliValues = {
+		'task-type': 'confirmation',
+		body: session_cite.text(summary_of(action.message)),
+		recommended,
+		...(alternative !== undefined && { alternative: [alternative] }),
+	}
+
+	return issue_url === undefined ? values : { ...values, 'issue-url': issue_url }
+}
+
+// The send is stamped on the hold, so a later stop of the same pause does not announce it again. A
+// stamp that fails does not fail the send: the Telegram is out, and a refused stop would send it twice.
+async function mark_notified(): Promise<void> {
+	try {
+		const directory = await run_hold.worktree_directory()
+
+		if (directory !== undefined) run_hold_session.mark_notified(run_hold.hold_path(directory))
+	} catch (error) {
+		console.warn(`stop:guard could not stamp the notify on the hold: ${String(error)}`)
+	}
+}
+
+async function notify(action: NotifyAction): Promise<string> {
+	const issue_url = await issue_url_of(action.issue)
+
+	await telegram_test.send_values(notify_values(issue_url, action))
+	await mark_notified()
+
+	return `📱 stop:guard sent the confirmation notify (${issue_url ?? action.issue}).`
+}
+
+async function release(issue: string): Promise<string | undefined> {
+	const argv = issue === run_hold.UNNUMBERED_ISSUE ? ['--release'] : ['--release', issue]
+	const code = await run_hold_cli.run(argv)
+
+	return code === SUCCESS_EXIT_CODE ? '🔓 stop:guard released the run:hold record.' : undefined
+}
+
+// Every line or none: a citation with a number missing is the half-fix the refusal exists to avoid.
+async function cite(references: ReadonlyArray<string>): Promise<string | undefined> {
+	const cited = await issue_cite_cli.cite(issue_citation.cite_arguments(references))
+	if (cited === undefined || cited.failures.length > 0) return undefined
+
+	return ['Issue citations:', ...cited.lines].join(NOTICE_SEPARATOR)
+}
+
+// An action's line for the person, or `undefined` when it did not take.
+async function run_action(action: StopAction): Promise<string | undefined> {
+	if (action.kind === 'notify') return await notify(action)
+	if (action.kind === 'release') return await release(action.issue)
+
+	return await cite(action.references)
+}
+
+// A throw is an action that did not take, the same as one that answered it had failed.
+async function attempt(action: StopAction): Promise<string | undefined> {
+	try {
+		return await run_action(action)
+	} catch {
+		return undefined
+	}
+}
+
+function is_notice(notice: string | undefined): notice is string {
+	return notice !== undefined
+}
+
+// In order, one at a time: the notify reports the hold the release then ends. The first failure is the
+// one refused with, as the rule order put it first.
+async function settle(actions: ReadonlyArray<StopAction>): Promise<Settled> {
+	const notices = await stdout_on_stderr.run(
+		async () => await bounded_pool.bounded_map(actions, SEQUENTIAL, attempt),
+	)
+	const failed = actions.find((_action, index) => notices[index] === undefined)
+
+	return {
+		notices: notices.filter((notice) => is_notice(notice)),
+		failure: failed === undefined ? undefined : stop_rules.fallback_reason(failed),
+	}
+}
+
+function joined(notices: ReadonlyArray<string>): string | undefined {
+	return notices.length === 0 ? undefined : notices.join(NOTICE_SEPARATOR)
+}
+
+// A failure refuses only where the outcome allows it — never past the loop-breaker.
+function settled_envelope(
+	settled: Settled,
+	is_blocking: boolean,
+	lang: string,
+): string | undefined {
+	const notice = joined(settled.notices)
+
+	if (is_blocking && settled.failure !== undefined) {
+		return stop_rules.block_envelope(settled.failure, lang, notice)
+	}
+
+	return notice === undefined ? undefined : stop_rules.notice_envelope(notice)
+}
+
+// What the hook writes for one stop's outcome, or `undefined` for a stop that writes nothing.
+async function envelope_of(outcome: StopOutcome, lang: string): Promise<string | undefined> {
+	if (outcome.reason !== undefined) return stop_rules.block_envelope(outcome.reason, lang)
+
+	const settled = await settle(outcome.actions)
+
+	return settled_envelope(settled, outcome.blocks_on_failure, lang)
+}
+
+const stop_actions = { envelope_of, summary_of }
+
+export { stop_actions }