pi-quiver 5.3.0 → 5.5.0

package/CHANGELOG.md

@@ -8,6 +8,26 @@ 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.5.0 - 2026-09-10
+
+- doc_to_md: rewrite primary-PDF image links correctly on Windows.
+- slack: optionally resolve the user token through a credential command on every user-identity tool call, with a configurable timeout in seconds, allowing running pi sessions to use replaced credentials without leaking secrets on command failure or falling back to stale env tokens.
+
+## v5.4.0 - 2026-09-10
+
+- Settings: one condensed `pi-quiver settings` warning (each distinct message
+  once per process) lists flat legacy keys in use, unknown `quiver.<block>`
+  names, and unknown fields inside
+  known blocks, with accepted names inline; unknown keys fall back to defaults.
+  Replaces the separate non-object-`quiver` and flat+nested-duplicate sentences;
+  a flat legacy key alone now warns (still honoured). Accepted names are the
+  exported `QUIVER_CONFIG_KEYS` registry in `lib/extension-config.ts` (#14).
+- Settings warnings from `fast-mode`, `session-name`, and `slack` reach stderr
+  when no UI is bound (print/json modes) instead of being dropped by the no-op
+  headless `notify`.
+- doc_to_md: the coercer no longer warns about unknown `quiver.docToMd` keys (the
+  settings lint does); the `pi-quiver` CLI reader warns about them itself.
+
 ## v5.3.0 - 2026-09-09
 
 - doc_to_md: results are now a bundle on disk (`<stem>.md` + `images/`, temp dir

package/README.md

@@ -173,6 +173,22 @@ legacy keys, frozen at `fastMode`, `sessionAutoName`, `swordHeader`, and
 `providerStallWatchdog` - never extended to new settings (see [Migrating from
 flat keys](#migrating-from-flat-keys)).
 
+pi-quiver lints the whole `quiver` object in both files each time a setting is
+resolved and emits **one** condensed warning (TUI: a `Warning:` block in the
+chat; headless: stderr) listing every flat legacy key in use, every unknown
+`quiver.<block>`, and every unknown field inside a known block, with the
+accepted names inline. Unknown keys fall back to their defaults. Each distinct
+message fires once per pi process; a clean file emits nothing. A wrong value
+type (`"fastMode": "yes"`) is a separate per-key `unrecognized value` warning.
+The accepted names live in `QUIVER_CONFIG_KEYS` in `lib/extension-config.ts` -
+a new setting is registered there or it warns as unknown.
+
+```text
+Warning: pi-quiver settings (/Users/x/.pi/agent/settings.json): unknown or misplaced keys - unknown ones fall back to defaults
+  "providerStallWatchdog" at top level - move under "quiver"
+  "quiver.providerStallWatchdog.timeoutMs" - unknown; accepted: enabled, firstEventMs, warningMs, recoveryMs, maxStallRetries
+```
+
 Worked mixed-shape example: global `settings.json` has flat
 `"fastMode": false`, project `.pi/settings.json` has
 `"quiver": { "fastMode": { "enabled": true } }`. The project layer's
@@ -258,11 +274,13 @@ Operational notes:
 | --- | --- | --- |
 | `enabled` | `false` | Master switch, checked at `session_start`; toggling takes effect next session. |
 | `cachePath` | user-scope per-OS cache dir | Overrides where the workspace-keyed channel/user name->ID cache file is written; relative paths resolve against the repo root. |
-| `userTokenEnv` | `SLACK_USER_TOKEN` | Env var name holding the user token (required for `slack_search`/`slack_thread`, no bot fallback). |
+| `userTokenEnv` | `SLACK_USER_TOKEN` | Env var name holding the user token when `userTokenCommand` is unset (required for `slack_search`/`slack_thread`, no bot fallback). |
+| `userTokenCommand` | unset | Executable argv array that prints the current user token to stdout; resolved on every user-identity tool call. |
+| `userTokenCommandTimeoutSeconds` | `10` | Positive finite timeout in seconds for `userTokenCommand`. Increase this when an interactive credential helper may need authorization. |
 | `botTokenEnv` | `SLACK_BOT_TOKEN` | Env var name holding the bot token. |
 | `uploadThresholdChars` | `4000` | Link-collapsed length above which an announce/thread detail body is delivered as a file upload instead of inline text. |
 
-Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `PI_QUIVER_SLACK_CACHE_PATH`, `PI_QUIVER_SLACK_USER_TOKEN_ENV`, `PI_QUIVER_SLACK_BOT_TOKEN_ENV`, and `PI_QUIVER_SLACK_UPLOAD_THRESHOLD_CHARS` - applied on top of the resolved `settings.json` layers, same override rung the extension's config resolver defines. Tokens themselves are resolved per call: process env first, then the repo's `.env` file (or the primary checkout's, for a worktree with none) - never a fallback across identities. Full reference incl. cache layering, the announce protocol, and the `search.messages`/`conversations.replies` throttle caveats: [doc/slack.md](doc/slack.md).
+Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `PI_QUIVER_SLACK_CACHE_PATH`, `PI_QUIVER_SLACK_USER_TOKEN_ENV`, `PI_QUIVER_SLACK_BOT_TOKEN_ENV`, and `PI_QUIVER_SLACK_UPLOAD_THRESHOLD_CHARS` - applied on top of the resolved `settings.json` layers, same override rung the extension's config resolver defines. `userTokenCommand` and `userTokenCommandTimeoutSeconds` are settings-only: pi executes the argv directly, without a shell, on every user-identity Slack tool call. For example, macOS Keychain can supply the token with `"userTokenCommand": ["security", "find-generic-password", "-s", "slack-user-token", "-w"]`. Its stdout is the token; empty output, nonzero exit, or timeout is a sanitized hard error and never falls back to `userTokenEnv`. Without the command, tokens resolve per call from process env and then `.env` (or the primary checkout's, for a worktree with none). Bot resolution is unchanged. Restart pi after changing Slack settings because the extension captures them at session start. Full reference incl. cache layering, the announce protocol, and the `search.messages`/`conversations.replies` throttle caveats: [doc/slack.md](doc/slack.md).
 
 ### doc_to_md settings
 
@@ -304,13 +322,12 @@ existing keys under `"quiver": { ... }` and delete the flat copies:
 { "quiver": { "fastMode": true } }
 ```
 
-Until you delete the flat copy, having both set is not an error - the
-duplicate resolves per the precedence above (nested wins within a layer) -
-but it emits a warning notification, deduped per process (each unique
-message fires at most once per pi process - in practice once per interactive
-session) until the flat entry is removed. Every new pi-quiver setting introduced after this change
-(for example a future `slack` key) is nested-only from day one: it has no
-flat form to fall back to.
+A flat copy keeps resolving (nested wins within a layer, project layer wins
+across layers) but every flat legacy key in use is listed in the condensed
+settings warning above (`"fastMode" at top level - move under "quiver"`) until
+it is moved. Every new pi-quiver setting introduced after this change (for
+example `slack`) is nested-only from day one: it has no flat form to fall back
+to, and a flat `slack` block is ignored without a warning.
 
 ## Claude Code support
 

package/dist/bin/pi-quiver.js

@@ -796,10 +796,7 @@ function coerceDocToMdSettings(raw, warn = console.warn) {
   const out = {};
   for (const [k, v] of Object.entries(raw)) {
     const d = DOC_TO_MD_OPTIONS.find((o) => o.key === k);
-    if (!d || !d.settable) {
-      warn(`pi-quiver: quiver.docToMd.${k} is not a tunable setting; ignored.`);
-      continue;
-    }
+    if (!d || !d.settable) continue;
     const c = coerceValue(d, v);
     if (!c.ok) {
       warn(`pi-quiver: quiver.docToMd.${k} ${c.reason}; ignored.`);
@@ -1406,6 +1403,10 @@ function readCliSettings(cwd, env, warn) {
       continue;
     }
     if (raw === void 0) continue;
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+      const unknown = Object.keys(raw).filter((k) => !DOC_TO_MD_OPTIONS.some((o) => o.key === k && o.settable));
+      if (unknown.length > 0) warn(`pi-quiver: quiver.docToMd in ${file} has keys that are not tunable settings; ignored: ${unknown.join(", ")}`);
+    }
     const patch = coerceDocToMdSettings(raw, warn);
     if (patch) Object.assign(out, patch);
     else warn(`pi-quiver: "docToMd" in ${file} has an unrecognized value; ignored.`);

package/extensions/fast-mode.ts

@@ -65,7 +65,7 @@ const STATUS_KEY = "fast-mode";
 const BETA_HEADER = "anthropic-beta";
 
 type Config = { enabled: boolean };
-const DEFAULT_CONFIG: Config = { enabled: false };
+export const DEFAULT_CONFIG: Config = { enabled: false };
 
 export function coerce(raw: unknown): Partial<Config> | undefined {
 	if (raw === undefined) return undefined;
@@ -189,7 +189,7 @@ export default function (pi: ExtensionAPI) {
 	const readFlag = (): boolean => pi.getFlag("fast") === true;
 
 	const resolveState = (ctx: ExtensionContext): boolean => {
-		const config = resolveConfig(ctx.cwd, "fastMode", DEFAULT_CONFIG, coerce, (m) => ctx.ui.notify(m, "warning")).enabled;
+		const config = resolveConfig(ctx.cwd, "fastMode", DEFAULT_CONFIG, coerce, (m) => ctx.hasUI ? ctx.ui.notify(m, "warning") : console.warn(m)).enabled;
 		enabled = resolveEnabled({ config, flag: readFlag(), live: liveOverride });
 		return enabled;
 	};

package/extensions/session-name.ts

@@ -64,7 +64,7 @@ type Config = {
 	revisitFirstTurn: number;
 	revisitEveryTurns: number;
 };
-const DEFAULT_CONFIG: Config = {
+export const DEFAULT_CONFIG: Config = {
 	enabled: false,
 	ghosttyTab: true,
 	herdrTab: true,
@@ -105,7 +105,7 @@ export function coerce(raw: unknown): Partial<Config> | undefined {
 }
 
 function loadConfig(ctx: ExtensionContext): Config {
-	return resolveConfig(ctx.cwd, "sessionAutoName", DEFAULT_CONFIG, coerce, (m) => ctx.ui.notify(m, "warning"));
+	return resolveConfig(ctx.cwd, "sessionAutoName", DEFAULT_CONFIG, coerce, (m) => ctx.hasUI ? ctx.ui.notify(m, "warning") : console.warn(m));
 }
 
 type ContentBlock = { type?: string; text?: string };

package/extensions/slack.ts

@@ -19,6 +19,7 @@ import {
 	buildPolicyBlock,
 	discoverRepoRoot,
 	resolveSlackConfig,
+	resolveCredential,
 	resolveToken,
 	searchMessages,
 	readThread,
@@ -40,7 +41,7 @@ import {
 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.',
+	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.',
 });
 
 // Approved recovery fields only - never dump the raw Slack API response (err.data can carry it
@@ -75,12 +76,13 @@ async function resolveCall(
 	signal: AbortSignal | undefined,
 	repoRoot: string,
 ): Promise<ResolvedCall> {
-	const token = resolveToken(identity, cfg, process.env, repoRoot);
+	const token = await resolveCredential(identity, cfg, process.env, repoRoot);
 	const teamId = await teamIdFor(token, defaultApiCall, signal);
 	const otherIdentity = identity === "user" ? "bot" : "user";
 	const otherTeamId = await (async () => {
+		if (otherIdentity === "user" && cfg.userTokenCommand) return undefined;
 		try {
-			const otherToken = resolveToken(otherIdentity, cfg, process.env, repoRoot);
+			const otherToken = await resolveCredential(otherIdentity, cfg, process.env, repoRoot);
 			return await teamIdFor(otherToken, defaultApiCall, signal);
 		} catch {
 			// Other identity's token can't be resolved/authenticated - best-effort
@@ -99,14 +101,14 @@ async function resolveCall(
 
 /**
  * slack_cache_refresh's identity pick: user token when present, else bot (spec "Cache" section).
- * Pure and network-free - resolveToken only reads env/.env - so it's unit-testable without a
- * transport seam.
+ * Pure and network-free - command configuration counts as a user credential without executing it.
  */
 export function pickCacheRefreshIdentity(
 	cfg: SlackConfig,
 	env: Record<string, string | undefined>,
 	repoRoot: string,
 ): "user" | "bot" {
+	if (cfg.userTokenCommand) return "user";
 	try {
 		resolveToken("user", cfg, env, repoRoot);
 		return "user";
@@ -200,7 +202,7 @@ export default function slackExtension(pi: ExtensionAPI) {
 	let registered = false;
 
 	pi.on("session_start", async (_event, ctx) => {
-		const cfg = resolveSlackConfig(ctx.cwd, process.env, (m) => ctx.ui.notify(m, "warning"));
+		const cfg = resolveSlackConfig(ctx.cwd, process.env, (m) => ctx.hasUI ? ctx.ui.notify(m, "warning") : console.warn(m));
 		if (cfg.enabled !== true) return;
 		if (registered) return;
 		registered = true;

package/extensions/sword-header.ts

@@ -18,7 +18,7 @@ import { truncateToWidth } from "@earendil-works/pi-tui";
 import { resolveConfig } from "../lib/extension-config.ts";
 
 type Config = { enabled: boolean };
-const DEFAULT_CONFIG: Config = { enabled: false };
+export const DEFAULT_CONFIG: Config = { enabled: false };
 
 export function coerce(raw: unknown): Partial<Config> | undefined {
 	if (raw === undefined) return undefined;

package/lib/doc-to-md-options.ts

@@ -105,13 +105,13 @@ function coerceValue(d: OptionDescriptor, raw: unknown, fromString = false): { o
 	}
 }
 
-/** Single validation boundary for `quiver.docToMd`: unknown/ill-typed/intent keys are dropped with one warning each. */
+/** Type-validation boundary for `quiver.docToMd`: ill-typed keys are dropped with one warning each; unknown/intent keys are skipped (the settings lint reports them). */
 export function coerceDocToMdSettings(raw: unknown, warn: (message: string) => void = console.warn): Partial<Tunables> | undefined {
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const out: Record<string, unknown> = {};
 	for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
 		const d = DOC_TO_MD_OPTIONS.find((o) => o.key === k);
-		if (!d || !d.settable) { warn(`pi-quiver: quiver.docToMd.${k} is not a tunable setting; ignored.`); continue; }
+		if (!d || !d.settable) continue;
 		const c = coerceValue(d, v);
 		if (!c.ok) { warn(`pi-quiver: quiver.docToMd.${k} ${c.reason}; ignored.`); continue; }
 		out[k] = c.value;

package/lib/extension-config.ts

@@ -20,6 +20,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { DOC_TO_MD_OPTIONS } from "./doc-to-md-options.ts";
 
 export function readSettings(path: string): Record<string, unknown> | undefined {
 	try {
@@ -36,6 +37,22 @@ export function settingsPaths(cwd: string): string[] {
 /** Flat top-level fallback is frozen to these pre-quiver keys; never extend. */
 const LEGACY_FLAT_KEYS = new Set(["fastMode", "sessionAutoName", "swordHeader", "providerStallWatchdog"]);
 
+/**
+ * Lint allowlist: every pi-quiver settings block and its fields. A key read
+ * by an extension but missing here is reported as unknown - register new
+ * keys here first.
+ */
+export const QUIVER_CONFIG_KEYS: Record<string, readonly string[]> = {
+	fastMode: ["enabled"],
+	sessionAutoName: ["enabled", "ghosttyTab", "herdrTab", "rules", "deny", "revisitFirstTurn", "revisitEveryTurns"],
+	swordHeader: ["enabled"],
+	providerStallWatchdog: ["enabled", "firstEventMs", "warningMs", "recoveryMs", "maxStallRetries"],
+	slack: ["enabled", "cachePath", "policyPath", "userTokenEnv", "userTokenCommand", "userTokenCommandTimeoutSeconds", "botTokenEnv", "uploadThresholdChars"],
+	docToMd: DOC_TO_MD_OPTIONS.filter((o) => o.settable).map((o) => o.key),
+};
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+
 const emittedWarnings = new Set<string>();
 
 function emitWarning(warn: ((message: string) => void) | undefined, message: string): void {
@@ -44,49 +61,68 @@ function emitWarning(warn: ((message: string) => void) | undefined, message: str
 	warn(message);
 }
 
+/** Structural findings for one parsed settings file: flat legacy use, non-object quiver, unknown blocks, unknown fields. */
+function lintSettings(settings: Record<string, unknown>): string[] {
+	const lines: string[] = [];
+	for (const key of Object.keys(settings)) if (LEGACY_FLAT_KEYS.has(key)) lines.push(`"${key}" at top level - move under "quiver"`);
+	const root = settings.quiver;
+	if (root === undefined) return lines;
+	if (!isPlainObject(root)) return [...lines, `"quiver" is not an object - ignored`];
+	const fieldLines: string[] = [];
+	for (const [block, value] of Object.entries(root)) {
+		if (!Object.hasOwn(QUIVER_CONFIG_KEYS, block)) {
+			lines.push(`"quiver.${block}" - unknown block; accepted: ${Object.keys(QUIVER_CONFIG_KEYS).join(", ")}`);
+			continue;
+		}
+		if (!isPlainObject(value)) continue;
+		const fields = QUIVER_CONFIG_KEYS[block];
+		for (const field of Object.keys(value)) if (!fields.includes(field)) fieldLines.push(`"quiver.${block}.${field}" - unknown; accepted: ${fields.join(", ")}`);
+	}
+	return [...lines, ...fieldLines];
+}
+
+function formatLint(findings: Array<[path: string, lines: string[]]>): string {
+	const tail = "unknown or misplaced keys - unknown ones fall back to defaults";
+	if (findings.length === 1) {
+		const [path, lines] = findings[0];
+		return [`pi-quiver settings (${path}): ${tail}`, ...lines.map((l) => `  ${l}`)].join("\n");
+	}
+	return [`pi-quiver settings: ${tail}`, ...findings.flatMap(([path, lines]) => [`  ${path}`, ...lines.map((l) => `    ${l}`)])].join("\n");
+}
+
 /**
  * Resolve a single extension config key across the settings layers.
  * `quiver.<key>` wins over flat `<key>` within a layer by presence (even
  * when malformed); flat fallback exists only for LEGACY_FLAT_KEYS. `coerce`
  * validates the layer's candidate into a partial patch (or `undefined` to
  * skip); patches merge over `defaults` in layer order (project wins).
- * `warn` receives one sentence per malformed or flat/nested-duplicated key,
- * deduped per process.
+ * `warn` receives one sentence per malformed key plus one condensed
+ * structural lint (flat legacy use, unknown blocks, unknown fields) - each
+ * distinct message once per process.
  */
 export function resolveConfig<T extends object>(
 	cwd: string,
 	key: string,
 	defaults: T,
-	coerce: (raw: unknown) => Partial<T> | undefined,
+	coerce: (raw: unknown, warn?: (message: string) => void) => Partial<T> | undefined,
 	warn?: (message: string) => void,
 ): T {
 	const cfg: T = { ...defaults };
-	let nestedSeen = false;
-	let flatSeen = false;
+	const findings: Array<[string, string[]]> = [];
 	for (const path of settingsPaths(cwd)) {
 		const settings = readSettings(path);
 		if (!settings) continue;
-		let root = settings.quiver;
-		if (root !== undefined && (root === null || typeof root !== "object" || Array.isArray(root))) {
-			emitWarning(warn, `pi-quiver: "quiver" in ${path} is not an object; ignored.`);
-			root = undefined;
-		}
-		const nested = root as Record<string, unknown> | undefined;
+		const lines = lintSettings(settings);
+		if (lines.length > 0) findings.push([path, lines]);
+		const nested = isPlainObject(settings.quiver) ? settings.quiver : undefined;
 		const hasNested = nested !== undefined && Object.hasOwn(nested, key);
 		const hasFlat = Object.hasOwn(settings, key);
-		nestedSeen ||= hasNested;
-		flatSeen ||= hasFlat;
 		if (!hasNested && !(hasFlat && LEGACY_FLAT_KEYS.has(key))) continue;
 		const candidate = hasNested ? nested![key] : settings[key];
-		const patch = coerce(candidate);
+		const patch = coerce(candidate, (message) => emitWarning(warn, message));
 		if (patch) Object.assign(cfg, patch);
 		else emitWarning(warn, `pi-quiver: "${key}" in ${path} has an unrecognized value; ignored.`);
 	}
-	if (nestedSeen && flatSeen) {
-		emitWarning(
-			warn,
-			`pi-quiver: "${key}" is set both flat and under "quiver" (nested wins within a layer; across layers the project layer wins regardless of shape) - move the flat entry under "quiver".`,
-		);
-	}
+	if (findings.length > 0) emitWarning(warn, formatLint(findings));
 	return cfg;
 }

package/lib/slack-core.ts

@@ -9,7 +9,7 @@
  * slack-local `PI_QUIVER_SLACK_*` env-var overlay applied on top.
  */
 
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -21,6 +21,8 @@ export interface SlackConfig {
 	cachePath: string | undefined;
 	policyPath: string | undefined;
 	userTokenEnv: string;
+	userTokenCommand: string[] | undefined;
+	userTokenCommandTimeoutSeconds: number;
 	botTokenEnv: string;
 	uploadThresholdChars: number;
 }
@@ -30,6 +32,8 @@ export const DEFAULT_SLACK_CONFIG: SlackConfig = {
 	cachePath: undefined,
 	policyPath: undefined,
 	userTokenEnv: "SLACK_USER_TOKEN",
+	userTokenCommand: undefined,
+	userTokenCommandTimeoutSeconds: 10,
 	botTokenEnv: "SLACK_BOT_TOKEN",
 	uploadThresholdChars: 4000,
 };
@@ -44,7 +48,9 @@ export class SlackError extends Error {
 	}
 }
 
-export function coerce(raw: unknown): Partial<SlackConfig> | undefined {
+const MAX_TIMER_SECONDS = 2_147_483.647;
+
+export function coerce(raw: unknown, warn?: (message: string) => void): Partial<SlackConfig> | undefined {
 	if (typeof raw === "boolean") return { enabled: raw };
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const o = raw as Record<string, unknown>;
@@ -53,6 +59,28 @@ export function coerce(raw: unknown): Partial<SlackConfig> | undefined {
 	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 (
+		Array.isArray(o.userTokenCommand) &&
+		typeof o.userTokenCommand[0] === "string" &&
+		o.userTokenCommand[0].length > 0 &&
+		o.userTokenCommand.every((part) => typeof part === "string")
+	) {
+		patch.userTokenCommand = [...o.userTokenCommand];
+	}
+	if (o.userTokenCommandTimeoutSeconds !== undefined) {
+		if (
+			typeof o.userTokenCommandTimeoutSeconds === "number" &&
+			Number.isFinite(o.userTokenCommandTimeoutSeconds) &&
+			o.userTokenCommandTimeoutSeconds > 0 &&
+			o.userTokenCommandTimeoutSeconds <= MAX_TIMER_SECONDS
+		) {
+			patch.userTokenCommandTimeoutSeconds = o.userTokenCommandTimeoutSeconds;
+		} else {
+			warn?.(
+				`pi-quiver: quiver.slack.userTokenCommandTimeoutSeconds must be a positive finite number no greater than ${MAX_TIMER_SECONDS}; ignored.`,
+			);
+		}
+	}
 	if (typeof o.botTokenEnv === "string") patch.botTokenEnv = o.botTokenEnv;
 	if (typeof o.uploadThresholdChars === "number" && Number.isInteger(o.uploadThresholdChars) && o.uploadThresholdChars > 0) {
 		patch.uploadThresholdChars = o.uploadThresholdChars;
@@ -222,6 +250,42 @@ export function resolveToken(
 	);
 }
 
+function runCredentialCommand(command: string[], timeoutMs: number): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const [file, ...args] = command;
+		execFile(file, args, { timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 64 * 1024, encoding: "utf8" }, (err, stdout) => {
+			if (err) {
+				const childError = err as NodeJS.ErrnoException & { killed?: boolean; signal?: string | null };
+				if (childError.killed) {
+					reject(new SlackError("credential_command_failed", `Slack user credential command timed out after ${timeoutMs}ms.`));
+					return;
+				}
+				const status = typeof childError.code === "number" ? ` (status ${childError.code})` : "";
+				reject(new SlackError("credential_command_failed", `Slack user credential command failed${status}.`));
+				return;
+			}
+			const token = stdout.trim();
+			if (!token) {
+				reject(new SlackError("missing_token", "Slack user credential command returned no token."));
+				return;
+			}
+			resolve(token);
+		});
+	});
+}
+
+export async function resolveCredential(
+	identity: "user" | "bot",
+	cfg: SlackConfig,
+	env: Record<string, string | undefined>,
+	repoRoot: string,
+): Promise<string> {
+	if (identity === "user" && cfg.userTokenCommand) {
+		return runCredentialCommand(cfg.userTokenCommand, Math.ceil(cfg.userTokenCommandTimeoutSeconds * 1000));
+	}
+	return resolveToken(identity, cfg, env, repoRoot);
+}
+
 /**
  * Data-plane transport: every Slack API call and file upload funnels through
  * these two injectable functions so tests script responses without network.

package/package.json

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

package/scripts/doc_to_md.py

@@ -21,6 +21,12 @@ HTML_IMAGE_RE = re.compile(
 )
 
 
+def image_source_map(source, target, filename):
+    real = os.path.realpath(source)
+    return {source: target, source.replace("\\", "/"): target,
+            real: target, real.replace("\\", "/"): target, filename: target}
+
+
 def rewrite_image_destinations(md, sources):
     def markdown(match):
         dest = match.group(2) if match.group(2) is not None else match.group(3)
@@ -106,7 +112,7 @@ def mode_pdf_primary(o):
                     dest = f"img{i}{os.path.splitext(f)[1].lower()}"
                     source = os.path.join(tmp, f)
                     target = f"p{n}/{dest}"
-                    sources.update({source: target, os.path.realpath(source): target, f: target})
+                    sources.update(image_source_map(source, target, f))
                     os.replace(source, os.path.join(d, dest))
                 md = rewrite_image_destinations(md, sources)
             if not md.strip():