@joshuafolkken/kit 1.1453.0 → 1.1455.0

package/dist/hooks/stop-guard.js

@@ -13,7 +13,7 @@ import {
   repo_party,
   run_cut,
   run_hold
-} from "./chunk-Y3GKIKGW.js";
+} from "./chunk-7WQBPLUN.js";
 import {
   agent_headless,
   agent_role_profile,
@@ -30,12 +30,12 @@ import {
 import "./chunk-CDY4NFQG.js";
 import {
   hook_decision
-} from "./chunk-W5ZKGTSY.js";
+} from "./chunk-GPLGZ6IC.js";
 import {
   time_density_hook,
   time_hook_transcript,
   time_reported_failure
-} from "./chunk-MBJYQPEK.js";
+} from "./chunk-LIAFCXL7.js";
 import {
   lane_child_marker
 } from "./chunk-OLMO72ON.js";
@@ -317,6 +317,52 @@ var backlog_ready = {
 
 // scripts/notify/telegram-notify.ts
 import { z } from "zod";
+
+// scripts/notify/confirmation-options.ts
+var JAPANESE_LANG_PREFIX = "ja";
+var JAPANESE_HEADINGS = {
+  recommended: "\u63A8\u5968:",
+  alternatives: "\u4ED6\u306E\u9078\u629E\u80A2:",
+  none: "\u306A\u3057"
+};
+var ENGLISH_HEADINGS = {
+  recommended: "Recommended:",
+  alternatives: "Alternatives:",
+  none: "none"
+};
+function headings() {
+  const { lang } = session_language.resolve_session_lang();
+  return lang.toLowerCase().startsWith(JAPANESE_LANG_PREFIX) ? JAPANESE_HEADINGS : ENGLISH_HEADINGS;
+}
+function alternatives_block(options, labels) {
+  if (options.alternatives.length === 0) return `${labels.alternatives} ${labels.none}`;
+  const lines = options.alternatives.map((alternative) => `- ${alternative}`);
+  return [labels.alternatives, ...lines].join("\n");
+}
+function block(options) {
+  const labels = headings();
+  return `${labels.recommended} ${options.recommended}
+${alternatives_block(options, labels)}`;
+}
+var confirmation_options = { block };
+
+// scripts/notify/notify-opt-in.ts
+var OPT_IN_KEY = "JOSH_NOTIFY_OPT_IN";
+var OPTIONAL_TASK_TYPES = /* @__PURE__ */ new Set(["planning", "completion"]);
+var LIST_SEPARATOR = ",";
+function opted_in_types() {
+  return (process.env[OPT_IN_KEY] ?? "").split(LIST_SEPARATOR).map((entry) => entry.trim().toLowerCase()).filter((entry) => entry.length > 0);
+}
+function is_skipped(task_type) {
+  if (!OPTIONAL_TASK_TYPES.has(task_type)) return false;
+  return !opted_in_types().includes(task_type);
+}
+function skip_line(task_type) {
+  return `\u{1F515} ${task_type} notifications are not opted in (${OPT_IN_KEY}).`;
+}
+var notify_opt_in = { is_skipped, skip_line };
+
+// scripts/notify/telegram-notify.ts
 var TELEGRAM_API_BASE = "https://api.telegram.org";
 var TELEGRAM_TEXT_LIMIT = 4096;
 var BODY_TRUNCATION_MARK = "\n...";
@@ -377,6 +423,12 @@ function load_config() {
 function is_notify_disabled() {
   return parse_environment_string(process.env[NOTIFY_SWITCH_KEY]).toLowerCase() === NOTIFY_OFF_VALUE;
 }
+function skip_line2(task_type) {
+  if (is_notify_disabled()) {
+    return `\u{1F515} Telegram notifications are disabled (${NOTIFY_SWITCH_KEY}=${NOTIFY_OFF_VALUE}).`;
+  }
+  return notify_opt_in.is_skipped(task_type) ? notify_opt_in.skip_line(task_type) : void 0;
+}
 function build_header(task_type, repo_name) {
   const { icon, label } = TASK_DEFINITIONS[task_type];
   if (repo_name === void 0 || repo_name.length === 0) return `${icon} ${label}`;
@@ -402,6 +454,7 @@ function build_url_parts(input) {
 function build_blocks(input) {
   const blocks = [build_title_block(input)];
   push_if_present(blocks, input.body);
+  push_if_present(blocks, input.choices);
   blocks.push(...build_url_parts(input));
   return blocks;
 }
@@ -435,10 +488,9 @@ function build_send_failure(error, config) {
   return new Error(`${SEND_FAILED_PREFIX}: ${reason}`, { cause: new Error(reason) });
 }
 async function send(input) {
-  if (is_notify_disabled()) {
-    console.info(
-      `\u{1F515} Telegram notifications are disabled (${NOTIFY_SWITCH_KEY}=${NOTIFY_OFF_VALUE}).`
-    );
+  const skipped = skip_line2(input.task_type);
+  if (skipped !== void 0) {
+    console.info(skipped);
     return;
   }
   const config = load_config();
@@ -487,6 +539,7 @@ async function confirm(input) {
       repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
       issue_title: input.issue_title,
       body: input.body,
+      choices: confirmation_options.block(input),
       issue_url: void 0,
       pr_url: void 0
     },
@@ -762,7 +815,7 @@ var stop_payload_schema = z3.object({
   last_assistant_message: z3.string().nullish()
 });
 var NO_OUTCOME = { reason: void 0 };
-var STOP_NOTIFY_REASON = '\u26D4 mid-workflow stop notification: this working tree is still held by a run and no `confirmation` Telegram was sent this turn, so a person is being left to wait off-screen without knowing the run paused. `CLAUDE.md` \u2192 "Mid-workflow stop notification" requires `pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\'` before any mid-workflow pause. Send it, then end with a one-line confirmation that it was sent \u2014 do not repeat your previous reply. This fires only while the hold is held and no notify is on the transcript, and `stop_hook_active` lets a second stop through so a run is never wedged.';
+var STOP_NOTIFY_REASON = '\u26D4 mid-workflow stop notification: this working tree is still held by a run and no `confirmation` Telegram was sent this turn, so a person is being left to wait off-screen without knowing the run paused. `CLAUDE.md` \u2192 "Mid-workflow stop notification" requires `pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\' --recommended "<choice>" --alternative "<choice>"` before any mid-workflow pause. Send it, then end with a one-line confirmation that it was sent \u2014 do not repeat your previous reply. This fires only while the hold is held and no notify is on the transcript, and `stop_hook_active` lets a second stop through so a run is never wedged.';
 var HOLD_RELEASE_REASON = "\u26D4 working-tree hold not released: this working tree is clean but its `run:hold` record is still in place, so the next run here runs `pnpm josh ms` believing the tree is free while you hold it. The workflow-commands skill \u2192 `working-tree-hold.md`: a stop that leaves the tree clean releases the hold with `pnpm josh run:release <N>` (bare for a `new` entry). A `halfrun` pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty, and a `prrun` stop keeps it by its stop mark \u2014 this row is silent there. Release it, then end with a one-line confirmation that it was released \u2014 do not repeat your previous reply.";
 var ISSUE_CITATION_REASON = "Session-facing output cites an Issue as a number-link so the reader can click through and see which repository it is (`CLAUDE.md`, `prompts/collaboration-workflow/issue-citation.md`).";
 function build_citation_reason(references) {

package/dist/josh.js

@@ -2747,7 +2747,7 @@ var WORKFLOW_COMMANDS = {
     description: "Send Telegram notification",
     category: "Workflow",
     reference: [
-      "[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]",
+      "[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>] [--recommended <text>] [--alternative <text>]...",
       "automation",
       ["notifications"]
     ],

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1453.0",
+  "version": "1.1455.0",
   "name": "@joshuafolkken/kit",
   "description": "Development toolkit for AI-assisted projects: formatting, AI assistant rules and a Git/GitHub Issue workflow for any repository, plus lint, type check, tests and hooks for Node projects",
   "keywords": [

package/prompts/collaboration-workflow/shell-body.md

@@ -25,7 +25,7 @@ zsh は `pnpm josh ms` を実行し、その標準出力を本文に埋め込む
 pnpm josh issue:comment <N> --body-file <path>
 gh api -X PATCH repos/{owner}/{repo}/issues/<N> --field body=@<path>
 pnpm josh followup "<title> #<N>" --notify-message-file <path>
-pnpm josh notify --task-type confirmation --issue-url "<url>" --body-file <path>
+pnpm josh notify --task-type confirmation --issue-url "<url>" --body-file <path> --recommended "<choice>"
 ```
 
 **PR コメントも同じ経路である** — REST では pull request のコメントは issue のコメントであり、`pnpm josh issue:comment <N> --body-file <path>` がそのまま使える。`gh issue comment` / `gh pr comment` は使わない（GraphQL 経由。理由は `docs/maintainers/shell-body-rationale.md` → "Why no `gh` subcommand is written in an executable block"）。

package/scripts/gh/git-pr-ai-review.ts

@@ -89,6 +89,10 @@ async function fetch_review_comments(
 	return parsed?.map((comment) => to_review_comment(comment))
 }
 
+// The other choice both AI-review stops offer: a person who has looked records why and moves on.
+const IGNORE_ALTERNATIVE =
+	'Re-run `pnpm josh followup --ai-review-ignore-reason "<reason>"` if the gate does not apply'
+
 async function handle_blockers(input: {
 	branch_name: string
 	ignore_reason: string | undefined
@@ -105,7 +109,12 @@ async function handle_blockers(input: {
 		return
 	}
 
-	await git_pr_confirmation.notify_confirmation({ context: input.context, body })
+	await git_pr_confirmation.notify_confirmation({
+		context: input.context,
+		body,
+		recommended: 'Fix the findings and re-run `pnpm josh followup`',
+		alternatives: [IGNORE_ALTERNATIVE],
+	})
 
 	throw new Error(body)
 }
@@ -140,6 +149,8 @@ async function handle_unreadable_comments(input: {
 	await git_pr_confirmation.notify_confirmation({
 		context: input.context,
 		body: UNREADABLE_COMMENTS_BODY,
+		recommended: 'Re-run `pnpm josh followup` once the comments can be read',
+		alternatives: [IGNORE_ALTERNATIVE],
 	})
 
 	throw new Error(UNREADABLE_COMMENTS_BODY)

package/scripts/gh/git-pr-confirmation.ts

@@ -1,3 +1,7 @@
+import {
+	confirmation_options,
+	type ConfirmationOptions,
+} from '#scripts/notify/confirmation-options'
 import { telegram_notify, type TelegramSendInput } from '#scripts/notify/telegram-notify'
 
 // What to type when the confirmation notification itself could not be delivered.
@@ -5,7 +9,7 @@ import { telegram_notify, type TelegramSendInput } from '#scripts/notify/telegra
 // commands and a backtick inside shell double quotes is evaluated before the command runs.
 const CONFIRMATION_RECOVERY =
 	'send it by hand — `pnpm josh notify --task-type confirmation --issue-url <url> ' +
-	'--body-file <path>`'
+	'--body-file <path> --recommended "<choice>"`'
 
 interface TelegramContext {
 	repo_name: string | undefined
@@ -14,15 +18,18 @@ interface TelegramContext {
 	pr_url: string | undefined
 }
 
-function build_confirmation_input(input: {
+interface ConfirmationInput extends ConfirmationOptions {
 	context: TelegramContext
 	body: string
-}): TelegramSendInput {
+}
+
+function build_confirmation_input(input: ConfirmationInput): TelegramSendInput {
 	return {
 		task_type: 'confirmation',
 		repo_name: input.context.repo_name,
 		issue_title: input.context.issue_title,
 		body: input.body,
+		choices: confirmation_options.block(input),
 		issue_url: input.context.issue_url,
 		pr_url: input.context.pr_url,
 	}
@@ -34,10 +41,7 @@ function build_confirmation_input(input: {
 //
 // Unlike the completion notification, this one *has* a recovery: a `confirmation` is exactly what
 // `josh notify` is for, and the run stops here anyway, so re-sending it by hand loses nothing.
-async function notify_confirmation(input: {
-	context: TelegramContext
-	body: string
-}): Promise<void> {
+async function notify_confirmation(input: ConfirmationInput): Promise<void> {
 	await telegram_notify.send_or_report(build_confirmation_input(input), CONFIRMATION_RECOVERY)
 }
 

package/scripts/josh/josh-commands-workflow.ts

@@ -47,7 +47,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Send Telegram notification',
 		category: 'Workflow',
 		reference: [
-			'[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]',
+			'[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>] [--recommended <text>] [--alternative <text>]...',
 			'automation',
 			['notifications'],
 		],

package/scripts/notify/confirmation-options.ts

@@ -0,0 +1,59 @@
+import { session_language } from '#scripts/josh/session-language'
+
+// **A confirmation names what to choose, not only why the run stopped.** The person reading it is
+// off-screen by definition, so the message itself carries the recommended choice and the others —
+// in the session language, because that is the language the person works in.
+
+interface ConfirmationOptions {
+	recommended: string
+	alternatives: ReadonlyArray<string>
+}
+
+interface Headings {
+	recommended: string
+	alternatives: string
+	none: string
+}
+
+const JAPANESE_LANG_PREFIX = 'ja'
+const JAPANESE_HEADINGS: Headings = {
+	recommended: '推奨:',
+	alternatives: '他の選択肢:',
+	none: 'なし',
+}
+const ENGLISH_HEADINGS: Headings = {
+	recommended: 'Recommended:',
+	alternatives: 'Alternatives:',
+	none: 'none',
+}
+
+// Only the two languages the workflow is written in have headings; any other falls back to English.
+function headings(): Headings {
+	const { lang } = session_language.resolve_session_lang()
+
+	return lang.toLowerCase().startsWith(JAPANESE_LANG_PREFIX) ? JAPANESE_HEADINGS : ENGLISH_HEADINGS
+}
+
+// An empty list is stated as none, so a confirmation with no other option says so rather than
+// leaving a reader to wonder whether the line was lost.
+function alternatives_block(options: ConfirmationOptions, labels: Headings): string {
+	if (options.alternatives.length === 0) return `${labels.alternatives} ${labels.none}`
+
+	const lines = options.alternatives.map((alternative) => `- ${alternative}`)
+
+	return [labels.alternatives, ...lines].join('\n')
+}
+
+// The block is handed to the sender as its own `choices` field rather than appended to the body:
+// the body is what a too-long message is cut from, and the choices are the one part a reader cannot
+// act without, so they must survive the cut.
+function block(options: ConfirmationOptions): string {
+	const labels = headings()
+
+	return `${labels.recommended} ${options.recommended}\n${alternatives_block(options, labels)}`
+}
+
+const confirmation_options = { block }
+
+export { confirmation_options }
+export type { ConfirmationOptions }

package/scripts/notify/notify-opt-in.ts

@@ -0,0 +1,33 @@
+import type { TelegramTaskType } from './telegram-notify'
+
+// **`planning` and `completion` reach a person only when they asked for them.** Neither needs the
+// person to act now — a plan is posted on the Issue and a merge is visible on the pull request — so
+// sending both on every run buried the types that do need someone. Every other type is unaffected.
+//
+// **One variable listing the opted-in types, not one switch per type**, so making a further type
+// optional later adds an entry to `OPTIONAL_TASK_TYPES` rather than another variable.
+const OPT_IN_KEY = 'JOSH_NOTIFY_OPT_IN'
+const OPTIONAL_TASK_TYPES: ReadonlySet<TelegramTaskType> = new Set(['planning', 'completion'])
+const LIST_SEPARATOR = ','
+
+function opted_in_types(): ReadonlyArray<string> {
+	return (process.env[OPT_IN_KEY] ?? '')
+		.split(LIST_SEPARATOR)
+		.map((entry) => entry.trim().toLowerCase())
+		.filter((entry) => entry.length > 0)
+}
+
+// Unset means none: an optional type is sent only once it is named.
+function is_skipped(task_type: TelegramTaskType): boolean {
+	if (!OPTIONAL_TASK_TYPES.has(task_type)) return false
+
+	return !opted_in_types().includes(task_type)
+}
+
+function skip_line(task_type: TelegramTaskType): string {
+	return `🔕 ${task_type} notifications are not opted in (${OPT_IN_KEY}).`
+}
+
+const notify_opt_in = { is_skipped, skip_line }
+
+export { notify_opt_in }

package/scripts/notify/telegram-notify.ts

@@ -1,6 +1,8 @@
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { z } from 'zod'
+import { confirmation_options, type ConfirmationOptions } from './confirmation-options'
+import { notify_opt_in } from './notify-opt-in'
 
 const TELEGRAM_API_BASE = 'https://api.telegram.org'
 // `sendMessage` refuses a text longer than this.
@@ -42,6 +44,9 @@ interface TelegramSendInput {
 	repo_name: string | undefined
 	issue_title: string | undefined
 	body: string | undefined
+	// A confirmation's recommended choice and the others — set beside the body rather than inside it
+	// so a body cut to the length limit never takes the choices with it.
+	choices?: string | undefined
 	issue_url: string | undefined
 	pr_url: string | undefined
 }
@@ -149,6 +154,16 @@ function is_notify_disabled(): boolean {
 	return parse_environment_string(process.env[NOTIFY_SWITCH_KEY]).toLowerCase() === NOTIFY_OFF_VALUE
 }
 
+// The line a skipped send prints, or `undefined` for a send that goes out. The blanket opt-out wins
+// over the per-type opt-in, so `off` stays the one switch that silences everything.
+function skip_line(task_type: TelegramTaskType): string | undefined {
+	if (is_notify_disabled()) {
+		return `🔕 Telegram notifications are disabled (${NOTIFY_SWITCH_KEY}=${NOTIFY_OFF_VALUE}).`
+	}
+
+	return notify_opt_in.is_skipped(task_type) ? notify_opt_in.skip_line(task_type) : undefined
+}
+
 function build_header(task_type: TelegramTaskType, repo_name: string | undefined): string {
 	const { icon, label } = TASK_DEFINITIONS[task_type]
 	if (repo_name === undefined || repo_name.length === 0) return `${icon} ${label}`
@@ -185,6 +200,7 @@ function build_blocks(input: TelegramSendInput): Array<string> {
 	const blocks: Array<string> = [build_title_block(input)]
 
 	push_if_present(blocks, input.body)
+	push_if_present(blocks, input.choices)
 	blocks.push(...build_url_parts(input))
 
 	return blocks
@@ -243,13 +259,13 @@ function build_send_failure(error: unknown, config: TelegramConfig): Error {
 //
 // The failure it throws carries a `cause`, and that cause is redacted too — see `build_send_failure`.
 //
-// The opt-out is checked here, before `load_config`, so every caller — the tolerant form included —
-// skips the same way and none has to repeat the check.
+// The opt-out and the per-type opt-in are checked here, before `load_config`, so every caller — the
+// tolerant form included — skips the same way and none has to repeat the check.
 async function send(input: TelegramSendInput): Promise<void> {
-	if (is_notify_disabled()) {
-		console.info(
-			`🔕 Telegram notifications are disabled (${NOTIFY_SWITCH_KEY}=${NOTIFY_OFF_VALUE}).`,
-		)
+	const skipped = skip_line(input.task_type)
+
+	if (skipped !== undefined) {
+		console.info(skipped)
 
 		return
 	}
@@ -341,7 +357,7 @@ async function warn(input: WarningInput): Promise<boolean> {
 	)
 }
 
-interface ConfirmInput {
+interface ConfirmInput extends ConfirmationOptions {
 	issue_title: string
 	body: string
 	recovery: string
@@ -365,6 +381,7 @@ async function confirm(input: ConfirmInput): Promise<boolean> {
 			repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
 			issue_title: input.issue_title,
 			body: input.body,
+			choices: confirmation_options.block(input),
 			issue_url: undefined,
 			pr_url: undefined,
 		},
@@ -463,4 +480,4 @@ const telegram_notify = {
 }
 
 export { telegram_notify, build_text, TASK_DEFINITIONS, telegram_environment_schema }
-export type { TelegramSendInput, TelegramTaskType }
+export type { ConfirmInput, TelegramSendInput, TelegramTaskType }

package/scripts/notify/telegram-test-logic.ts

@@ -1,4 +1,5 @@
 import { cli_body } from '#scripts/josh/cli-body'
+import { confirmation_options } from './confirmation-options'
 import type { TelegramSendInput, TelegramTaskType } from './telegram-notify'
 
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -10,6 +11,8 @@ interface CliValues {
 	'body-file'?: string
 	'issue-url'?: string
 	'pr-url'?: string
+	recommended?: string
+	alternative?: Array<string>
 }
 /* eslint-enable @typescript-eslint/naming-convention */
 
@@ -67,12 +70,41 @@ function normalize_body(values: CliValues): string | undefined {
 	})
 }
 
+// **A confirmation without a recommended choice is refused, not sent**: the person it reaches is
+// off-screen, and a stop that names no choice leaves them to reconstruct one. `--alternative` may be
+// absent — a stop with one way forward says so — so only `--recommended` is required.
+function require_recommended(values: CliValues): string {
+	const recommended = values.recommended?.trim() ?? ''
+
+	if (recommended.length === 0) {
+		throw new Error('--task-type confirmation needs --recommended "<the recommended choice>".')
+	}
+
+	return recommended
+}
+
+function given_alternatives(values: CliValues): Array<string> {
+	return (values.alternative ?? []).filter((alternative) => alternative.trim().length > 0)
+}
+
+function build_choices(values: CliValues, task_type: TelegramTaskType): string | undefined {
+	if (task_type !== 'confirmation') return undefined
+
+	return confirmation_options.block({
+		recommended: require_recommended(values),
+		alternatives: given_alternatives(values),
+	})
+}
+
 function build_input(input: { values: CliValues; context: ResolvedContext }): TelegramSendInput {
+	const task_type = parse_task_type(input.values['task-type'])
+
 	return {
-		task_type: parse_task_type(input.values['task-type']),
+		task_type,
 		repo_name: coalesce(input.values['repo-name'], input.context.repo_name),
 		issue_title: coalesce(input.values['issue-title'], input.context.issue_title),
 		body: normalize_body(input.values),
+		choices: build_choices(input.values, task_type),
 		issue_url: input.values['issue-url'],
 		pr_url: input.values['pr-url'],
 	}

package/scripts/notify/telegram-test.ts

@@ -14,10 +14,10 @@ const REPO_NAME_SEPARATOR = '/'
 const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
 const USAGE =
-	'Usage: josh notify [--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]'
+	'Usage: josh notify [--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>] [--recommended <text>] [--alternative <text>]...'
 
 // The free-text values a caller writes, often opening with a Markdown `-` bullet.
-const FREE_TEXT_FLAGS = ['--body', '--issue-title']
+const FREE_TEXT_FLAGS = ['--body', '--issue-title', '--recommended', '--alternative']
 
 const OPTIONS = {
 	'task-type': { type: 'string' },
@@ -27,6 +27,8 @@ const OPTIONS = {
 	'body-file': { type: 'string' },
 	'issue-url': { type: 'string' },
 	'pr-url': { type: 'string' },
+	recommended: { type: 'string' },
+	alternative: { type: 'string', multiple: true },
 } as const
 
 // `undefined` for a line nobody can read — an unknown flag, or a flag given no value.

package/scripts/rules/shell-body-trigger.ts

@@ -6,7 +6,8 @@
 
 // A body handed to a command as an inline double-quoted argument, in the spellings a run reaches for:
 // `gh`'s field flags (`-f` / `-F` / `--field` / `--raw-field` with `body=`), `gh`'s own `--body`, and
-// `josh`'s `--body` and `--notify-message`. The value is captured so the decision can be made on what
+// `josh`'s `--body` and `--notify-message`, and `josh notify`'s `--recommended` / `--alternative` —
+// free text every confirmation carries, naming the very commands a backtick would run. The value is captured so the decision can be made on what
 // the body actually contains rather than on the flag alone.
 //
 // **`-b` is deliberately absent.** It is `gh`'s short `--body`, but it is also `git checkout -b`, and
@@ -14,7 +15,7 @@
 // spellings end in `-` where this pattern needs whitespace or `=`, so `--body-file <path>` and
 // `--notify-message-file <path>` cannot match it.
 const FIELD_FLAGS = '(?:-f|-F|--field|--raw-field)'
-const MESSAGE_FLAGS = '(?:--body|--notify-message)'
+const MESSAGE_FLAGS = '(?:--body|--notify-message|--recommended|--alternative)'
 
 // **The opening quote sits on either side of `body=`, and both spellings are the same command.** zsh
 // strips the quotes before `gh` is started, so `-f body="… \`pnpm josh ms\` …"` and

package/scripts/rules/stop-rules.ts

@@ -103,7 +103,8 @@ const STOP_NOTIFY_REASON =
 	'⛔ mid-workflow stop notification: this working tree is still held by a run and no `confirmation` ' +
 	'Telegram was sent this turn, so a person is being left to wait off-screen without knowing the run ' +
 	'paused. `CLAUDE.md` → "Mid-workflow stop notification" requires ' +
-	'`pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\'` before any ' +
+	'`pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\' ' +
+	'--recommended "<choice>" --alternative "<choice>"` before any ' +
 	'mid-workflow pause. Send it, then end with a one-line confirmation that it was sent — do not repeat ' +
 	'your previous reply. This fires only while the hold is held and no notify is on the transcript, and ' +
 	'`stop_hook_active` lets a second stop through so a run is never wedged.'

package/scripts/run/entry/run-entry-stop.ts

@@ -1,6 +1,6 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command } from '#scripts/josh/josh-run'
-import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { telegram_notify, type ConfirmInput } from '#scripts/notify/telegram-notify'
 import { lane_park } from '#scripts/rules/lane-park'
 
 // What `run:entry` does on the way out of a stop it decided itself.
@@ -26,14 +26,15 @@ interface StopNotice {
 }
 
 interface StopPorts {
-	notify: (input: { issue_title: string; body: string; recovery: string }) => Promise<boolean>
+	notify: (input: ConfirmInput) => Promise<boolean>
 	release: (issue_number: string) => Promise<boolean>
 	is_parking_child: () => boolean
 }
 
 const RECOVERY = 'If this did not arrive, the run:entry output in the session names the stop.'
+const LATER_ALTERNATIVE = 'Leave the Issue for a later session — nothing was changed'
 const NOTIFY_FAILED_NOTE =
-	'(the confirmation Telegram could not be sent — send it with `pnpm josh notify --task-type confirmation` before stopping)'
+	'(the confirmation Telegram could not be sent — send it with `pnpm josh notify --task-type confirmation --recommended "<choice>"` before stopping)'
 const RELEASED_NOTE = '(hold released by run:entry — the tree is free for the resume)'
 const RELEASE_FAILED_NOTE =
 	'(the hold could not be released — run `pnpm josh run:release` before stopping)'
@@ -78,6 +79,8 @@ async function notify_stop(notice: StopNotice, ports: StopPorts): Promise<void>
 		issue_title: `${notice.command} ${issue_cite.plain(notice.issue_number)} stopped`,
 		body: body_of(notice),
 		recovery: RECOVERY,
+		recommended: `Run \`${notice.command} ${issue_cite.plain(notice.issue_number)}\` again in a fresh session`,
+		alternatives: [LATER_ALTERNATIVE],
 	})
 
 	console.info(is_sent ? lane_park.COMMAND_NOTIFY_MARKER : NOTIFY_FAILED_NOTE)

package/scripts/run/run-stop-notify.ts

@@ -38,6 +38,8 @@ async function announce(notice: StopNotice): Promise<boolean> {
 		issue_title: STOP_TITLE,
 		body: notice.reason,
 		recovery: STOP_RECOVERY,
+		recommended: 'Resolve the reason above, then run `backlogrun` again',
+		alternatives: ['Leave the backlog stopped until a later session'],
 	})
 }