pi-quiver 5.1.0 → 5.2.1

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.1 - 2026-09-02
+
+- sword-header: clip each header line to the terminal width in `render(width)` (ANSI-aware `truncateToWidth`, hard clip). Fixes a hard crash (`Rendered line N exceeds terminal width`) in terminals/panes narrower than 80 columns.
+
+## 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).

package/README.md

@@ -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/sword-header.ts

@@ -14,6 +14,7 @@
  */
 
 import type { ExtensionAPI, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
 import { resolveConfig } from "../lib/extension-config.ts";
 
 type Config = { enabled: boolean };
@@ -69,8 +70,8 @@ export default function (pi: ExtensionAPI) {
 		const cfg = resolveConfig(ctx.cwd, "swordHeader", DEFAULT_CONFIG, coerce, (m) => ctx.ui.notify(m, "warning"));
 		if (!cfg.enabled) return;
 		ctx.ui.setHeader((_tui, theme) => ({
-			render(_width: number): string[] {
-				return renderSwordLines(theme);
+			render(width: number): string[] {
+				return renderSwordLines(theme).map((line) => truncateToWidth(line, width, ""));
 			},
 			invalidate() {},
 		}));

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/package.json

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