@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/scripts/hooks/pre-commit-lint.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { core_budget } from '#scripts/gate/core-budget'
+import {
+	CSPELL_COMMIT_CACHE_FLAGS,
+	ESLINT_COMMIT_CACHE_FLAGS,
+	PRETTIER_CACHE_FLAGS,
+} from '#scripts/josh/josh-command-types'
+import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
+import { execa } from 'execa'
+
+// The pre-commit hook's cspell, prettier and eslint runs over the staged files. They go through here
+// rather than a bare `pnpm exec` in `lefthook/base.yml` so each cache location comes from the
+// constant its ignore rules are asserted against (joshuafolkken/kit#3948) — a YAML copy would keep
+// writing the old file the day that constant moves.
+//
+// cspell and eslint write the hook's own files: a staged-files cspell run prunes every entry it did
+// not visit, and `--quiet` stores eslint reports without their warnings. Prettier does neither, so
+// it shares the gate's file and a commit right after a green gate checks nothing twice.
+
+const ARGV_OFFSET = 2
+const USAGE_ERROR_EXIT_CODE = 2
+const PNPM = 'pnpm'
+
+const TOOL_ARGUMENTS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	cspell: [
+		'exec',
+		'cspell',
+		'lint',
+		'--no-must-find-files',
+		'--no-progress',
+		...CSPELL_COMMIT_CACHE_FLAGS,
+	],
+	prettier: ['exec', 'prettier', '--check', '--ignore-unknown', ...PRETTIER_CACHE_FLAGS],
+	eslint: ['exec', 'eslint', '--quiet', ...ESLINT_COMMIT_CACHE_FLAGS],
+}
+
+// **Each tool claims its place in the core budget** (joshuafolkken/kit#3944): lefthook starts the three
+// in parallel, and off the ledger every other lane's admission saw them only as foreign load. Each is
+// one process over the staged files — eslint over 40 of them took 16.9s of CPU over 14.0s of wall at
+// 1,225 MB, the one-process shape the whole-tree scan's weight already names.
+// The key is the one `CORE_WEIGHTS` and `MEMORY_MB` both declare the tool under.
+const TOOL_BUDGETS: Readonly<Record<string, 'spell_check' | 'format' | 'eslint_scan'>> = {
+	cspell: 'spell_check',
+	prettier: 'format',
+	eslint: 'eslint_scan',
+}
+
+const USAGE = `Usage: josh pre-commit-lint <${Object.keys(TOOL_ARGUMENTS).join('|')}> [files...]`
+
+function build_arguments(
+	tool: string,
+	staged_files: ReadonlyArray<string>,
+): ReadonlyArray<string> | undefined {
+	const tool_arguments = TOOL_ARGUMENTS[tool]
+	if (tool_arguments === undefined) return undefined
+
+	return [...tool_arguments, ...staged_files]
+}
+
+async function run_tool(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const result = await execa(PNPM, command_arguments, { stdio: 'inherit', reject: false })
+
+	return resolve_spawn_exit(PNPM, result)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const [tool = '', ...staged_files] = argv
+	const command_arguments = build_arguments(tool, staged_files)
+	const budget = TOOL_BUDGETS[tool]
+
+	if (command_arguments === undefined || budget === undefined) {
+		console.error(USAGE)
+
+		return USAGE_ERROR_EXIT_CODE
+	}
+
+	return await core_budget.with_command_reservation(
+		core_budget.CORE_WEIGHTS[budget],
+		async () => await run_tool(command_arguments),
+		{ memory_mb: core_budget.MEMORY_MB[budget], command: `pre-commit ${tool}` },
+	)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
+}
+
+const pre_commit_lint = { build_arguments, run, USAGE_ERROR_EXIT_CODE }
+
+export { pre_commit_lint }

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

@@ -1,5 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { core_budget } from '#scripts/gate/core-budget'
+import { gate_plan } from '#scripts/gate/gate-plan'
 import { gate_skip, type GateReuse } from '#scripts/gate/gate-skip'
 import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
 import { hook_gate_reuse } from '#scripts/gate/hook-gate-reuse'
@@ -123,6 +125,18 @@ function format_miss(reason: string): string {
 	return `↻ running the whole unit suite — the green gate record does not cover this push: ${reason}.`
 }
 
+// **The whole suite claims its place in the core budget, the one `josh test:unit` claims.** Without it
+// a push's suite ran beside other lanes' gates off the ledger, so their admission saw its workers only
+// as foreign load (joshuafolkken/kit#3874). Only the miss reserves: a reused record runs nothing, and a
+// claim there could make a push wait out a full ledger for a suite it then skips.
+async function run_reserved_suite(vitest_arguments: ReadonlyArray<string>): Promise<number> {
+	return await core_budget.with_command_reservation(
+		gate_plan.direct_unit_weight(),
+		async () => await test_unit_guard.run_guarded_unit(process.cwd(), vitest_arguments),
+		{ memory_mb: gate_plan.direct_unit_memory(), command: 'pre-push test:unit' },
+	)
+}
+
 async function run_pre_push_unit(
 	extra_arguments: ReadonlyArray<string> = [],
 	source?: string,
@@ -132,10 +146,7 @@ async function run_pre_push_unit(
 	if ('miss' in reuse) {
 		process.stdout.write(`${format_miss(reuse.miss)}\n`)
 
-		return await test_unit_guard.run_guarded_unit(
-			process.cwd(),
-			forwarded_arguments(extra_arguments),
-		)
+		return await run_reserved_suite(forwarded_arguments(extra_arguments))
 	}
 
 	process.stdout.write(`${format_skip(reuse.stamp.taken_at)}\n`)

package/scripts/hooks/pretool-guard.ts

@@ -1,13 +1,13 @@
 import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
-import { investigation_refusal } from '#scripts/delegation/investigation-guard'
+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'
@@ -22,38 +22,34 @@ 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 the batch guard's non-blocking notice
-// (the whole-file-write 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.
 
-// Fold the guards' verdicts into one. A refusal wins over everything else, and the batch guard's
-// reason is shown first to match the entry order the separate hooks had. When nothing refuses,
-// whatever the batch guard reported (a notice, a fault, or nothing) passes through untouched.
-function combine_outcomes(batch: GuardOutcome, extra_reason: string | undefined): GuardOutcome {
-	if (batch.reason !== undefined) return batch
-
-	if (extra_reason !== undefined) {
-		return { reason: extra_reason, notice: undefined, fault: undefined }
-	}
-
-	return batch
-}
+const CLEAR: GuardOutcome = { reason: undefined, notice: undefined, fault: undefined }
 
 function is_clear(outcome: GuardOutcome): boolean {
 	return outcome.reason === undefined && outcome.notice === undefined && outcome.fault === undefined
 }
 
-// The duplicate-read guard is `notice`-mode in a lane child, so it is the second guard that can raise a
-// non-refusal notice. Its notice is surfaced only where nothing else spoke —
-// a refusal from any guard, or the batch guard's own notice, wins first.
-function with_duplicate_notice(combined: GuardOutcome, notice: string | undefined): GuardOutcome {
-	if (notice === undefined || !is_clear(combined)) return combined
+// Fold the guards' verdicts into one. A refusal wins over everything else, in the entry order the
+// separate hooks had: the outcomes in the order given, then the rule guard's reason. When nothing
+// refuses, the first guard that spoke passes its notice or fault through untouched — so a lane child's
+// `notice`-mode guidance reaches the model rather than only spending its stamp (joshuafolkken/kit#3877).
+function combine_outcomes(
+	outcomes: ReadonlyArray<GuardOutcome>,
+	rule_reason: string | undefined,
+): GuardOutcome {
+	const reason = outcomes.find((outcome) => outcome.reason !== undefined)?.reason ?? rule_reason
+
+	if (reason !== undefined) return { reason, notice: undefined, fault: undefined }
 
-	return { reason: undefined, notice, fault: undefined }
+	return outcomes.find((outcome) => !is_clear(outcome)) ?? CLEAR
 }
 
 // The Step 0 reminder is the last word: asked only where every guard stayed
@@ -70,14 +66,13 @@ function with_step_zero_notice(outcome: GuardOutcome, raw_payload: string): Guar
 // once-per-run stamp, so short-circuiting on the first refusal would change which guard is allowed to
 // fire on a later call.
 function guard_outcome(raw_payload: string): GuardOutcome {
-	const batch = batch_outcome(raw_payload)
-	const investigation = investigation_refusal(raw_payload)
-	const duplicate = duplicate_read_outcome(raw_payload)
-	const rule = delivered_rules.delivery(raw_payload)
-	const duplicate_refusal = duplicate.reason
-	const combined = combine_outcomes(batch, investigation ?? duplicate_refusal ?? rule)
-
-	return with_duplicate_notice(combined, duplicate.notice)
+	const outcomes = [
+		batch_outcome(raw_payload),
+		investigation_outcome(raw_payload),
+		duplicate_read_outcome(raw_payload),
+	]
+
+	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.
@@ -102,12 +97,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> {
@@ -165,59 +162,32 @@ function foreground_rewrite(
 	)
 }
 
-interface PipefailRewrite {
-	payload: string
-	input: Record<string, unknown>
-}
-
-// A piped josh check the hook runs under `set -o pipefail` instead of refusing it:
-// the rewritten input, and the payload that carries it. The rewrite is the
-// rule guard's delivery, so the rule guard's switch turns it off too.
-function pipefail_rewrite(raw_payload: string): PipefailRewrite | undefined {
-	if (!delivered_rules.is_enabled()) return undefined
-
-	const call = guarded_call(raw_payload)
-	const input = call === undefined ? undefined : piped_verification.pipefail_input(call)
-	const payload = json_value.parse_or_undefined(raw_payload)
-
-	if (input === undefined || !json_value.is_record(payload)) return undefined
-
-	return { payload: JSON.stringify({ ...payload, tool_input: input }), input }
-}
-
-function pipefail_envelope(
+// 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.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 = rule_envelope(outcome, rewrite) ?? foreground_rewrite(outcome, raw_payload)
 
-	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 = {
@@ -225,7 +195,6 @@ const pretool_guard = {
 	emit,
 	foreground_rewrite,
 	mark_phase,
-	pipefail_rewrite,
 	pretool_outcome,
 	respond,
 }

package/scripts/hooks/reserved-run.ts

@@ -78,6 +78,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),
+		{ command: parsed.command.join(' ') },
 	)
 }
 

package/scripts/hooks/run-hook.sh

@@ -5,9 +5,8 @@
 # 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 root prefix has already cleared the git location variables a git hook exports, or kept them
+#   when the checkout needs them; this script starts no `git` of its own (joshuafolkken/kit#3946).
 # - 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`).
@@ -16,27 +15,26 @@
 #   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
-
 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 "$hooks_dir/hook-bundle-ready.ts" "$hook_name" "$josh_command" "$@"
 	;;
 esac

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

@@ -65,8 +65,9 @@ function notice(raw_payload: string, root: string = process.cwd()): string | und
 
 	const target = STAMP.path(transcript)
 
-	if (STAMP.last_ms(target) !== hook_decision.NEVER_MS) return undefined
-	if (!STAMP.record(target, Date.now())) return undefined
+	if (STAMP.last_ms(target) !== hook_decision.NEVER_MS || !STAMP.record(target, Date.now())) {
+		return undefined
+	}
 
 	return NOTICE
 }

package/scripts/hooks/stop-actions.ts

@@ -0,0 +1,204 @@
+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 { 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)
+}
+
+// **The hook's stdout is the decision envelope, so nothing else may reach it**: the reused calls report
+// on stdout (`josh run:release`'s verdict token, the notify's sent line) and are sent to stderr instead.
+type StreamWrite = typeof process.stdout.write
+
+function set_stdout_write(stream_write: StreamWrite): void {
+	process.stdout.write = stream_write
+}
+
+async function on_stderr<T>(work: () => Promise<T>): Promise<T> {
+	const saved = { write: process.stdout.write.bind(process.stdout) }
+
+	set_stdout_write(process.stderr.write.bind(process.stderr))
+
+	try {
+		return await work()
+	} finally {
+		set_stdout_write(saved.write)
+	}
+}
+
+// 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 on_stderr(
+		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 }