pi-quiver 6.7.0 → 6.8.0

package/CHANGELOG.md

@@ -8,6 +8,15 @@ Published to npm as `pi-quiver` (`pi install npm:pi-quiver`). Pushing a
 via OIDC trusted publishing. The release helper at
 `.agents/skills/release/scripts/release.sh` cuts the tag; CI publishes.
 
+## v6.8.0 - 2026-10-01
+
+- `session-name`: opt-in automatic naming starts in the background after three completed model/tool rounds. Shorter runs start a non-blocking attempt at run end; initial generation is best-effort with a 30-second local deadline and no automatic retry per session activation.
+
+## v6.7.1 - 2026-10-01
+
+- `slack_post`/`slack_update` explain native Slack representations for skill-required formatting, with complete readable fallback; otherwise plain content stays plain.
+- `slack_post` announcements carry native blocks in the detail reply without upload fallback and preserve structured detail in JSON for existing-thread recovery.
+
 ## v6.7.0 - 2026-09-30
 
 - README: `swordHeader` note on why pi's built-in logo flashes before the sword appears and how `quietStartup` removes it.

package/README.md

@@ -199,7 +199,7 @@ same outcome here because `enabled` is the only field either layer sets, but
 the merge is per-field: a global field with no project counterpart would
 survive untouched.
 
-`sessionAutoName.enabled` makes one extra short LLM call per session (once, after the first turn) to title it; `false` (default) makes no model calls. `rules` appends house conventions to the naming prompt (later rules win when they conflict with the built-ins). Literal, case-insensitive `deny` phrases are stripped from every name; whitespace inside a phrase is loose, so `"acme corp"` also catches `AcmeCorp`. `revisitFirstTurn` re-evaluates the name once that many model round trips have completed, while `revisitEveryTurns` does so at every multiple; both default to `0` (off) because each revisit costs another short LLM call. For example, `10` and `100` mark round trips 10, 100, 200, 300. Revisits only run when the agent has fully settled (idle, nothing queued) - an automated multi-turn run such as a subagent chain is never renamed or delayed mid-flight; cadence points it crossed fire once, at the settle. A machine-generated name is replaced when stale. A name set by a human is never overwritten: the extension strongly prefers it, and announces a suggestion only when the work has clearly moved on. Counts come from the persisted transcript, so they survive resume.
+`sessionAutoName.enabled` starts one background initial naming attempt for an unnamed session after three completed model/tool rounds in the current agent run, not three user messages. A round is one completed assistant turn and its tool results, regardless of how many tools run. If the run ends sooner, it starts the same background attempt at run end. Initial naming is best-effort: preparation and generation have a 30-second local deadline, and the agent, editor return, and shutdown do not wait for naming. The session can remain unnamed if generation fails, times out, or the process exits first; there is no automatic retry during that session activation, though reopening an unnamed session allows another attempt on its next run. An existing name suppresses initial naming, and a human rename while generation is pending takes precedence. `false` (default) makes no automatic naming model calls. `rules` appends house conventions to the naming prompt (later rules win when they conflict with the built-ins). Literal, case-insensitive `deny` phrases are stripped from every name; whitespace inside a phrase is loose, so `"acme corp"` also catches `AcmeCorp`. `revisitFirstTurn` re-evaluates the name once that many model round trips have completed, while `revisitEveryTurns` does so at every multiple; both default to `0` (off) because each revisit costs another short LLM call. For example, `10` and `100` mark round trips 10, 100, 200, 300. Revisits only run when the agent has fully settled (idle, nothing queued) - an automated multi-turn run such as a subagent chain is never renamed or delayed mid-flight by a revisit; cadence points it crossed fire once, at the settle. A machine-generated name is replaced when stale. A name set by a human is never overwritten: the extension strongly prefers it, and announces a suggestion only when the work has clearly moved on. Revisit counts come from the persisted transcript, so they survive resume.
 
 `herdrTab` (default `true`) mirrors the same curated label to the Herdr tab bar over Herdr's unix socket, independent of `ghosttyTab` - either sink can be toggled off without affecting the other. A tab is claimable while its label is a bare number (`1`, `4`, ...) at any position - Herdr's vocabulary for "unnamed" - so reordering tabs before or after naming never matters; a tab you deliberately name `3` is taken over too. A non-numeric label is treated as a human's and is never overwritten; the check repeats every turn, so renumbering the tab by hand hands it back. Exactly one leading `* ` (herdr-ntfy-notify's armed marker) is not a human rename - it is preserved across renames and the shutdown restore, and removing it keeps the claim. Every session claims afresh: on each shutdown (quit, reload, `/new`, resume, fork) a claimed tab is restored to its then-current position number, and the successor session in the pane claims it again on its first name. The label the extension writes is never digits-only - a bare `1234` becomes `#1234`, and the naming prompt asks the model for `PR 1234` / `issue 123` / `ticket ABC-123` instead of a bare ID. It only ever runs in TUI mode, on an attached TTY, under Herdr (`HERDR_ENV`/`HERDR_TAB_ID`/`HERDR_SOCKET_PATH` all set) - `pi -p`/json/rpc runs and background subagents never touch the tab. Caveat: the restored number is internally a custom name (Herdr has no clear-to-auto API), so that tab keeps a number-looking label but stops renumbering on later tab closes/reorders.
 

package/extensions/session-name.ts

@@ -2,7 +2,7 @@
  * Session naming.
  *
  * - /session-name [name]  : manually set or show the session name.
- * - Auto-naming           : after the first agent turn, derive a concise name
+ * - Auto-naming           : after three rounds (or a shorter run), derive a name
  *                           from the conversation (unless one is already set).
  * - Revisiting            : re-derive the name later in a long session, once
  *                           the work has revealed what it actually is.
@@ -372,16 +372,21 @@ export function withAuthBaseUrl<M extends { baseUrl: string }>(
 	return auth.baseUrl ? { ...model, baseUrl: auth.baseUrl } : model;
 }
 
-async function generateName(
+export async function generateName(
 	ctx: ExtensionContext,
 	opts: PromptOptions = {},
+	signal?: AbortSignal,
+	getComplete: () => Promise<CompleteFn> = loadComplete,
 ): Promise<typeof KEEP | GeneratedName | undefined> {
+	if (signal?.aborted) return undefined;
 	const conversation = buildConversationText(ctx, 4000, Boolean(opts.currentName));
 	if (conversation.length < 8) return undefined;
 
 	const model = ctx.model;
 	if (!model) return undefined;
+	const prompt = buildNamingPrompt(conversation, opts);
 	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (signal?.aborted) return undefined;
 	// ok=true with apiKey=undefined is the env-key path: the key lives in
 	// process.env (e.g. ANTHROPIC_API_KEY), not auth.json. getApiKeyAndHeaders
 	// deliberately opts out of the env fallback (includeFallback: false), so it
@@ -389,9 +394,8 @@ async function generateName(
 	// itself via withEnvApiKey/getEnvApiKey. Only bail when auth genuinely failed.
 	if (!auth?.ok) return undefined;
 
-	const prompt = buildNamingPrompt(conversation, opts);
-
-	const complete = await loadComplete();
+	const complete = await getComplete();
+	if (signal?.aborted) return undefined;
 	const response = await complete(
 		withAuthBaseUrl(model, auth),
 		{
@@ -399,9 +403,10 @@ async function generateName(
 				{ role: "user" as const, content: [{ type: "text" as const, text: prompt }], timestamp: Date.now() },
 			],
 		},
-		{ apiKey: auth.apiKey, headers: auth.headers, env: auth.env, reasoningEffort: "low" },
+		{ apiKey: auth.apiKey, headers: auth.headers, env: auth.env, reasoningEffort: "low", signal },
 	);
 
+	if (signal?.aborted) return undefined;
 	const raw = response.content
 		.filter((c): c is { type: "text"; text: string } => c.type === "text")
 		.map((c) => c.text)
@@ -413,10 +418,16 @@ async function generateName(
 type NameGenerator = (
 	ctx: ExtensionContext,
 	opts?: PromptOptions,
+	signal?: AbortSignal,
 ) => Promise<typeof KEEP | GeneratedName | undefined>;
 
 export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = generateName) {
 	let autoNameTried = false;
+	let activation = 0;
+	let initialRounds = 0;
+	let initialDone: Promise<void> = Promise.resolve();
+	let initialAttempt: { cancel: () => void } | null = null;
+	const invalidateInitial = (): void => { initialAttempt?.cancel(); };
 	// Who chose the current name. A human's wording is never overwritten by a
 	// revisit - at most we suggest - so unknown provenance (a resumed session, a
 	// rename from outside this extension) is treated as human.
@@ -472,6 +483,7 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		tabLabel?: string,
 		author?: NameAuthor,
 		mode?: Mode,
+		ownsName?: () => boolean,
 	): Promise<void> => {
 		const clean = applyDenyList(name, cfg.deny);
 		if (author) recordNameAuthor(clean, author);
@@ -480,7 +492,7 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		lastSyncedName = clean;
 		currentTabLabel = toTabLabel(applyDenyList(tabLabel ?? clean, cfg.deny));
 		renameGhosttyTab(currentTabLabel, cfg.ghosttyTab);
-		await syncHerdrTab(cfg, currentTabLabel, mode);
+		await syncHerdrTab(cfg, currentTabLabel, mode, ownsName);
 	};
 
 	// Re-assert the tab from the current session name. Self-heals when the name
@@ -533,19 +545,23 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		return { claimable: false, armed: false };
 	};
 
-	const syncHerdrTab = (cfg: Config, label: string | null, mode: Mode | undefined): Promise<void> => {
+	const syncHerdrTab = (cfg: Config, label: string | null, mode: Mode | undefined, ownsName?: () => boolean): Promise<void> => {
 		const run = async (): Promise<void> => {
+			if (ownsName && !ownsName()) return;
 			if (!cfg.herdrTab || mode !== "tui" || !label) return;
 			if (!isHerdrActive()) return;
 			const sock = process.env.HERDR_SOCKET_PATH as string;
 			const tabId = process.env.HERDR_TAB_ID as string;
 			const live = await getTab(sock, tabId, HERDR_TIMEOUT_MS);
+			if (ownsName && !ownsName()) return;
 			if (!live) return; // transient or stale tab id; a failed read is never a human rename
 			if (typeof herdrClaim === "object" && herdrClaim !== null) {
 				const owned = matchOwned(live.label, herdrClaim.lastWritten);
 				if (owned.owned) {
 					if (label === herdrClaim.lastWritten) return;
-					if (await renameTab(sock, tabId, (owned.armed ? ARMED_PREFIX : "") + label, HERDR_TIMEOUT_MS)) herdrClaim.lastWritten = label;
+					if (await renameTab(sock, tabId, (owned.armed ? ARMED_PREFIX : "") + label, HERDR_TIMEOUT_MS)) {
+						herdrClaim.lastWritten = label;
+					}
 					return;
 				}
 			}
@@ -589,6 +605,7 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		handler: async (args, ctx) => {
 			const name = args.trim();
 			if (name) {
+				invalidateInitial();
 				autoNameTried = true; // manual name wins; don't auto-overwrite later
 				await setName(loadConfig(ctx), name, undefined, "human", ctx.mode);
 				ctx.ui.notify(`Session named: ${pi.getSessionName()}`, "info");
@@ -600,6 +617,15 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		invalidateInitial();
+		activation++;
+		autoNameTried = false;
+		initialRounds = 0;
+		nameAuthor = "human";
+		lastRevisitAt = 0;
+		expectedInternalName = null;
+		lastSyncedName = null;
+		currentTabLabel = null;
 		// Every session claims afresh, exactly like a fresh process: /new, resume,
 		// and fork each tear the previous session down (restore included) first.
 		// Before loadConfig so `enabled: false, herdrTab: true` resets too.
@@ -636,6 +662,8 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 			return;
 		}
 		expectedInternalName = null;
+		invalidateInitial();
+		autoNameTried = true;
 		if (!current) return;
 		const cfg = loadConfig(ctx);
 		if (!cfg.enabled) return;
@@ -659,24 +687,60 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 	// internally a custom name - Herdr has no clear-to-auto API - so it won't
 	// renumber on reorders; the successor claims any numeric label regardless.
 	pi.on("session_shutdown", async () => {
+		invalidateInitial();
+		activation++;
 		await restoreHerdrTab();
 	});
 
-	pi.on("agent_end", async (_event, ctx) => {
+	const startInitial = (ctx: ExtensionContext): void => {
 		if (autoNameTried || pi.getSessionName()) return;
 		const cfg = loadConfig(ctx);
-		if (!cfg.enabled) return; // off by default; opt in via settings.json
+		if (!cfg.enabled) return;
 		autoNameTried = true;
-		try {
-			const generated = await generate(ctx, { rules: cfg.rules });
-			if (generated && generated !== KEEP && !pi.getSessionName()) {
-				await setName(cfg, generated.sessionName, generated.tabLabel, "auto", ctx.mode);
-				if (ctx.hasUI) ctx.ui.notify(`Auto-named session: ${pi.getSessionName()}`, "info");
+		const identity = activation;
+		const mode = ctx.mode;
+		const notify = ctx.hasUI ? ctx.ui.notify.bind(ctx.ui) : undefined;
+		const controller = new AbortController();
+		let active = true;
+		let settle!: () => void;
+		initialDone = new Promise<void>((resolve) => { settle = resolve; });
+		const finish = (): void => {
+			if (!active) return;
+			active = false;
+			clearTimeout(timer);
+			if (initialAttempt === attempt) initialAttempt = null;
+			settle();
+		};
+		const attempt = { cancel: (): void => { finish(); controller.abort(); } };
+		const timer = setTimeout(attempt.cancel, 30_000);
+		timer.unref();
+		initialAttempt = attempt;
+		void (async () => {
+			try {
+				const generated = await generate(ctx, { rules: cfg.rules }, controller.signal);
+				if (!active || identity !== activation || controller.signal.aborted) return;
+				if (!generated || generated === KEEP || pi.getSessionName()) return;
+				clearTimeout(timer);
+				const applied = applyDenyList(generated.sessionName, cfg.deny);
+				await setName(cfg, generated.sessionName, generated.tabLabel, "auto", mode,
+					() => active && identity === activation && !controller.signal.aborted && pi.getSessionName() === applied);
+				if (active && identity === activation && !controller.signal.aborted && pi.getSessionName() === applied) {
+					notify?.(`Auto-named session: ${applied}`, "info");
+				}
+			} catch {
+				// Naming is best-effort, including late failures after cancellation.
+			} finally {
+				finish();
 			}
-		} catch {
-			// best-effort; ignore failures
-		}
+		})();
+	};
+
+	pi.on("agent_start", () => { initialRounds = 0; });
+	pi.on("turn_end", (_event, ctx) => {
+		initialRounds++;
+		if (initialRounds >= 3) startInitial(ctx);
 	});
+	pi.on("agent_end", (_event, ctx) => { startInitial(ctx); });
 
 	// Revisit. A name derived from the first turn describes the opening move,
 	// which is frequently not what the session turns out to be about - the work
@@ -724,7 +788,7 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		})();
 	});
 
-	return { revisitSettled: () => revisitDone };
+	return { initialSettled: () => initialDone, revisitSettled: () => revisitDone };
 }
 
 export default function (pi: ExtensionAPI) {

package/extensions/slack.ts

@@ -40,6 +40,19 @@ import {
 } from "../lib/slack-core.ts";
 import { cacheFilePath, teamIdFor, resolveChannel, refreshCache, resolveMentions, assertSameTeam, type CacheCtx } from "../lib/slack-cache.ts";
 
+const SLACK_FORMATTING_GUIDANCE: { rules: string[]; example: string } = {
+	rules: [
+		"For slack_post and slack_update, represent only formatting required by the calling skill. Keep otherwise plain content plain; preserve required structure rather than flattening it to a prose paragraph.",
+		'For slack_post and slack_update, use required lists as rich_text blocks containing rich_text_list with style: "bullet" or style: "ordered" and rich_text_section items. Preserve order and item boundaries; use line-separated text markers only in fallback, not as a substitute for the native list.',
+		"For slack_post and slack_update, represent required block quotations with rich_text_quote inside rich_text. Preserve quoted wording and supplied attribution. In text-only fallback, put > at the start of quoted lines and distinguish quotation from commentary; retain the required native quotation.",
+		"For slack_post and slack_update, inside rich_text represent required emphasis with text-element style properties bold, italic, strike; use code style for inline code, rich_text_preformatted for multiline code, and native link elements for labeled links. Keep mrkdwn delimiters out of native text leaves. On text-only surfaces, use *bold*, _italic_, ~strike~, backticks for inline code, triple-backticks for multiline code, and <url|label> for labeled links; code alone does not introduce blocks.",
+		"For slack_post and slack_update, preserve literal code. In text-only code and fallback, supply \\@name for literal mention-like names, including echo \\@alice for literal echo @alice; backticks do not suppress mention scanning. Rely on name lookup only in text and thread_body; treat @name in blocks as literal.",
+		"For slack_post and slack_update, when authoring blocks also supply complete readable fallback with substantive content, list item boundaries, and quotation/commentary distinctions for notifications and screen readers. Pair blocks with text for ordinary posts and updates, with thread_body ?? text for existing-thread replies, and with thread_body for announcement detail without thread_ts. Keep the announcement text headline text-only; blocks belong only to its detail. Without thread_body, blocks do not create an announcement. Pass caller-authored blocks through for Slack validation; existing blocks-only callers remain supported.",
+		"For slack_post and slack_update, keep blocks-bearing threaded replies and announcement details as messages: they bypass the local MAX_TEXT_LENGTH fallback guard and never use threshold-based or msg_too_long upload fallback.",
+	],
+	example: 'Native list example: {"text":"- First\\n- Second","blocks":[{"type":"rich_text","elements":[{"type":"rich_text_list","style":"bullet","elements":[{"type":"rich_text_section","elements":[{"type":"text","text":"First"}]},{"type":"rich_text_section","elements":[{"type":"text","text":"Second"}]}]}]}]}',
+};
+
 const IDENTITY = Type.Union([Type.Literal("user"), Type.Literal("bot")], {
 	description: 'Which token to act as: "user" (a real person, needed for slack_search/slack_thread) or "bot" (an app identity). Determines which credential source is used and whose name shows as the author.',
 });
@@ -302,14 +315,15 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Post",
 			promptSnippet: "Post a Slack message, reply, or headline+detail announcement",
 			description:
-				"Post a Slack message via chat.postMessage, as `as: \"user\"` or `as: \"bot\"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Plain post: `text` and/or `blocks` (Block Kit JSON, passed through unvalidated). Threaded reply: also set `thread_ts` - no headline is ever emitted, `thread_body` (or `text`) becomes the reply body. Announce mode: set `thread_body` WITHOUT `thread_ts` - posts a short single-line `text` headline, then posts `thread_body` as the first threaded reply in the same call; if `thread_body`'s rendered length exceeds the configured uploadThresholdChars (default 4000), it is delivered as a threaded file upload instead. Recovery: re-invoke with `thread_ts` set (never re-omit it) to post only into the existing thread - a second headline is never sent. On detail-delivery failure the headline is marked \"detail pending\" and the detail is saved to a temp file; the error names the path. `unfurl_links`/`unfurl_media` apply to this post only, are omitted when unset (Slack's default stands), and slack_update cannot change unfurling after the fact.",
+				"Post a Slack message via chat.postMessage, as `as: \"user\"` or `as: \"bot\"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Plain post: `text` and/or `blocks` (Block Kit JSON, passed through unvalidated). Threaded reply: also set `thread_ts` - no headline is ever emitted, `thread_body` (or `text`) becomes the reply body. Announce mode: set `thread_body` WITHOUT `thread_ts` - posts a short single-line `text` headline, then posts the detail `blocks` with `thread_body` fallback (or text-only `thread_body`) as the first threaded reply in the same call; for text-only detail, if `thread_body`'s rendered length exceeds the configured uploadThresholdChars (default 4000), it is delivered as a threaded file upload instead. Recovery: re-invoke with `thread_ts` set (never re-omit it) to post only into the existing thread - a second headline is never sent. On detail-delivery failure the headline is marked \"detail pending\" and the detail is saved to a temp file; the returned error supplies recovery-artifact details. `unfurl_links`/`unfurl_media` apply to this post only, are omitted when unset (Slack's default stands), and slack_update cannot change unfurling after the fact." + "\n\n" + SLACK_FORMATTING_GUIDANCE.rules.join("\n") + "\n\n" + SLACK_FORMATTING_GUIDANCE.example,
+			promptGuidelines: SLACK_FORMATTING_GUIDANCE.rules,
 			parameters: Type.Object({
 				as: IDENTITY,
 				channel: Type.String({ description: "#name, channel ID, @name, or user ID (DM)" }),
-				text: Type.Optional(Type.String({ description: "Message text, or the announce headline when thread_body is set" })),
-				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON array, passed through unvalidated" })),
+				text: Type.Optional(Type.String({ description: "Message fallback, or text-only announcement headline when thread_body is set without thread_ts" })),
+				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON for the posted body, or detail reply in combined announcements; passed through unvalidated" })),
 				thread_ts: Type.Optional(Type.String({ description: "Reply into this existing thread instead of posting a new headline" })),
-				thread_body: Type.Optional(Type.String({ description: "Detail body for an announce headline, or the reply body when thread_ts is set" })),
+				thread_body: Type.Optional(Type.String({ description: "Detail fallback in announce mode without thread_ts, or reply fallback when thread_ts is set" })),
 				unfurl_links: Type.Optional(
 					Type.Boolean({ description: "Slack unfurls link previews by default; pass false to suppress text-link previews for this message." }),
 				),
@@ -384,13 +398,14 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Update",
 			promptSnippet: "Edit an existing Slack message",
 			description:
-				'Edit a message via chat.update, as `as: "user"` or `as: "bot"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Only the identity that originally posted the message can edit it (Slack constraint; surfaced as an error otherwise). Accepts `text` and/or `blocks` (Block Kit JSON, unvalidated).',
+				'Edit a message via chat.update, as `as: "user"` or `as: "bot"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Only the identity that originally posted the message can edit it (Slack constraint; surfaced as an error otherwise). Accepts `text` and/or `blocks` (Block Kit JSON, unvalidated).' + "\n\n" + SLACK_FORMATTING_GUIDANCE.rules.join("\n") + "\n\n" + SLACK_FORMATTING_GUIDANCE.example,
+			promptGuidelines: SLACK_FORMATTING_GUIDANCE.rules,
 			parameters: Type.Object({
 				as: IDENTITY,
 				channel: Type.String({ description: "#name, channel ID, @name, or user ID (DM)" }),
 				ts: Type.String({ description: "Timestamp of the message to edit" }),
-				text: Type.Optional(Type.String()),
-				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON array, passed through unvalidated" })),
+				text: Type.Optional(Type.String({ description: "Readable message fallback with blocks, or text-only message body" })),
+				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON for the edited message body, passed through unvalidated" })),
 			}),
 			async execute(_toolCallId, params, signal) {
 				return guarded(async () => {

package/lib/slack-core.ts

@@ -800,7 +800,7 @@ export async function postPlain(
 	},
 	deps: CoreDeps,
 ): Promise<MutationResult> {
-	assertTextWithinLimit(args.text);
+	if (!(args.blocks && args.thread_ts !== undefined)) assertTextWithinLimit(args.text);
 
 	const params: Record<string, unknown> = { channel: args.channel };
 	if (args.text !== undefined) params.text = args.text;
@@ -947,13 +947,13 @@ export function formatUnresolvedSuffix(
 	return suffix;
 }
 
-export function persistDetail(body: string): string {
+export function persistDetail(body: string, format: "md" | "json" = "md"): string {
 	const dir = join(tmpdir(), "pi-slack");
 	mkdirSync(dir, { recursive: true });
 	const hash = createHash("sha256").update(body).digest("hex").slice(0, 8);
 	// Same-millisecond re-invocation with identical content hashes to the same filename and
 	// overwrites with byte-identical bytes - harmless, so no collision handling is needed here.
-	const path = join(dir, `${Date.now()}-${hash}-detail.md`);
+	const path = join(dir, `${Date.now()}-${hash}-detail.${format}`);
 	writeFileSync(path, body, "utf8");
 	return path;
 }
@@ -1007,7 +1007,7 @@ async function deliverDetailUploadOrPersist(
 	channel: string,
 	threadTs: string,
 	body: string,
-	deps: CoreDeps & { uploadBytes: UploadBytes; persist?: (body: string) => string },
+	deps: CoreDeps & { uploadBytes: UploadBytes; persist?: (body: string, format?: "md" | "json") => string },
 ): Promise<{ detailTs?: string }> {
 	try {
 		return await deliverDetailUpload(channel, threadTs, body, deps);
@@ -1028,14 +1028,22 @@ async function deliverDetailUploadOrPersist(
  * also failed and the (now unrecoverable) detail body's length, and omit detailPath from the
  * caller's structured error data.
  */
-function persistOrDescribe(body: string, persist: (body: string) => string): { detailPath?: string; note: string } {
+function persistOrDescribe(
+	body: string,
+	persist: (body: string, format?: "md" | "json") => string,
+	format: "md" | "json" = "md",
+	knownHeadline = true,
+): { detailPath?: string; note: string } {
 	try {
-		const detailPath = persist(body);
-		return { detailPath, note: `the full detail was saved to ${detailPath}` };
+		const detailPath = persist(body, format);
+		const recovery = format === "json"
+			? `${knownHeadline ? "; recover with saved text as thread_body and saved blocks using the known thread_ts" : "; locate the headline in the channel and obtain its ts before recovering with saved text as thread_body and saved blocks using that thread_ts"}; correct rejected blocks before recovery, preserving the original artifact`
+			: "";
+		return { detailPath, note: `the full detail was saved to ${detailPath}${format === "json" ? " (json)" : ""}${recovery}` };
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		return {
-			note: `persisting the ${body.length}-char detail body ALSO failed (${msg}) - the detail is unrecoverable`,
+			note: `persisting the ${body.length}-char detail ${format === "json" ? "payload" : "body"} ALSO failed (${msg}) - the detail is unrecoverable`,
 		};
 	}
 }
@@ -1055,9 +1063,10 @@ async function recoverFromDetailFailure(
 	ts: string,
 	permalink: string | undefined,
 	deps: CoreDeps,
-	persist: (body: string) => string,
+	persist: (body: string, format?: "md" | "json") => string,
+	format: "md" | "json" = "md",
 ): Promise<never> {
-	const { detailPath, note } = persistOrDescribe(detailBody, persist);
+	const { detailPath, note } = persistOrDescribe(detailBody, persist, format);
 
 	let markerFailureMessage: string | undefined;
 	try {
@@ -1085,17 +1094,19 @@ async function recoverFromDetailFailure(
 }
 
 export async function announce(
-	args: { channel: string; text: string; thread_body: string },
+	args: { channel: string; text: string; thread_body: string; blocks?: unknown[] },
 	deps: CoreDeps & {
 		uploadBytes: UploadBytes;
 		thresholdChars: number;
-		persist?: (body: string) => string;
+		persist?: (body: string, format?: "md" | "json") => string;
 		unfurl_links?: boolean;
 		unfurl_media?: boolean;
 	},
 ): Promise<AnnounceResult> {
 	assertHeadline(args.text);
 	const persist = deps.persist ?? persistDetail;
+	const detailFormat = args.blocks ? "json" : "md";
+	const detailBody = args.blocks ? JSON.stringify({ text: args.thread_body, blocks: args.blocks }) : args.thread_body;
 	const unfurl: Record<string, unknown> = {};
 	if (deps.unfurl_links !== undefined) unfurl.unfurl_links = deps.unfurl_links;
 	if (deps.unfurl_media !== undefined) unfurl.unfurl_media = deps.unfurl_media;
@@ -1105,7 +1116,7 @@ export async function announce(
 		headlineData = await deps.apiCall("chat.postMessage", deps.token, { channel: args.channel, text: args.text, ...unfurl }, { retry: false, signal: deps.signal });
 	} catch (err) {
 		if (err instanceof SlackError && err.code === "transport") {
-			const { detailPath, note } = persistOrDescribe(args.thread_body, persist);
+			const { detailPath, note } = persistOrDescribe(detailBody, persist, detailFormat, false);
 			throw new SlackError(
 				"outcome_unknown",
 				`Headline post to ${args.channel} may or may not have reached Slack (${err.message}); check the channel before re-invoking slack_post. ${capitalize(note)}.`,
@@ -1125,24 +1136,24 @@ export async function announce(
 	try {
 		ts = requireResponseString(headlineData, "chat.postMessage", "ts");
 	} catch (err) {
-		const { detailPath, note } = persistOrDescribe(args.thread_body, persist);
+		const { detailPath, note } = persistOrDescribe(detailBody, persist, detailFormat, false);
 		const detail = err instanceof Error ? err.message : String(err);
 		throw new SlackError(
 			"outcome_unknown",
-			`Headline post to ${channel} WAS accepted by Slack (ok:true) but the response was unparseable (${detail}); do NOT re-invoke slack_post - thread the detail manually. ${capitalize(note)}.`,
+			`Headline post to ${channel} WAS accepted by Slack (ok:true) but the response was unparseable (${detail}); ${args.blocks ? "do NOT repost the headline - recover only into its thread" : "do NOT re-invoke slack_post - thread the detail manually"}. ${capitalize(note)}.`,
 			{ channel, ...(detailPath ? { detailPath } : {}) },
 		);
 	}
 
 	const { permalink, warning } = await withPermalink(deps, channel, ts);
 
-	if (linkCollapsedLength(args.thread_body) > deps.thresholdChars) {
+	if (!args.blocks && linkCollapsedLength(args.thread_body) > deps.thresholdChars) {
 		let detailTs: string | undefined;
 		try {
 			({ detailTs } = await deliverDetailUpload(channel, ts, args.thread_body, deps));
 		} catch (err) {
 			const causeMessage = err instanceof Error ? err.message : String(err);
-			return recoverFromDetailFailure(causeMessage, args.text, args.thread_body, channel, ts, permalink, deps, persist);
+			return recoverFromDetailFailure(causeMessage, args.text, detailBody, channel, ts, permalink, deps, persist, detailFormat);
 		}
 		return { channel, ts, permalink, warning, detailTs, detailUploaded: true };
 	}
@@ -1152,21 +1163,21 @@ export async function announce(
 		detailData = await deps.apiCall(
 			"chat.postMessage",
 			deps.token,
-			{ channel, text: args.thread_body, thread_ts: ts, ...unfurl },
+			{ channel, text: args.thread_body, thread_ts: ts, ...(args.blocks ? { blocks: args.blocks } : {}), ...unfurl },
 			{ retry: true, signal: deps.signal },
 		);
 	} catch (err) {
-		if (err instanceof SlackError && err.code === "msg_too_long") {
+		if (!args.blocks && err instanceof SlackError && err.code === "msg_too_long") {
 			try {
 				const { detailTs } = await deliverDetailUpload(channel, ts, args.thread_body, deps);
 				return { channel, ts, permalink, warning, detailTs, detailUploaded: true };
 			} catch (uploadErr) {
 				const causeMessage = uploadErr instanceof Error ? uploadErr.message : String(uploadErr);
-				return recoverFromDetailFailure(causeMessage, args.text, args.thread_body, channel, ts, permalink, deps, persist);
+				return recoverFromDetailFailure(causeMessage, args.text, detailBody, channel, ts, permalink, deps, persist, detailFormat);
 			}
 		}
-		const causeMessage = err instanceof Error ? err.message : String(err);
-		return recoverFromDetailFailure(causeMessage, args.text, args.thread_body, channel, ts, permalink, deps, persist);
+		const causeMessage = args.blocks && err instanceof SlackError && !err.message.startsWith(`${err.code}:`) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
+		return recoverFromDetailFailure(causeMessage, args.text, detailBody, channel, ts, permalink, deps, persist, detailFormat);
 	}
 
 	const detailTs = requireResponseString(detailData, "chat.postMessage", "ts");
@@ -1183,11 +1194,11 @@ export async function postMessage(
 		unfurl_links?: boolean;
 		unfurl_media?: boolean;
 	},
-	deps: CoreDeps & { uploadBytes: UploadBytes; thresholdChars: number; persist?: (body: string) => string },
+	deps: CoreDeps & { uploadBytes: UploadBytes; thresholdChars: number; persist?: (body: string, format?: "md" | "json") => string },
 ): Promise<MutationResult | AnnounceResult> {
 	if (args.thread_body !== undefined && args.thread_ts === undefined) {
 		return announce(
-			{ channel: args.channel, text: args.text ?? "", thread_body: args.thread_body },
+			{ channel: args.channel, text: args.text ?? "", thread_body: args.thread_body, blocks: args.blocks },
 			{ ...deps, unfurl_links: args.unfurl_links, unfurl_media: args.unfurl_media },
 		);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "6.7.0",
+  "version": "6.8.0",
   "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, a themed ASCII startup header, Opus 4.8 fast mode, and a provider-stall watchdog.",
   "author": "Jacek Juraszek",
   "license": "MIT",