pi-quiver 5.0.0 → 5.2.0

package/CHANGELOG.md

@@ -8,6 +8,14 @@ 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.
 
+## v5.2.0 - 2026-09-01
+
+- session-name: sync the session name to the Herdr tab label (`herdrTab`, default true within the opt-in `quiver.sessionAutoName`). Claim-once - only a tab still on its default numeric label is adopted; manual renames always win. Restores the default label on shutdown; crash leaves the last label (rename by hand to recover).
+
+## v5.1.0 - 2026-09-01
+
+- `slack`: optional `policyPath` config injects a repo policy file into the system prompt every turn (`<slack-policy source="...">`); a missing/unreadable/empty file degrades to a `status=` block plus one deduped warning, tools stay fully usable either way (#9). `slack_post`/`slack_update` now resolve `@name` mentions to `<@U...>` (cache-first, one batched `users.list` live pass), leaving unresolvable names literal and reported via `unresolved mentions: ...` plus `details.unresolvedMentions`. The name cache gained an optional per-user `email` field and a file-level `snapshot_at` marker (set only by a full `slack_cache_refresh`, gating whether an alias match can be trusted straight from cache); `slack_cache_refresh`'s result line now reports an email/user ratio with a missing-scope hint. `slack_post` gained `unfurl_links`/`unfurl_media` params, applied to the headline and inline detail leg (never the upload stub), omitted when unset so Slack's default stands; `slack_update` has no equivalent (`chat.update` has no unfurl argument). See [doc/slack.md](doc/slack.md).
+
 ## v5.0.0 - 2026-08-29
 
 - **New opt-in `slack` extension** (#7): eight `slack_*` tools (search, thread, post, update, delete, pin, upload, cache refresh) for context-safe Slack search/threads/posting. Dual `user`/`bot` token identities resolved per call from process env or the repo's `.env`, never cross-identity fallback. Workspace-keyed channel/user name->ID cache with a repo-overridable `cachePath`. Fetch-style output size gating on search/thread reads. `slack_post`'s `thread_body` (no `thread_ts`) posts a transactional headline+thread announce - oversized detail bodies upload as a file - with a documented recovery path on delivery failure. OFF by default; nested-only `quiver.slack` config, no legacy flat form. See [doc/slack.md](doc/slack.md).

package/README.md

@@ -18,7 +18,7 @@ But the moment an agent does that, one `fetch` or PDF read can dump hundreds of
 
 `fetch` and `doc_to_md` bring real web pages, GitHub issues/PRs, and local PDF/DOCX/PPTX files into context - and every result is size-gated by construction: over 32 KB or 1000 lines spills to a temp file with a preview and a grep/read hint, so a single call can never flood the window. Ingestion is what makes data-driven work possible; the gate is what keeps it safe.
 
-`session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`, and `slack` are opt-in ergonomics, recovery, and integration controls: session labeling, a themed startup header, Anthropic fast mode, semantic-stall recovery, and context-safe Slack search/threads/posting.
+`session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`, and `slack` are opt-in ergonomics, recovery, and integration controls: session labeling, a themed startup header, Anthropic fast mode, semantic-stall recovery, and context-safe Slack search/threads/posting with repo-policy injection, `@name` mention resolution, cached emails, and per-call unfurl control.
 
 ## Part of the pi agent toolkit
 
@@ -64,7 +64,7 @@ A 300 KB changelog page never touches your context window - you get a preview an
 | --- | --- | --- |
 | `extensions/fetch.ts` | `fetch` | Retrieve URLs over HTTP(S). HTML -> Markdown (Readability extraction, Turndown conversion). Binary saved untouched to a temp file. GitHub issue/PR/repo/actions-run/actions-job URLs auto-route through `gh` (falls back to HTTP); failed runs/jobs include failed-step logs (best-effort, summary-only otherwise). Same size gate as `doc_to_md`. Behavior lives in `lib/fetch-core.ts`; also exposed as the `pi-quiver fetch` CLI (see [Claude Code support](#claude-code-support)). |
 | `extensions/doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX to Markdown. High-fidelity via `pymupdf4llm`, resolved per process (`uv` -> system Python >= 3.12 with the package -> one-time managed venv in the user cache dir); degraded pure-JS fallback (`unpdf`) otherwise. DOCX/PPTX convert via LibreOffice first. Behavior lives in `lib/doc-to-md-core.ts`; also exposed as the `pi-quiver doc-to-md` CLI (see [Claude Code support](#claude-code-support)). |
-| `extensions/session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, naming rules and deny list, long-session revisits, and Ghostty tab rename. OFF by default. |
+| `extensions/session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, naming rules and deny list, long-session revisits, and Ghostty/Herdr tab rename. OFF by default. |
 | `extensions/sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
 | `extensions/fast-mode.ts` | `/fast` | Inject Anthropic fast-mode (`speed: "fast"` + `anthropic-beta: fast-mode-2026-02-01`) into every Claude Opus 4.8 / Opus 5 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
 | `extensions/provider-stall-watchdog.ts` | - | Opt-in provider-stall recovery, in two tiers: a pre-first-event deadline (`firstEventMs`, 20s) on every provider request in every mode, and the mid-stream pair (warn at 2 min, recover at 4 min) in TUI runs only. Policy D offers each stall to Pi's retry loop until the stall retry budget (`maxStallRetries`, default = `retry.maxRetries`) is exhausted. OFF by default. |
@@ -146,6 +146,7 @@ These extensions are opt-in via `settings.json` (project `.pi/settings.json` ove
     "sessionAutoName": {
       "enabled": false,
       "ghosttyTab": true,
+      "herdrTab": true,
       "rules": [],
       "deny": [],
       "revisitFirstTurn": 0,
@@ -181,6 +182,8 @@ 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.
 
+`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. It's claim-once: the extension adopts a tab only while it still shows its default numeric label (its live 1-based position among the workspace's tabs); a manually renamed tab, or one renamed mid-session by hand, is never touched again for that session - the human's label always wins. On every shutdown (quit, reload, `/new`, resume, fork) a claimed tab's label is restored to its then-current default position, so a successor session in the same pane can claim cleanly. 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. Caveats: a hard crash (`kill -9`) skips the restore and leaves the stale label - rename the tab by hand to recover; and the restored label 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.
+
 `fastMode` only affects `claude-opus-4-8` and `claude-opus-5` requests on Anthropic's `anthropic-messages` API; enabling it opts into premium fast-mode pricing. `--fast` forces it on for one launch; `/fast on|off` toggles live. Proxy providers (opencode, cloudflare-ai-gateway) are excluded. `fastMode`'s header injection needs the `before_provider_headers` hook (pi bundling `@earendil-works/pi-coding-agent` >= 0.80.5); on older pi the beta header is silently not sent. See [doc/fetch.md](doc/fetch.md) and [doc/doc-to-md.md](doc/doc-to-md.md) for the ingestion tools' full reference; session-name/sword-header behavior above is complete.
 
 `pi-ai` prices every fast request at standard rates - it has no `usage.speed` support and no request-level pricing modifier - so `fastMode` corrects the reported cost itself: a `message_end` handler scales all four `usage.cost` components by `FAST_MODE_COST_MULTIPLIER` (2x) and returns the corrected message. Persisted session JSONL and pi's own native cost display are always exact, since they're written from this corrected message. pi-cohort's live `Σ$` reflects the correction only when pi-quiver's `message_end` handler runs before pi-cohort's - best-effort, depending on extension load order - and is reconciled on pi-cohort's next `session_start` regardless. The upstream fix (teaching `pi-ai`'s `Usage`/`calculateCost` about `usage.speed`) is the better long-term path and is tracked separately.

package/extensions/session-name.ts

@@ -36,6 +36,12 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resolveConfig } from "../lib/extension-config.ts";
 
+// ExtensionMode ("tui" | "rpc" | "json" | "print") isn't among the package's
+// public exports; derive it from ExtensionContext, which is, instead of
+// duplicating the union here.
+type Mode = ExtensionContext["mode"];
+import { getTab, isHerdrActive, listTabs, renameTab } from "../lib/herdr-tab.ts";
+
 // `complete` moved between pi-ai layouts: older builds re-export it from the
 // package index, newer ones expose it only via the `/compat` subpath. A static
 // import that targets one breaks at load time on the other (and a missing
@@ -52,6 +58,7 @@ async function loadComplete(): Promise<CompleteFn> {
 type Config = {
 	enabled: boolean;
 	ghosttyTab: boolean;
+	herdrTab: boolean;
 	rules: string[];
 	deny: string[];
 	revisitFirstTurn: number;
@@ -60,6 +67,7 @@ type Config = {
 const DEFAULT_CONFIG: Config = {
 	enabled: false,
 	ghosttyTab: true,
+	herdrTab: true,
 	rules: [],
 	deny: [],
 	revisitFirstTurn: 0,
@@ -76,12 +84,13 @@ const turnCount = (v: unknown): number | undefined =>
 
 export function coerce(raw: unknown): Partial<Config> | undefined {
 	if (raw === undefined) return undefined;
-	if (typeof raw === "boolean") return { enabled: raw, ghosttyTab: raw };
+	if (typeof raw === "boolean") return { enabled: raw, ghosttyTab: raw, herdrTab: raw };
 	if (raw && typeof raw === "object") {
 		const o = raw as Record<string, unknown>;
 		const out: Partial<Config> = {};
 		if (typeof o.enabled === "boolean") out.enabled = o.enabled;
 		if (typeof o.ghosttyTab === "boolean") out.ghosttyTab = o.ghosttyTab;
+		if (typeof o.herdrTab === "boolean") out.herdrTab = o.herdrTab;
 		const rules = stringList(o.rules);
 		if (rules) out.rules = rules;
 		const deny = stringList(o.deny);
@@ -425,6 +434,8 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 	// per-turn re-assert wins the race and keeps the tab in sync with the name.
 	let lastSyncedName: string | null = null;
 	let currentTabLabel: string | null = null;
+	let herdrClaim: { lastWritten: string } | "backed-off" | null = null;
+	let herdrChain: Promise<void> = Promise.resolve();
 
 	// Adopt a name we set ourselves, keeping any curated tab label (auto-naming
 	// produces a separate TAB line that need not match the first words of the
@@ -451,12 +462,13 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		return "human";
 	};
 
-	const setName = (
+	const setName = async (
 		cfg: Config,
 		name: string,
 		tabLabel?: string,
 		author?: NameAuthor,
-	): void => {
+		mode?: Mode,
+	): Promise<void> => {
 		const clean = applyDenyList(name, cfg.deny);
 		if (author) recordNameAuthor(clean, author);
 		expectedInternalName = clean;
@@ -464,13 +476,17 @@ 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);
 	};
 
 	// Re-assert the tab from the current session name. Self-heals when the name
 	// changed outside setName (builtin/manual rename we didn't author): the
-	// curated label no longer applies, so re-derive from the name.
+	// curated label no longer applies, so re-derive from the name. The Ghostty
+	// write is already internally gated by renameGhosttyTab's own cfg.ghosttyTab
+	// check, which lets turn_start re-derive currentTabLabel for the Herdr sink
+	// even with the Ghostty sink off.
 	const syncTab = (cfg: Config): void => {
-		if (!cfg.enabled || !cfg.ghosttyTab) return;
+		if (!cfg.enabled) return;
 		const name = pi.getSessionName();
 		if (!name) return;
 		if (name !== lastSyncedName) {
@@ -480,13 +496,83 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		if (currentTabLabel) renameGhosttyTab(currentTabLabel, cfg.ghosttyTab);
 	};
 
+	// Herdr sink. Claim-once: adopt the tab only while it shows its default
+	// (position) label; a human rename - before or during the session - wins
+	// permanently. All syncs serialize on one chain so overlapping hooks never
+	// interleave a read with a rename.
+	// Used both for turn_start syncs (bounds a wedged-but-accepting Herdr so it
+	// can't stall the turn) and for the session_end restore.
+	const HERDR_TIMEOUT_MS = 500;
+
+	const positionOf = (tabs: { tab_id: string; workspace_id: string }[], tabId: string): number => {
+		const own = tabs.find((t) => t.tab_id === tabId);
+		if (!own) return -1;
+		const siblings = tabs.filter((t) => t.workspace_id === own.workspace_id);
+		return siblings.findIndex((t) => t.tab_id === tabId) + 1;
+	};
+
+	const syncHerdrTab = (cfg: Config, label: string | null, mode: Mode | undefined): Promise<void> => {
+		const run = async (): Promise<void> => {
+			if (!cfg.herdrTab || mode !== "tui" || !label) return;
+			if (herdrClaim === "backed-off") return;
+			if (!isHerdrActive()) return;
+			const sock = process.env.HERDR_SOCKET_PATH as string;
+			const tabId = process.env.HERDR_TAB_ID as string;
+			if (herdrClaim === null) {
+				const tabs = await listTabs(sock, HERDR_TIMEOUT_MS);
+				if (!tabs) return; // transient; retry next sync
+				const position = positionOf(tabs, tabId);
+				if (position === -1) return; // stale tab id (pane moved); retry harmlessly
+				const own = tabs.find((t) => t.tab_id === tabId)!;
+				if (own.label !== String(position)) {
+					herdrClaim = "backed-off"; // human (or crashed predecessor) owns it
+					return;
+				}
+				if (await renameTab(sock, tabId, label, HERDR_TIMEOUT_MS)) {
+					herdrClaim = { lastWritten: label };
+				}
+				return;
+			}
+			const live = await getTab(sock, tabId, HERDR_TIMEOUT_MS);
+			if (!live) return; // failed read is not a human rename; stay claimed
+			if (live.label !== herdrClaim.lastWritten) {
+				herdrClaim = "backed-off";
+				return;
+			}
+			if (label === herdrClaim.lastWritten) return;
+			if (await renameTab(sock, tabId, label, HERDR_TIMEOUT_MS)) herdrClaim.lastWritten = label;
+		};
+		herdrChain = herdrChain.then(run, run);
+		return herdrChain;
+	};
+
+	// No mode gate needed here: herdrClaim can only become an object via
+	// syncHerdrTab, which itself gates on mode === "tui".
+	const restoreHerdrTab = (): Promise<void> => {
+		const run = async (): Promise<void> => {
+			if (typeof herdrClaim !== "object" || herdrClaim === null) 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 (!live || live.label !== herdrClaim.lastWritten) return; // human's label wins
+			const tabs = await listTabs(sock, HERDR_TIMEOUT_MS);
+			if (!tabs) return;
+			const position = positionOf(tabs, tabId);
+			if (position === -1) return;
+			await renameTab(sock, tabId, String(position), HERDR_TIMEOUT_MS);
+		};
+		herdrChain = herdrChain.then(run, run);
+		return herdrChain;
+	};
+
 	pi.registerCommand("session-name", {
 		description: "Set or show session name (usage: /session-name [new name])",
 		handler: async (args, ctx) => {
 			const name = args.trim();
 			if (name) {
 				autoNameTried = true; // manual name wins; don't auto-overwrite later
-				setName(loadConfig(ctx), name, undefined, "human");
+				await setName(loadConfig(ctx), name, undefined, "human", ctx.mode);
 				ctx.ui.notify(`Session named: ${pi.getSessionName()}`, "info");
 			} else {
 				const current = pi.getSessionName();
@@ -504,7 +590,7 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 			// The curated tab label is not persisted, so derive from the name.
 			autoNameTried = true;
 			nameAuthor = restoredNameAuthor(ctx, current);
-			setName(cfg, current);
+			await setName(cfg, current, undefined, undefined, ctx.mode);
 		} else {
 			// Fresh session: clear carryover so a new name re-derives cleanly and
 			// auto-naming can run again.
@@ -534,14 +620,24 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		recordNameAuthor(current, "human");
 		if (cfg.deny.length === 0) return;
 		const clean = applyDenyList(current, cfg.deny);
-		if (clean !== current) setName(cfg, clean, undefined, "human");
+		if (clean !== current) await setName(cfg, clean, undefined, "human", ctx.mode);
 	});
 
 	// Re-assert at the start of every turn. This is the only signal we get that
 	// fires after pi's own OS-title writer on session replacement, so it keeps
 	// the tab pinned to the session name and picks up external renames.
 	pi.on("turn_start", async (_event, ctx) => {
-		syncTab(loadConfig(ctx));
+		const cfg = loadConfig(ctx);
+		syncTab(cfg);
+		if (cfg.enabled) await syncHerdrTab(cfg, currentTabLabel, ctx.mode);
+	});
+
+	// Restore the numeric label on every teardown reason (quit/reload/new/
+	// resume/fork): a successor session in this pane must find the default so
+	// claim-once stays sound. The restored label is internally a custom name -
+	// Herdr has no clear-to-auto API - so it looks right but won't renumber.
+	pi.on("session_shutdown", async () => {
+		await restoreHerdrTab();
 	});
 
 	pi.on("agent_end", async (_event, ctx) => {
@@ -552,7 +648,7 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 		try {
 			const generated = await generate(ctx, { rules: cfg.rules });
 			if (generated && generated !== KEEP && !pi.getSessionName()) {
-				setName(cfg, generated.sessionName, generated.tabLabel, "auto");
+				await setName(cfg, generated.sessionName, generated.tabLabel, "auto", ctx.mode);
 				if (ctx.hasUI) ctx.ui.notify(`Auto-named session: ${pi.getSessionName()}`, "info");
 			}
 		} catch {
@@ -588,7 +684,7 @@ export function installSessionName(pi: ExtensionAPI, generate: NameGenerator = g
 				if (!result || result === KEEP) return;
 				if (pi.getSessionName() !== current) return; // renamed under us mid-call
 				if (nameAuthor === "auto") {
-					setName(cfg, result.sessionName, result.tabLabel, "auto");
+					await setName(cfg, result.sessionName, result.tabLabel, "auto", ctx.mode);
 					if (ctx.hasUI) ctx.ui.notify(`Renamed session: ${pi.getSessionName()}`, "info");
 				} else if (ctx.hasUI) {
 					// Human wording is theirs to change; surface the drift and stop.

package/extensions/slack.ts

@@ -16,6 +16,7 @@ import { basename, isAbsolute, join } from "node:path";
 import {
 	defaultApiCall,
 	defaultUploadBytes,
+	buildPolicyBlock,
 	discoverRepoRoot,
 	resolveSlackConfig,
 	resolveToken,
@@ -26,6 +27,7 @@ import {
 	deleteMessage,
 	pinMessage,
 	uploadFile,
+	formatUnresolvedSuffix,
 	SlackError,
 	type SlackConfig,
 	type CoreDeps,
@@ -33,8 +35,9 @@ import {
 	type AnnounceResult,
 	type SearchResult,
 	type ThreadResult,
+	type UnresolvedMention,
 } from "../lib/slack-core.ts";
-import { cacheFilePath, teamIdFor, resolveChannel, refreshCache, assertSameTeam, type CacheCtx } from "../lib/slack-cache.ts";
+import { cacheFilePath, teamIdFor, resolveChannel, refreshCache, resolveMentions, assertSameTeam, type CacheCtx } from "../lib/slack-cache.ts";
 
 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 token env var is used and whose name shows as the author.',
@@ -139,6 +142,19 @@ export function channelLine(result: MutationResult | (MutationResult & { fileId:
 	return parts.join(" | ");
 }
 
+/** Shared by slack_post/slack_update: the channelLine + unresolved-mentions suffix result shape. */
+function mentionAwareResult(
+	result: MutationResult | AnnounceResult,
+	mentions: { unresolved: UnresolvedMention[]; lookupError?: string },
+	opts: { detailUploaded?: boolean } = {},
+) {
+	const suffix = formatUnresolvedSuffix(mentions.unresolved, { lookupError: mentions.lookupError, ...opts });
+	return {
+		content: [{ type: "text" as const, text: suffix ? `${channelLine(result)} | ${suffix}` : channelLine(result) }],
+		details: { ...result, ...(mentions.unresolved.length > 0 ? { unresolvedMentions: mentions.unresolved } : {}) },
+	};
+}
+
 export function searchResultText(result: SearchResult): string {
 	return `${result.output}\n\ntotal: ${result.total} | page: ${result.page} of ${result.pageCount}`;
 }
@@ -191,6 +207,36 @@ export default function slackExtension(pi: ExtensionAPI) {
 
 		const repoRoot = discoverRepoRoot(ctx.cwd);
 
+		const policyPath = cfg.policyPath;
+		if (policyPath !== undefined) {
+			const resolvedPolicyPath = isAbsolute(policyPath) ? policyPath : join(repoRoot, policyPath);
+			let policyWarned = false;
+			const warnOnce = (eventCtx: typeof ctx, message: string): void => {
+				if (policyWarned) return;
+				policyWarned = true;
+				if (eventCtx.hasUI) eventCtx.ui.notify(message, "warning");
+				else console.warn(message);
+			};
+
+			pi.on("before_agent_start", async (event, eventCtx) => {
+				let block: string;
+				try {
+					const body = readFileSync(resolvedPolicyPath, "utf8");
+					if (body.trim() === "") {
+						warnOnce(eventCtx, `pi-quiver: Slack policy file ${policyPath} is empty; posting policy is unknown this session.`);
+						block = buildPolicyBlock({ source: policyPath, status: "empty" });
+					} else {
+						block = buildPolicyBlock({ source: policyPath, status: "ok", body });
+					}
+				} catch (err) {
+					const code = (err as { code?: string }).code ?? (err instanceof Error ? err.message : String(err));
+					warnOnce(eventCtx, `pi-quiver: Slack policy file ${policyPath} could not be read (${code}); posting policy is unknown this session.`);
+					block = buildPolicyBlock({ source: policyPath, status: "unreadable", code });
+				}
+				return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+			});
+		}
+
 		pi.registerTool({
 			name: "slack_search",
 			label: "Slack Search",
@@ -248,7 +294,7 @@ 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 or a channel ID (user @names not accepted). 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.",
+				"Post a Slack message via chat.postMessage, as `as: \"user\"` or `as: \"bot\"`. `channel` accepts #name or a channel ID (user @names not accepted). 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.",
 			parameters: Type.Object({
 				as: IDENTITY,
 				channel: Type.String({ description: "#name or channel ID (user @names not accepted)" }),
@@ -256,20 +302,69 @@ export default function slackExtension(pi: ExtensionAPI) {
 				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON array, 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" })),
+				unfurl_links: Type.Optional(
+					Type.Boolean({ description: "Slack unfurls link previews by default; pass false to suppress text-link previews for this message." }),
+				),
+				unfurl_media: Type.Optional(
+					Type.Boolean({ description: "Pass false to suppress image/video previews for this message." }),
+				),
 			}),
 			async execute(_toolCallId, params, signal) {
 				return guarded(async () => {
 					assertNoMarkdownText(params);
 					const { deps, cacheCtx } = await resolveCall(params.as, cfg, ctx, signal, repoRoot);
 					const channel = await resolveChannel(params.channel, cacheCtx);
+
+					// Only the fields core will actually send: announce uses text + thread_body (both
+					// scanned), a threaded reply collapses to thread_body ?? text (whichever param carried
+					// the body is the one core reads, so substitute into that same field - never the
+					// other), a plain post is text alone.
+					const isAnnounce = params.thread_body !== undefined && params.thread_ts === undefined;
+					const isReply = params.thread_ts !== undefined;
+					let text: string | undefined;
+					let threadBody: string | undefined;
+					let mentions: { unresolved: UnresolvedMention[]; lookupError?: string };
+					if (isAnnounce) {
+						const resolved = await resolveMentions(
+							[
+								{ field: "text", value: params.text ?? "" },
+								{ field: "thread_body", value: params.thread_body ?? "" },
+							],
+							cacheCtx,
+						);
+						mentions = resolved;
+						text = resolved.values[0];
+						threadBody = resolved.values[1];
+					} else if (isReply) {
+						const replyField: "text" | "thread_body" = params.thread_body !== undefined ? "thread_body" : "text";
+						const resolved = await resolveMentions([{ field: replyField, value: params.thread_body ?? params.text ?? "" }], cacheCtx);
+						mentions = resolved;
+						if (replyField === "thread_body") {
+							text = params.text;
+							threadBody = resolved.values[0];
+						} else {
+							text = params.text === undefined ? undefined : resolved.values[0];
+							threadBody = undefined;
+						}
+					} else {
+						const resolved = await resolveMentions([{ field: "text", value: params.text ?? "" }], cacheCtx);
+						mentions = resolved;
+						text = params.text === undefined ? undefined : resolved.values[0];
+					}
+
 					const result = await postMessage(
-						{ channel, text: params.text, blocks: params.blocks, thread_ts: params.thread_ts, thread_body: params.thread_body },
+						{
+							channel,
+							text,
+							blocks: params.blocks,
+							thread_ts: params.thread_ts,
+							thread_body: threadBody,
+							unfurl_links: params.unfurl_links,
+							unfurl_media: params.unfurl_media,
+						},
 						{ ...deps, thresholdChars: cfg.uploadThresholdChars, uploadBytes: defaultUploadBytes },
 					);
-					return {
-						content: [{ type: "text" as const, text: channelLine(result) }],
-						details: result,
-					};
+					return mentionAwareResult(result, mentions, { detailUploaded: "detailUploaded" in result && result.detailUploaded === true });
 				}, params.as);
 			},
 			renderCall: (args, theme) => oneLine(theme, "slack_post", `as:${args.as} ${args.channel}`),
@@ -294,11 +389,12 @@ export default function slackExtension(pi: ExtensionAPI) {
 					assertNoMarkdownText(params);
 					const { deps, cacheCtx } = await resolveCall(params.as, cfg, ctx, signal, repoRoot);
 					const channel = await resolveChannel(params.channel, cacheCtx);
-					const result = await updateMessage({ channel, ts: params.ts, text: params.text, blocks: params.blocks }, deps);
-					return {
-						content: [{ type: "text" as const, text: channelLine(result) }],
-						details: result,
-					};
+					const mentions = await resolveMentions([{ field: "text", value: params.text ?? "" }], cacheCtx);
+					const result = await updateMessage(
+						{ channel, ts: params.ts, text: params.text === undefined ? undefined : mentions.values[0], blocks: params.blocks },
+						deps,
+					);
+					return mentionAwareResult(result, mentions);
 				}, params.as);
 			},
 			renderCall: (args, theme) => oneLine(theme, "slack_update", `as:${args.as} ${args.channel} ts:${args.ts}`),
@@ -410,15 +506,21 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Cache Refresh",
 			promptSnippet: "Rebuild the Slack channel/user name->ID cache",
 			description:
-				'Rebuild the Slack channel and user name->ID cache from scratch (full conversations.list + users.list scan, atomic replace). Uses the "user" identity when a user token is configured, else falls back to "bot" (no `as` param). Run this after channels/users change or when a #name/@name lookup unexpectedly fails with name_not_found. Reports the resulting channel and user counts.',
+				'Rebuild the Slack channel and user name->ID cache from scratch (full conversations.list + users.list scan, atomic replace). Uses the "user" identity when a user token is configured, else falls back to "bot" (no `as` param). Run this after channels/users change or when a #name/@name lookup unexpectedly fails with name_not_found. Reports the resulting channel, user, and email counts - a low email/user ratio hints the users:read.email scope may be missing.',
 			parameters: Type.Object({}),
 			async execute(_toolCallId, _params, signal) {
 				const identity = pickCacheRefreshIdentity(cfg, process.env, repoRoot);
 				return guarded(async () => {
 					const { cacheCtx } = await resolveCall(identity, cfg, ctx, signal, repoRoot);
 					const result = await refreshCache(cacheCtx);
+					const ratio =
+						result.users === 0
+							? ""
+							: result.emails === 0
+								? ` | emails: 0/${result.users} (users:read.email scope may be missing)`
+								: ` | emails: ${result.emails}/${result.users}`;
 					return {
-						content: [{ type: "text" as const, text: `channels: ${result.channels}, users: ${result.users}` }],
+						content: [{ type: "text" as const, text: `channels: ${result.channels}, users: ${result.users}${ratio}` }],
 						details: result,
 					};
 				}, identity);

package/lib/herdr-tab.ts

@@ -0,0 +1,93 @@
+// Pi-free Herdr socket client for the session-name extension's tab sink.
+// One-shot newline-delimited JSON RPC against Herdr's unix socket (protocol
+// 20, herdr 0.8.2). Every failure mode resolves null: a dead, wedged, or
+// absent Herdr must never break a session or stall shutdown.
+// Responses are trusted structurally: result.tab/result.tabs shapes are not
+// validated beyond presence, and the consumer treats their fields as
+// Herdr-provided truth.
+import net from "node:net";
+
+export interface HerdrTab {
+	tab_id: string;
+	workspace_id: string;
+	label: string;
+	number: number;
+}
+
+export function isHerdrActive(
+	env: Record<string, string | undefined> = process.env,
+	isTTY: boolean = process.stdout.isTTY === true,
+): boolean {
+	return env.HERDR_ENV === "1" && !!env.HERDR_TAB_ID && !!env.HERDR_SOCKET_PATH && isTTY;
+}
+
+let nextRequestId = 1;
+
+export function herdrRequest(
+	socketPath: string,
+	method: string,
+	params: Record<string, unknown>,
+	timeoutMs = 1500,
+): Promise<Record<string, unknown> | null> {
+	return new Promise((resolve) => {
+		const path = process.platform === "win32" ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+		let settled = false;
+		const timer = setTimeout(() => done(null), timeoutMs);
+		const socket = net.createConnection({ path });
+		const done = (value: Record<string, unknown> | null) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			resolve(value);
+		};
+		socket.on("error", () => done(null));
+		socket.on("close", () => done(null));
+		socket.on("connect", () => {
+			socket.write(`${JSON.stringify({ id: String(nextRequestId++), method, params })}\n`);
+		});
+		let buffer = "";
+		socket.on("data", (chunk) => {
+			buffer += chunk.toString("utf8");
+			const newline = buffer.indexOf("\n");
+			if (newline === -1) return;
+			try {
+				const message = JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>;
+				const result = message.result;
+				if (!("error" in message) && result && typeof result === "object") {
+					done(result as Record<string, unknown>);
+				} else {
+					done(null);
+				}
+			} catch {
+				done(null);
+			}
+		});
+	});
+}
+
+export async function getTab(
+	socketPath: string,
+	tabId: string,
+	timeoutMs = 1500,
+): Promise<HerdrTab | null> {
+	const result = await herdrRequest(socketPath, "tab.get", { tab_id: tabId }, timeoutMs);
+	const tab = result?.tab;
+	return tab && typeof tab === "object" ? (tab as unknown as HerdrTab) : null;
+}
+
+export async function listTabs(socketPath: string, timeoutMs = 1500): Promise<HerdrTab[] | null> {
+	const result = await herdrRequest(socketPath, "tab.list", {}, timeoutMs);
+	const tabs = result?.tabs;
+	return Array.isArray(tabs) ? (tabs as unknown as HerdrTab[]) : null;
+}
+
+export async function renameTab(
+	socketPath: string,
+	tabId: string,
+	label: string,
+	timeoutMs = 1500,
+): Promise<true | null> {
+	const result = await herdrRequest(socketPath, "tab.rename", { tab_id: tabId, label }, timeoutMs);
+	return result ? true : null;
+}

package/lib/slack-cache.ts

@@ -7,14 +7,24 @@
 
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
-import type { ApiCall, SlackConfig } from "./slack-core.ts";
+import type { ApiCall, SlackConfig, UnresolvedMention } from "./slack-core.ts";
 import { SlackError } from "./slack-core.ts";
 
+export interface UserEntry {
+	id: string;
+	display_name: string;
+	real_name: string;
+	email?: string;
+}
+
 export interface SlackCacheFile {
 	team_id: string;
 	channels: Record<string, string>;
-	users: Record<string, { id: string; display_name: string; real_name: string }>;
+	users: Record<string, UserEntry>;
 	refreshed_at: string;
+	/** Set only by refreshCache's full replacement; presence means this file once held a complete
+	 * workspace listing, which is the only state where an alias match may be trusted from cache. */
+	snapshot_at?: string;
 }
 
 export interface CacheCtx {
@@ -99,6 +109,16 @@ function stripPrefix(input: string): string {
 	return input.startsWith("#") || input.startsWith("@") ? input.slice(1) : input;
 }
 
+function toUserEntry(u: SlackUser): UserEntry {
+	const email = u.profile?.email;
+	return {
+		id: u.id,
+		display_name: u.profile?.display_name ?? "",
+		real_name: u.profile?.real_name ?? u.real_name ?? "",
+		...(email ? { email } : {}),
+	};
+}
+
 export async function resolveChannel(input: string, ctx: CacheCtx): Promise<string> {
 	if (RAW_CHANNEL_ID.test(input)) return input;
 	if (input.startsWith("@")) {
@@ -150,7 +170,7 @@ export async function resolveChannel(input: string, ctx: CacheCtx): Promise<stri
 interface SlackUser {
 	id: string;
 	name: string;
-	profile?: { display_name?: string; real_name?: string };
+	profile?: { display_name?: string; real_name?: string; email?: string };
 	real_name?: string;
 }
 
@@ -208,11 +228,7 @@ export async function resolveUser(input: string, ctx: CacheCtx): Promise<string>
 		for (const u of members) {
 			if (u.name === name) {
 				mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
-					base.users[name] = {
-						id: u.id,
-						display_name: u.profile?.display_name ?? "",
-						real_name: u.profile?.real_name ?? u.real_name ?? "",
-					};
+					base.users[name] = toUserEntry(u);
 				});
 				return u.id;
 			}
@@ -231,11 +247,7 @@ export async function resolveUser(input: string, ctx: CacheCtx): Promise<string>
 	if (displayCandidates.length === 1) {
 		const u = displayCandidates[0];
 		mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
-			base.users[u.name] = {
-				id: u.id,
-				display_name: u.profile?.display_name ?? "",
-				real_name: u.profile?.real_name ?? u.real_name ?? "",
-			};
+			base.users[u.name] = toUserEntry(u);
 		});
 		return u.id;
 	}
@@ -249,11 +261,7 @@ export async function resolveUser(input: string, ctx: CacheCtx): Promise<string>
 	if (realCandidates.length === 1) {
 		const u = realCandidates[0];
 		mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
-			base.users[u.name] = {
-				id: u.id,
-				display_name: u.profile?.display_name ?? "",
-				real_name: u.profile?.real_name ?? u.real_name ?? "",
-			};
+			base.users[u.name] = toUserEntry(u);
 		});
 		return u.id;
 	}
@@ -267,16 +275,202 @@ export async function resolveUser(input: string, ctx: CacheCtx): Promise<string>
 	throw new SlackError("name_not_found", `No user named "${name}" was found in the workspace.`);
 }
 
+const MENTION_DENY = new Set(["here", "channel", "everyone"]);
+const MENTION_BOUNDARY = new Set([" ", "\t", "\n", "\r", "(", "[", "*", "_", '"', "'"]);
+// `_` is trimmed here even though it is also a boundary character: it is a legal username
+// character too, so an italic-wrapped mention like `_@alice_` is otherwise unreachable - the
+// trailing `_` must be stripped for the candidate to resolve.
+const MENTION_TRAILING = /[.,;:!?)_]+$/;
+const MENTION_SCAN = /(\\?)@([A-Za-z0-9._-]+)/g;
+
+function isBoundary(text: string, atIndex: number): boolean {
+	if (atIndex === 0) return true;
+	return MENTION_BOUNDARY.has(text[atIndex - 1]);
+}
+
+/**
+ * Substitutes `@name` -> `<@U...>` across every field a mutation will actually send.
+ * Never throws for an unresolvable name: not-found, ambiguous, and a failed live lookup all
+ * leave the text literal and report it, because a mention is prose, not an addressed parameter.
+ */
+export async function resolveMentions(
+	fields: { field: "text" | "thread_body"; value: string }[],
+	ctx: CacheCtx,
+): Promise<{
+	values: string[];
+	unresolved: UnresolvedMention[];
+	lookupError?: string;
+}> {
+	interface Candidate {
+		field: "text" | "thread_body";
+		start: number;
+		end: number;
+		escaped: boolean;
+		/** [name, endOffsetForThatName] pairs, trimmed variant first so it wins the lookup race. */
+		lookups: [string, number][];
+	}
+
+	const perField: Candidate[][] = fields.map(() => []);
+	const wanted = new Set<string>();
+
+	fields.forEach((f, fi) => {
+		for (const m of f.value.matchAll(MENTION_SCAN)) {
+			const escaped = m[1] === "\\";
+			const at = m.index + m[1].length;
+			if (escaped) {
+				if (!isBoundary(f.value, m.index)) continue;
+			} else if (!isBoundary(f.value, at)) continue;
+
+			const raw = m[2];
+			const fullEnd = m.index + m[0].length;
+			const trimmed = raw.replace(MENTION_TRAILING, "");
+			// Check the deny list against both forms: `_@channel_`/`@here.` still carry the
+			// trailing punctuation stripped below, so a raw-only check misses them.
+			if (MENTION_DENY.has(raw) || MENTION_DENY.has(trimmed)) continue;
+			// A name that is entirely trailing-punctuation (e.g. `@...`) trims to "" - not a
+			// real candidate, so skip it rather than looking up an empty username.
+			if (trimmed === "") continue;
+			const trimmedEnd = fullEnd - (raw.length - trimmed.length);
+			const lookups: [string, number][] =
+				trimmed === raw ? [[raw, fullEnd]] : [[trimmed, trimmedEnd], [raw, fullEnd]];
+			perField[fi].push({ field: f.field, start: m.index, end: fullEnd, escaped, lookups });
+			if (!escaped) for (const [name] of lookups) wanted.add(name);
+		}
+	});
+
+	const cached = readCacheFile(ctx.filePath);
+	const resolved = new Map<string, string>();
+	const aliasTrusted = cached?.snapshot_at !== undefined;
+	// Names an aliasTrusted FULL snapshot already proved ambiguous: a live users.list call
+	// cannot un-ambiguate them, so they must not fall into `outstanding`.
+	const conclusivelyAmbiguous = new Set<string>();
+
+	if (cached) {
+		for (const name of wanted) {
+			const byUsername = cached.users[name];
+			if (byUsername) {
+				resolved.set(name, byUsername.id);
+				continue;
+			}
+			if (!aliasTrusted) continue;
+			const entries = Object.values(cached.users);
+			const display = entries.filter((u) => u.display_name === name);
+			if (display.length === 1) {
+				resolved.set(name, display[0].id);
+				continue;
+			}
+			if (display.length > 1) {
+				conclusivelyAmbiguous.add(name);
+				continue;
+			}
+			const real = entries.filter((u) => u.real_name === name);
+			if (real.length === 1) resolved.set(name, real[0].id);
+			else if (real.length > 1) conclusivelyAmbiguous.add(name);
+		}
+	}
+
+	const outstanding = [...wanted].filter((n) => !resolved.has(n) && !conclusivelyAmbiguous.has(n));
+	let lookupError: string | undefined;
+
+	if (outstanding.length > 0) {
+		try {
+			const found = new Map<string, SlackUser>();
+			const aliasHits = new Map<string, SlackUser[]>();
+			let cursor = "";
+			for (let page = 1; ; page++) {
+				if (page > MAX_LIST_PAGES) {
+					throw new SlackError(
+						"pagination_overflow",
+						`resolveMentions: users.list did not terminate within ${MAX_LIST_PAGES} pages.`,
+					);
+				}
+				const data = await ctx.apiCall(
+					"users.list",
+					ctx.token,
+					{ limit: 1000, ...(cursor ? { cursor } : {}) },
+					{ retry: false, signal: ctx.signal },
+				);
+				for (const u of (data.members as SlackUser[]) ?? []) {
+					for (const name of outstanding) {
+						if (u.name === name) found.set(name, u);
+						else if (u.profile?.display_name === name || (u.profile?.real_name ?? u.real_name) === name) {
+							aliasHits.set(name, [...(aliasHits.get(name) ?? []), u]);
+						}
+					}
+				}
+				const meta = data.response_metadata as { next_cursor?: string } | undefined;
+				const nextCursor = meta?.next_cursor ?? "";
+				if (nextCursor !== "" && nextCursor === cursor) break;
+				cursor = nextCursor;
+				if (!cursor) break;
+			}
+
+			const writes: SlackUser[] = [];
+			for (const name of outstanding) {
+				const exact = found.get(name);
+				const aliases = aliasHits.get(name) ?? [];
+				const pick = exact ?? (aliases.length === 1 ? aliases[0] : undefined);
+				if (!pick) continue;
+				resolved.set(name, pick.id);
+				writes.push(pick);
+			}
+			if (writes.length > 0) {
+				const teamId = cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal));
+				mergeAndWrite(ctx.filePath, teamId, (base) => {
+					for (const u of writes) base.users[u.name] = toUserEntry(u);
+				});
+			}
+		} catch (err) {
+			lookupError = err instanceof Error ? err.message : String(err);
+		}
+	}
+
+	const unresolved: UnresolvedMention[] = [];
+	const seenUnresolved = new Set<string>();
+	const values = fields.map((f, fi) => {
+		let out = "";
+		let cursor = 0;
+		for (const c of perField[fi]) {
+			out += f.value.slice(cursor, c.start);
+			const literal = f.value.slice(c.start, c.end);
+			if (c.escaped) {
+				out += literal.slice(1);
+				cursor = c.end;
+			} else {
+				const hit = c.lookups.find(([n]) => resolved.has(n));
+				if (hit !== undefined) {
+					out += `<@${resolved.get(hit[0])}>`;
+					cursor = hit[1];
+				} else {
+					out += literal;
+					const name = `@${c.lookups[0][0]}`;
+					// Documented contract (doc/slack.md): unresolvedMentions is deduplicated by
+					// (field, name), so "cc @bob @bob" reports @bob once, not once per occurrence.
+					const key = `${c.field}\u0000${name}`;
+					if (!seenUnresolved.has(key)) {
+						seenUnresolved.add(key);
+						unresolved.push({ field: c.field, name });
+					}
+					cursor = c.end;
+				}
+			}
+		}
+		return out + f.value.slice(cursor);
+	});
+
+	return { values, unresolved, ...(lookupError !== undefined ? { lookupError } : {}) };
+}
+
 /**
  * Full snapshot replace, deliberately asymmetric with mergeAndWrite: refresh's job is to
  * atomically overwrite the whole file, so a concurrent mergeAndWrite write racing this one may
  * be clobbered (last-writer-wins). Accepted per spec (doc/specs/2026-08-29-gh-7-slack-extension.md
  * Cache section) - a clobbered merge self-heals on the next cache miss.
  */
-export async function refreshCache(ctx: CacheCtx): Promise<{ channels: number; users: number }> {
+export async function refreshCache(ctx: CacheCtx): Promise<{ channels: number; users: number; emails: number }> {
 	const teamId = await teamIdFor(ctx.token, ctx.apiCall, ctx.signal);
 	const channels: Record<string, string> = {};
-	const users: Record<string, { id: string; display_name: string; real_name: string }> = {};
+	const users: Record<string, UserEntry> = {};
 
 	let cursor = "";
 	for (let page = 1; ; page++) {
@@ -319,7 +513,7 @@ export async function refreshCache(ctx: CacheCtx): Promise<{ channels: number; u
 		const data = await ctx.apiCall("users.list", ctx.token, { limit: 1000, ...(cursor ? { cursor } : {}) }, { retry: false, signal: ctx.signal });
 		const members = (data.members as SlackUser[]) ?? [];
 		for (const u of members) {
-			users[u.name] = { id: u.id, display_name: u.profile?.display_name ?? "", real_name: u.profile?.real_name ?? u.real_name ?? "" };
+			users[u.name] = toUserEntry(u);
 		}
 		const meta = data.response_metadata as { next_cursor?: string } | undefined;
 		const nextCursor = meta?.next_cursor ?? "";
@@ -333,6 +527,11 @@ export async function refreshCache(ctx: CacheCtx): Promise<{ channels: number; u
 		if (!cursor) break;
 	}
 
-	atomicWrite(ctx.filePath, { team_id: teamId, channels, users, refreshed_at: new Date().toISOString() });
-	return { channels: Object.keys(channels).length, users: Object.keys(users).length };
+	const snapshotAt = new Date().toISOString();
+	atomicWrite(ctx.filePath, { team_id: teamId, channels, users, refreshed_at: snapshotAt, snapshot_at: snapshotAt });
+	return {
+		channels: Object.keys(channels).length,
+		users: Object.keys(users).length,
+		emails: Object.values(users).filter((u) => u.email !== undefined).length,
+	};
 }

package/lib/slack-core.ts

@@ -19,6 +19,7 @@ import { resolveConfig } from "./extension-config.ts";
 export interface SlackConfig {
 	enabled: boolean;
 	cachePath: string | undefined;
+	policyPath: string | undefined;
 	userTokenEnv: string;
 	botTokenEnv: string;
 	uploadThresholdChars: number;
@@ -27,6 +28,7 @@ export interface SlackConfig {
 export const DEFAULT_SLACK_CONFIG: SlackConfig = {
 	enabled: false,
 	cachePath: undefined,
+	policyPath: undefined,
 	userTokenEnv: "SLACK_USER_TOKEN",
 	botTokenEnv: "SLACK_BOT_TOKEN",
 	uploadThresholdChars: 4000,
@@ -49,6 +51,7 @@ export function coerce(raw: unknown): Partial<SlackConfig> | undefined {
 	const patch: Partial<SlackConfig> = {};
 	if (typeof o.enabled === "boolean") patch.enabled = o.enabled;
 	if (typeof o.cachePath === "string") patch.cachePath = o.cachePath;
+	if (typeof o.policyPath === "string") patch.policyPath = o.policyPath;
 	if (typeof o.userTokenEnv === "string") patch.userTokenEnv = o.userTokenEnv;
 	if (typeof o.botTokenEnv === "string") patch.botTokenEnv = o.botTokenEnv;
 	if (typeof o.uploadThresholdChars === "number" && Number.isInteger(o.uploadThresholdChars) && o.uploadThresholdChars > 0) {
@@ -635,7 +638,14 @@ async function withPermalink(deps: CoreDeps, channel: string, ts: string): Promi
 }
 
 export async function postPlain(
-	args: { channel: string; text?: string; blocks?: unknown[]; thread_ts?: string },
+	args: {
+		channel: string;
+		text?: string;
+		blocks?: unknown[];
+		thread_ts?: string;
+		unfurl_links?: boolean;
+		unfurl_media?: boolean;
+	},
 	deps: CoreDeps,
 ): Promise<MutationResult> {
 	assertTextWithinLimit(args.text);
@@ -644,6 +654,8 @@ export async function postPlain(
 	if (args.text !== undefined) params.text = args.text;
 	if (args.blocks !== undefined) params.blocks = args.blocks;
 	if (args.thread_ts !== undefined) params.thread_ts = args.thread_ts;
+	if (args.unfurl_links !== undefined) params.unfurl_links = args.unfurl_links;
+	if (args.unfurl_media !== undefined) params.unfurl_media = args.unfurl_media;
 
 	const data = await deps.apiCall("chat.postMessage", deps.token, params, { retry: true, signal: deps.signal });
 	const channel = typeof data.channel === "string" ? data.channel : args.channel;
@@ -740,6 +752,49 @@ export function linkCollapsedLength(text: string): number {
 	return text.replace(/<([^|>]+)\|([^>]+)>/g, "$2").replace(/<[^>]+>/g, "x").length;
 }
 
+function escapeAttr(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/** Pure: the handler in extensions/slack.ts owns readFileSync and maps the outcome to this input. */
+export function buildPolicyBlock(input: {
+	source: string;
+	status: "ok" | "unreadable" | "empty";
+	body?: string;
+	code?: string;
+}): string {
+	const source = escapeAttr(input.source);
+	if (input.status === "ok") {
+		return `<slack-policy source="${source}">\n${input.body ?? ""}</slack-policy>`;
+	}
+	const reason =
+		input.status === "empty"
+			? `Configured Slack policy file is empty.`
+			: `Configured Slack policy file could not be read (${input.code ?? "unknown error"}).`;
+	return `<slack-policy source="${source}" status="${input.status}">\n${reason} Slack tools are available but the repository's posting policy is unknown - ask the operator before posting.\n</slack-policy>`;
+}
+
+export interface UnresolvedMention {
+	field: "text" | "thread_body";
+	name: string;
+}
+
+/** Pure: the `channelLine` suffix segment for unresolved mentions. Empty string means "append nothing". */
+export function formatUnresolvedSuffix(
+	unresolved: UnresolvedMention[],
+	opts: { lookupError?: string; detailUploaded?: boolean },
+): string {
+	if (unresolved.length === 0) return "";
+	const names: string[] = [];
+	for (const u of unresolved) if (!names.includes(u.name)) names.push(u.name);
+	let suffix = `unresolved mentions: ${names.join(", ")}`;
+	if (opts.lookupError !== undefined) suffix += ` (lookup failed: ${opts.lookupError})`;
+	if (opts.detailUploaded && unresolved.some((u) => u.field === "thread_body")) {
+		suffix += ` (detail uploaded as a file - slack_update cannot repair it; repost to fix)`;
+	}
+	return suffix;
+}
+
 export function persistDetail(body: string): string {
 	const dir = join(tmpdir(), "pi-slack");
 	mkdirSync(dir, { recursive: true });
@@ -763,6 +818,11 @@ function assertHeadline(text: string): void {
 
 export interface AnnounceResult extends MutationResult {
 	detailTs?: string;
+	// Set only when the detail leg took the file-upload path (deliverDetailUpload) rather than the
+	// inline threaded chat.postMessage reply - detailTs alone can't distinguish the two, since both
+	// paths set it. slack_update can edit the headline or the "Detail attached." stub, never an
+	// uploaded file's contents, so callers need this to know a mention-repair edit won't reach it.
+	detailUploaded?: true;
 }
 
 async function deliverDetailUpload(
@@ -874,14 +934,23 @@ async function recoverFromDetailFailure(
 
 export async function announce(
 	args: { channel: string; text: string; thread_body: string },
-	deps: CoreDeps & { uploadBytes: UploadBytes; thresholdChars: number; persist?: (body: string) => string },
+	deps: CoreDeps & {
+		uploadBytes: UploadBytes;
+		thresholdChars: number;
+		persist?: (body: string) => string;
+		unfurl_links?: boolean;
+		unfurl_media?: boolean;
+	},
 ): Promise<AnnounceResult> {
 	assertHeadline(args.text);
 	const persist = deps.persist ?? persistDetail;
+	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;
 
 	let headlineData: Record<string, unknown>;
 	try {
-		headlineData = await deps.apiCall("chat.postMessage", deps.token, { channel: args.channel, text: args.text }, { retry: false, signal: deps.signal });
+		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);
@@ -923,7 +992,7 @@ export async function announce(
 			const causeMessage = err instanceof Error ? err.message : String(err);
 			return recoverFromDetailFailure(causeMessage, args.text, args.thread_body, channel, ts, permalink, deps, persist);
 		}
-		return { channel, ts, permalink, warning, detailTs };
+		return { channel, ts, permalink, warning, detailTs, detailUploaded: true };
 	}
 
 	let detailData: Record<string, unknown>;
@@ -931,14 +1000,14 @@ export async function announce(
 		detailData = await deps.apiCall(
 			"chat.postMessage",
 			deps.token,
-			{ channel, text: args.thread_body, thread_ts: ts },
+			{ channel, text: args.thread_body, thread_ts: ts, ...unfurl },
 			{ retry: true, signal: deps.signal },
 		);
 	} catch (err) {
 		if (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 };
+				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);
@@ -953,11 +1022,22 @@ export async function announce(
 }
 
 export async function postMessage(
-	args: { channel: string; text?: string; blocks?: unknown[]; thread_ts?: string; thread_body?: string },
+	args: {
+		channel: string;
+		text?: string;
+		blocks?: unknown[];
+		thread_ts?: string;
+		thread_body?: string;
+		unfurl_links?: boolean;
+		unfurl_media?: boolean;
+	},
 	deps: CoreDeps & { uploadBytes: UploadBytes; thresholdChars: number; persist?: (body: string) => 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 }, deps);
+		return announce(
+			{ channel: args.channel, text: args.text ?? "", thread_body: args.thread_body },
+			{ ...deps, unfurl_links: args.unfurl_links, unfurl_media: args.unfurl_media },
+		);
 	}
 
 	if (args.thread_ts !== undefined) {
@@ -965,7 +1045,14 @@ export async function postMessage(
 		// the threshold/upload path only applies when composing plain mrkdwn from thread_body/text.
 		if (args.blocks !== undefined) {
 			return postPlain(
-				{ channel: args.channel, text: args.thread_body ?? args.text, blocks: args.blocks, thread_ts: args.thread_ts },
+				{
+					channel: args.channel,
+					text: args.thread_body ?? args.text,
+					blocks: args.blocks,
+					thread_ts: args.thread_ts,
+					unfurl_links: args.unfurl_links,
+					unfurl_media: args.unfurl_media,
+				},
 				deps,
 			);
 		}
@@ -980,7 +1067,10 @@ export async function postMessage(
 		// (server-side). This body is extension-composed detail, same as announce's detail leg, so
 		// it gets the same upload fallback instead of a bare throw.
 		try {
-			return await postPlain({ channel: args.channel, text: body, thread_ts: args.thread_ts }, deps);
+			return await postPlain(
+				{ channel: args.channel, text: body, thread_ts: args.thread_ts, unfurl_links: args.unfurl_links, unfurl_media: args.unfurl_media },
+				deps,
+			);
 		} catch (err) {
 			if (err instanceof SlackError && (err.code === "text_too_long" || err.code === "msg_too_long")) {
 				const { detailTs } = await deliverDetailUploadOrPersist(args.channel, args.thread_ts, body, deps);
@@ -990,5 +1080,8 @@ export async function postMessage(
 		}
 	}
 
-	return postPlain({ channel: args.channel, text: args.text, blocks: args.blocks }, deps);
+	return postPlain(
+		{ channel: args.channel, text: args.text, blocks: args.blocks, unfurl_links: args.unfurl_links, unfurl_media: args.unfurl_media },
+		deps,
+	);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "5.0.0",
+  "version": "5.2.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",