pi-quiver 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
+## v4.5.0 - 2026-08-29
+
+- Settings resolution: every pi-quiver setting is now read from an optional `"quiver"` root object in `settings.json` (`quiver.<key>`), grouping the four legacy flat keys (`fastMode`, `sessionAutoName`, `swordHeader`, `providerStallWatchdog`) plus any future key. The flat top-level form keeps working, but only for those four legacy keys - it is frozen there and never extended to new settings. Within a layer, `quiver.<key>` wins over flat `<key>` by presence; malformed values and flat/nested duplicates now emit a warning instead of resolving silently.
+
 ## v4.4.0 - 2026-08-26
 
 - doc_to_md: backend ladder now tries a system Python >= 3.12 with `pymupdf4llm` importable, then a one-time managed venv (bootstrapped at the version pin into a per-OS cache dir) between the existing `uv` and `unpdf` rungs. Data plane extracted to pi-free `lib/doc-to-md-core.ts`; new `pi-quiver doc-to-md <path>` CLI subcommand and `doc-to-md` Claude Code skill. `uv`/`soffice` detection is now spawn-based (Windows-correct). The bundled Python conversion script is now resolved from the package root, fixing a path bug that broke it under the bundled CLI.

package/README.md

@@ -137,45 +137,71 @@ None is a hard install-time dependency of the package; they are tools you provid
 
 ### Opt-in extension config
 
-These extensions are opt-in via `settings.json` (project `.pi/settings.json` overrides the global agent-dir layer):
+These extensions are opt-in via `settings.json` (project `.pi/settings.json` overrides the global agent-dir layer), nested under an optional `"quiver"` root:
 
 ```jsonc
 {
-  "sessionAutoName": {
-    "enabled": false,
-    "ghosttyTab": true,
-    "rules": [],
-    "deny": [],
-    "revisitFirstTurn": 0,
-    "revisitEveryTurns": 0
-  }, // or boolean shorthand
-  "swordHeader": false, // or { "enabled": true }
-  "fastMode": false,                                           // or { "enabled": true }
-  "providerStallWatchdog": false                               // or { "enabled": true }
+  "quiver": {
+    "sessionAutoName": {
+      "enabled": false,
+      "ghosttyTab": true,
+      "rules": [],
+      "deny": [],
+      "revisitFirstTurn": 0,
+      "revisitEveryTurns": 0
+    }, // or boolean shorthand
+    "swordHeader": false, // or { "enabled": true }
+    "fastMode": false,                                         // or { "enabled": true }
+    "providerStallWatchdog": false                             // or { "enabled": true }
+  }
 }
 ```
 
+Each key resolves independently: within a layer, `quiver.<key>` wins over a
+flat top-level `<key>` by presence alone (even when the winning value is
+malformed); across layers, each layer's candidate is validated into a partial
+patch and `Object.assign`ed over the accumulator in layer order (project
+last), so project fields override matching global fields while unmatched
+global fields survive - a flat-vs-nested shape difference between layers
+never changes this. The flat top-level form still works, but only for four
+legacy keys, frozen at `fastMode`, `sessionAutoName`, `swordHeader`, and
+`providerStallWatchdog` - never extended to new settings (see [Migrating from
+flat keys](#migrating-from-flat-keys)).
+
+Worked mixed-shape example: global `settings.json` has flat
+`"fastMode": false`, project `.pi/settings.json` has
+`"quiver": { "fastMode": { "enabled": true } }`. The project layer's
+patch (`{ "enabled": true }`) is `Object.assign`ed over the accumulator
+seeded from global's patch, so the resolved config is `{ "enabled": true }` -
+same outcome here because `enabled` is the only field either layer sets, but
+the merge is per-field: a global field with no project counterpart would
+survive untouched.
+
 `sessionAutoName.enabled` makes one extra short LLM call per session (once, after the first turn) to title it; `false` (default) makes no model calls. `rules` appends house conventions to the naming prompt (later rules win when they conflict with the built-ins). Literal, case-insensitive `deny` phrases are stripped from every name; whitespace inside a phrase is loose, so `"acme corp"` also catches `AcmeCorp`. `revisitFirstTurn` re-evaluates the name once that many model round trips have completed, while `revisitEveryTurns` does so at every multiple; both default to `0` (off) because each revisit costs another short LLM call. For example, `10` and `100` mark round trips 10, 100, 200, 300. Revisits only run when the agent has fully settled (idle, nothing queued) - an automated multi-turn run such as a subagent chain is never renamed or delayed mid-flight; cadence points it crossed fire once, at the settle. A machine-generated name is replaced when stale. A name set by a human is never overwritten: the extension strongly prefers it, and announces a suggestion only when the work has clearly moved on. Counts come from the persisted transcript, so they survive resume.
 
 `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.
 
-Recommended explicit retry and watchdog settings:
+Recommended explicit retry and watchdog settings - `providerStallWatchdog`
+nests under `quiver`, while pi-core's own `retry` stays flat beside it (it is
+not a pi-quiver setting and is never nested):
 
 ```json
 {
+  "quiver": {
+    "providerStallWatchdog": {
+      "enabled": true,
+      "firstEventMs": 20000,
+      "warningMs": 120000,
+      "recoveryMs": 240000,
+      "maxStallRetries": 3
+    }
+  },
   "retry": {
     "enabled": true,
     "maxRetries": 3,
     "baseDelayMs": 2000
-  },
-  "providerStallWatchdog": {
-    "enabled": true,
-    "firstEventMs": 20000,
-    "warningMs": 120000,
-    "recoveryMs": 240000,
-    "maxStallRetries": 3
   }
 }
 ```
@@ -205,6 +231,30 @@ Operational notes:
 - **A watchdog abort that the provider ignores escalates after a fixed 10s.** Any post-abort stream event re-arms that deadline (bytes prove only that the connection was alive at that instant), so a stream that emits a straggler and then wedges still escalates 10s after its last event. This reduces the hang; it cannot force the provider to stop, and undici's timeouts remain the final backstop.
 - **Headless runs report on stderr.** In `print`/`json` mode pi binds a no-op UI, so watchdog notices go out via `console.warn`. Nothing is ever written to stdout, which `json` mode uses for its protocol. In TUI and RPC the notices render as main-window notifications, not the bottom status line.
 
+### Migrating from flat keys
+
+The flat top-level form (`"fastMode": ...` etc. directly under `settings.json`)
+is the outdated configuration style. It is legacy-frozen to exactly the four
+keys above - `fastMode`, `sessionAutoName`, `swordHeader`,
+`providerStallWatchdog` - and will never gain a fifth. To migrate, wrap your
+existing keys under `"quiver": { ... }` and delete the flat copies:
+
+```jsonc
+// before
+{ "fastMode": true }
+
+// after
+{ "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.
+
 ## Claude Code support
 
 `fetch`'s core (`lib/fetch-core.ts`) is also published as a CLI, so Claude Code can use the same routing, size gate, and spill behavior as pi's native tool - without pi ever seeing Claude-only files.

package/extensions/fast-mode.ts

@@ -116,7 +116,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).enabled;
+		const config = resolveConfig(ctx.cwd, "fastMode", DEFAULT_CONFIG, coerce, (m) => ctx.ui.notify(m, "warning")).enabled;
 		enabled = resolveEnabled({ config, flag: readFlag(), live: liveOverride });
 		return enabled;
 	};

package/extensions/provider-stall-watchdog.ts

@@ -91,8 +91,8 @@ export function resolveRetryMaxRetries(cwd: string): number {
 	return maxRetries;
 }
 
-export function resolveWatchdogConfig(cwd: string): ConfigValidation {
-	const candidate = resolveConfig(cwd, "providerStallWatchdog", DEFAULT_CANDIDATE, coerce);
+export function resolveWatchdogConfig(cwd: string, warn?: (msg: string) => void): ConfigValidation {
+	const candidate = resolveConfig(cwd, "providerStallWatchdog", DEFAULT_CANDIDATE, coerce, warn);
 	if (candidate.blockIsObject === true && candidate.maxStallRetries === undefined) {
 		candidate.maxStallRetries = resolveRetryMaxRetries(cwd);
 	}
@@ -278,7 +278,7 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 			ui = ctx.ui;
 			hasUI = ctx.hasUI;
 			if (!config) {
-				const resolved = resolveWatchdogConfig(ctx.cwd);
+				const resolved = resolveWatchdogConfig(ctx.cwd, (m) => announce(m, "warning"));
 				if (!resolved.ok) {
 					disabled = true;
 					announce(`providerStallWatchdog disabled: ${resolved.error}`, "warning");

package/extensions/session-name.ts

@@ -96,7 +96,7 @@ export function coerce(raw: unknown): Partial<Config> | undefined {
 }
 
 function loadConfig(ctx: ExtensionContext): Config {
-	return resolveConfig(ctx.cwd, "sessionAutoName", DEFAULT_CONFIG, coerce);
+	return resolveConfig(ctx.cwd, "sessionAutoName", DEFAULT_CONFIG, coerce, (m) => ctx.ui.notify(m, "warning"));
 }
 
 type ContentBlock = { type?: string; text?: string };

package/extensions/sword-header.ts

@@ -66,7 +66,7 @@ function renderSwordLines(theme: Theme): string[] {
 export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
 		if (ctx.mode !== "tui") return;
-		const cfg = resolveConfig(ctx.cwd, "swordHeader", DEFAULT_CONFIG, coerce);
+		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[] {

package/lib/extension-config.ts

@@ -11,6 +11,10 @@
  * correct when these extensions are consumed as a git-tag-pinned package -
  * unlike deriving the path from `import.meta.url`, which only held while an
  * extension lived inside `<agentHome>/extensions/`.
+ *
+ * Within each layer, a nested `quiver.<key>` takes precedence over the flat
+ * `<key>` by presence alone (even when malformed); the flat top-level
+ * fallback is frozen to the pre-quiver LEGACY_FLAT_KEYS and never extended.
  */
 
 import { readFileSync } from "node:fs";
@@ -29,21 +33,60 @@ export function settingsPaths(cwd: string): string[] {
 	return [join(getAgentDir(), "settings.json"), join(cwd, ".pi", "settings.json")];
 }
 
+/** Flat top-level fallback is frozen to these pre-quiver keys; never extend. */
+const LEGACY_FLAT_KEYS = new Set(["fastMode", "sessionAutoName", "swordHeader", "providerStallWatchdog"]);
+
+const emittedWarnings = new Set<string>();
+
+function emitWarning(warn: ((message: string) => void) | undefined, message: string): void {
+	if (!warn || emittedWarnings.has(message)) return;
+	emittedWarnings.add(message);
+	warn(message);
+}
+
 /**
- * Resolve a single extension config key across the settings layers. `coerce`
- * validates each layer's raw value into a partial patch (or `undefined` to
+ * 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.
  */
 export function resolveConfig<T extends object>(
 	cwd: string,
 	key: string,
 	defaults: T,
 	coerce: (raw: unknown) => Partial<T> | undefined,
+	warn?: (message: string) => void,
 ): T {
 	const cfg: T = { ...defaults };
+	let nestedSeen = false;
+	let flatSeen = false;
 	for (const path of settingsPaths(cwd)) {
-		const patch = coerce(readSettings(path)?.[key]);
+		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 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".`,
+		);
 	}
 	return cfg;
 }

package/package.json

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