pi-quiver 5.3.0 → 5.4.0

package/CHANGELOG.md

@@ -8,6 +8,21 @@ 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.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
@@ -304,13 +320,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

@@ -200,7 +200,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", "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,14 +61,44 @@ 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,
@@ -61,32 +108,21 @@ export function resolveConfig<T extends object>(
 	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);
 		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/package.json

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