pi-goal-x 0.30.1 → 0.30.3

package/README.md

@@ -2,6 +2,15 @@
   <img src="pi-goal-x.png" alt="pi-goal-x logo" width="560">
 </div>
 
+<div align="center">
+  <a href="https://pi.dev/packages" target="_blank" rel="noopener noreferrer">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="assets/badge-dark.svg">
+      <img src="assets/badge-light.svg" alt="TOP 1% of Pi coding agent packages: #45 of 5,380 by downloads, as of Aug 2026" width="420">
+    </picture>
+  </a>
+</div>
+
 # pi-goal-x
 
 `pi-goal-x` is a goal-management extension for [pi](https://github.com/earendil-works/pi-coding-agent).

package/extensions/goal-events.ts

@@ -533,14 +533,20 @@ export function registerGoalEvents(core: GoalCore): void {
 			return;
 		}
 		if (!networkErrorGoalId || !core.isActionableContinuationGoal(networkErrorGoalId)) return;
-		const plan = core.runtime.scheduleNetworkErrorRetry(ctx, core.state.goal!);
+		const recovery = loadGoalSettings(ctx.cwd).networkRecovery;
+		const policy = recovery
+			? { maxAttempts: recovery.maxAttempts, maxDelayMs: recovery.maxDelayMs }
+			: undefined;
+		const plan = core.runtime.scheduleNetworkErrorRetry(ctx, core.state.goal!, policy);
 		if (plan) {
+			const cap = plan.maxAttempts > 0 ? `/${plan.maxAttempts}` : ", unbounded";
 			ctx.ui.notify(
-				`Provider network error. Retrying the goal in ${Math.round(plan.delayMs / 1000)}s (recovery ${plan.attempt}/${plan.maxAttempts}).`,
+				`Provider network error. Retrying the goal in ${Math.round(plan.delayMs / 1000)}s (recovery ${plan.attempt}${cap}).`,
 				"warning",
 			);
 			return;
 		}
+		// Only reachable under a configured bounded cap (maxAttempts > 0).
 		ctx.ui.notify(
 			"Provider network errors persisted after all recovery attempts. The goal remains active; resume it when the provider is healthy.",
 			"warning",

package/extensions/goal-format.ts

@@ -226,14 +226,36 @@ export function isErrorAssistantMessage(message: unknown): boolean {
 	return raw?.role === "assistant" && raw.stopReason === "error";
 }
 
-/** A provider-declared network failure is safe for the bounded goal backoff. */
+/**
+ * Transient provider failures are safe for goal-level recovery backoff:
+ * Pi-declared network errors plus HTTP 5xx-style outages surfaced by
+ * providers (503 server_error, "Endpoint is unavailable", overloaded,
+ * gateway failures). Deliberately excludes 4xx client errors such as auth
+ * and malformed-request failures, which retrying cannot fix.
+ */
+const TRANSIENT_PROVIDER_ERROR_RE = new RegExp(
+	[
+		"\\bnetwork[_\\s-]?error\\b",
+		"\\bserver[_\\s]?error\\b",
+		"\\b(?:502|503|504|529)\\b",
+		"\\bservice unavailable\\b",
+		"\\bbad gateway\\b",
+		"\\bgateway timeout\\b",
+		"\\bupstream request failed\\b",
+		"\\bendpoint is unavailable\\b",
+		"\\boverloaded[_\\s]?error\\b",
+	].join("|"),
+	"i",
+);
+
+/** A transient provider failure is safe for the bounded goal backoff. */
 export function isNetworkErrorAssistantMessage(message: unknown): boolean {
 	if (!isErrorAssistantMessage(message)) return false;
 	const raw = asRecord(message);
 	const details = [raw?.rawStopReason, raw?.errorMessage]
 		.filter((value): value is string => typeof value === "string")
 		.join(" ");
-	return /\bnetwork[_\s-]?error\b/i.test(details);
+	return TRANSIENT_PROVIDER_ERROR_RE.test(details);
 }
 
 export function isToolUseAssistantMessage(message: unknown): boolean {

package/extensions/goal-runtime.ts

@@ -12,7 +12,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { GoalCheckpointDetailsV2, GoalRecord } from "./goal-record.ts";
 import { checkpointTriggerPrompt } from "./prompts/goal-prompts.ts";
 import { POST_STOP_ALLOWED_TOOLS } from "./goal-tool-names.ts";
-import { networkErrorBackoffPlan, type NetworkErrorBackoffPlan } from "./network-error-backoff.ts";
+import { networkErrorBackoffPlan, type NetworkErrorBackoffPlan, type NetworkErrorRecoveryPolicy } from "./network-error-backoff.ts";
 
 export const CONTINUATION_IDLE_RETRY_MS = 50;
 
@@ -111,13 +111,13 @@ export class GoalRuntime {
 	 * have failed. The counter stays in memory and is cleared on a successful
 	 * turn or any user-owned cancellation path.
 	 */
-	scheduleNetworkErrorRetry(ctx: ExtensionContext, goal: GoalRecord): NetworkErrorBackoffPlan | null {
+	scheduleNetworkErrorRetry(ctx: ExtensionContext, goal: GoalRecord, policy?: NetworkErrorRecoveryPolicy): NetworkErrorBackoffPlan | null {
 		if (goal.status !== "active" || !goal.autoContinue || this.networkErrorRetryTimer) return null;
 		if (this.networkErrorRetryGoalId !== goal.id) {
 			this.networkErrorRetryGoalId = goal.id;
 			this.networkErrorRetryAttempt = 0;
 		}
-		const plan = networkErrorBackoffPlan(this.networkErrorRetryAttempt + 1);
+		const plan = networkErrorBackoffPlan(this.networkErrorRetryAttempt + 1, policy);
 		if (!plan) return null;
 		this.networkErrorRetryAttempt = plan.attempt;
 		this.networkErrorRetryTimer = setTimeout(() => {

package/extensions/goal-settings.ts

@@ -62,6 +62,12 @@ export const DEFAULT_GOAL_KEYBINDINGS: GoalKeybindings = {
 	},
 };
 
+/**
+ * Default ceiling for a single recovery delay; the escalation ladder
+ * plateaus here. Configurable via networkRecovery.maxDelayMs.
+ */
+export const DEFAULT_NETWORK_RECOVERY_MAX_DELAY_MS = 80_000;
+
 export function formatGoalKeybinding(key: string): string {
 	return key.split("+").map((part) => ({
 		ctrl: "Ctrl",
@@ -108,6 +114,11 @@ export interface GoalSettingsResolvedShape {
 	hideUnfocusedBanner?: boolean;
 	/** Issue #26: opt-in read-only blocker Oracle configuration (sparse). */
 	oracle?: GoalOracleSettingsLayer;
+	/**
+	 * Goal-level provider-error recovery backoff (sparse). maxAttempts 0 or
+	 * unset = unbounded retry (default); maxDelayMs caps the delay plateau.
+	 */
+	networkRecovery?: GoalNetworkRecoverySettingsLayer;
 }
 
 // Resolved Oracle settings are attached to the resolved runtime shape below
@@ -126,7 +137,6 @@ export interface GoalOracleSettingsLayer {
 	maxFailedAttemptsPerBlocker?: number;
 }
 
-/** Resolved Oracle settings (concrete defaults). */
 export interface ResolvedGoalOracleSettings {
 	enabled: boolean;
 	provider?: string;
@@ -136,6 +146,18 @@ export interface ResolvedGoalOracleSettings {
 	maxFailedAttemptsPerBlocker: number;
 }
 
+/** Sparse per-leaf network-recovery settings (maxAttempts 0 = unbounded). */
+export interface GoalNetworkRecoverySettingsLayer {
+	maxAttempts?: number;
+	maxDelayMs?: number;
+}
+
+/** Resolved network-recovery settings (concrete defaults). */
+export interface ResolvedGoalNetworkRecoverySettings {
+	maxAttempts: number;
+	maxDelayMs: number;
+}
+
 /**
  * Sparse settings layer: exactly what a settings FILE may contain. Every
  * field optional; explicit false/0 preserved so lower layers can override
@@ -151,6 +173,8 @@ export interface GoalSettingsLayer extends GoalSettingsResolvedShape {}
 export interface ResolvedGoalSettingsShape extends GoalSettingsResolvedShape {
 	/** Issue #26: resolved opt-in blocker Oracle configuration. */
 	oracle?: ResolvedGoalOracleSettings;
+	/** Resolved goal-level provider-error recovery configuration. */
+	networkRecovery?: ResolvedGoalNetworkRecoverySettings;
 }
 
 export type ResolvedGoalSettings = ResolvedGoalSettingsShape;
@@ -306,8 +330,11 @@ const ALLOWED_SETTINGS_KEYS = new Set([
 	"keybindings",
 	"hideUnfocusedBanner",
 	"oracle",
+	"networkRecovery",
 ]);
 
+const ALLOWED_NETWORK_RECOVERY_KEYS = new Set(["maxAttempts", "maxDelayMs"]);
+
 const ALLOWED_ORACLE_KEYS = new Set([
 	"enabled",
 	"provider",
@@ -475,6 +502,31 @@ export function parseSettingsLayer(
 				layer.oracle = oracle;
 				break;
 			}
+			case "networkRecovery": {
+				if (!value || typeof value !== "object" || Array.isArray(value)) {
+					diagnostics.push(diagnostic("invalid_nested_key", "networkRecovery must be an object", key));
+					break;
+				}
+				const nrRecord = value as Record<string, unknown>;
+				const nr: GoalNetworkRecoverySettingsLayer = {};
+				for (const [nKey, nValue] of Object.entries(nrRecord)) {
+					if (!ALLOWED_NETWORK_RECOVERY_KEYS.has(nKey)) {
+						diagnostics.push(diagnostic("unknown_key", `unknown networkRecovery key: ${nKey}`, `networkRecovery.${nKey}`));
+						continue;
+					}
+					if (nKey === "maxAttempts") {
+						const parsed = asNonNegativeInt(nValue);
+						if (parsed === undefined) diagnostics.push(diagnostic("invalid_value", "networkRecovery.maxAttempts must be an integer >= 0 (0 = unbounded)", `networkRecovery.${nKey}`));
+						else nr.maxAttempts = parsed;
+					} else {
+						const parsed = asNonNegativeInt(nValue);
+						if (parsed === undefined || parsed < 1_000) diagnostics.push(diagnostic("invalid_value", "networkRecovery.maxDelayMs must be an integer >= 1000", `networkRecovery.${nKey}`));
+						else nr.maxDelayMs = parsed;
+					}
+				}
+				if (Object.keys(nr).length > 0) layer.networkRecovery = nr;
+				break;
+			}
 			default:
 				diagnostics.push(diagnostic("unknown_key", `unknown settings key: ${key}`, key));
 				break;
@@ -733,6 +785,20 @@ export function loadSettingsSnapshot(cwd: string, env: NodeJS.ProcessEnv = proce
 		defaultValue: 0,
 		envVar: "PI_GOAL_OBJECTIVE_MAX_CHARS",
 	}));
+	const networkRecoveryMaxAttempts = track("networkRecovery.maxAttempts", resolveLeaf<number>({
+		envValue: envInt("PI_GOAL_NETWORK_RECOVERY_MAX_ATTEMPTS"),
+		projectValue: project.layer.networkRecovery?.maxAttempts,
+		globalValue: global.layer.networkRecovery?.maxAttempts,
+		defaultValue: 0,
+		envVar: "PI_GOAL_NETWORK_RECOVERY_MAX_ATTEMPTS",
+	}));
+	const networkRecoveryMaxDelayMs = track("networkRecovery.maxDelayMs", resolveLeaf<number>({
+		envValue: envInt("PI_GOAL_NETWORK_RECOVERY_MAX_DELAY_MS"),
+		projectValue: project.layer.networkRecovery?.maxDelayMs,
+		globalValue: global.layer.networkRecovery?.maxDelayMs,
+		defaultValue: DEFAULT_NETWORK_RECOVERY_MAX_DELAY_MS,
+		envVar: "PI_GOAL_NETWORK_RECOVERY_MAX_DELAY_MS",
+	}));
 
 	const keybindings: GoalKeybindings = {
 		dashboard: {
@@ -768,6 +834,10 @@ export function loadSettingsSnapshot(cwd: string, env: NodeJS.ProcessEnv = proce
 		stallTimeoutMinutes,
 		objectiveMaxChars,
 		keybindings,
+		networkRecovery: {
+			maxAttempts: networkRecoveryMaxAttempts,
+			maxDelayMs: networkRecoveryMaxDelayMs,
+		},
 		oracle: {
 			enabled: oracleEnabled,
 			...(oracleProvider ? { provider: oracleProvider } : {}),
@@ -1076,6 +1146,13 @@ function buildPersistedLayer(settings: GoalSettings): Record<string, unknown> {
 	if (settings.autoSelectSingleGoal !== undefined) persisted.autoSelectSingleGoal = settings.autoSelectSingleGoal;
 	if (settings.auditorProjectResources !== undefined) persisted.auditorProjectResources = settings.auditorProjectResources;
 	if (settings.hideUnfocusedBanner !== undefined) persisted.hideUnfocusedBanner = settings.hideUnfocusedBanner;
+	if ((settings as { networkRecovery?: ResolvedGoalNetworkRecoverySettings }).networkRecovery) {
+		const nr = (settings as { networkRecovery?: ResolvedGoalNetworkRecoverySettings }).networkRecovery!;
+		const o: Record<string, unknown> = {};
+		if (nr.maxAttempts !== undefined) o.maxAttempts = nr.maxAttempts;
+		if (nr.maxDelayMs !== undefined) o.maxDelayMs = nr.maxDelayMs;
+		if (Object.keys(o).length > 0) persisted.networkRecovery = o;
+	}
 	if ((settings as { oracle?: ResolvedGoalOracleSettings }).oracle) {
 		const o: Record<string, unknown> = {};
 		const so = (settings as { oracle?: ResolvedGoalOracleSettings }).oracle!;
@@ -1104,6 +1181,10 @@ export function envOverrideFor(key: keyof GoalSettings | "settingsFile", env: No
 	if (key === "disableTasks" && env.PI_GOAL_DISABLE_TASKS !== undefined) return "PI_GOAL_DISABLE_TASKS";
 	if (key === "disableContracts" && env.PI_GOAL_DISABLE_CONTRACTS !== undefined) return "PI_GOAL_DISABLE_CONTRACTS";
 	if (key === "objectiveMaxChars" && env.PI_GOAL_OBJECTIVE_MAX_CHARS !== undefined) return "PI_GOAL_OBJECTIVE_MAX_CHARS";
+	if (key === "networkRecovery") {
+		if (env.PI_GOAL_NETWORK_RECOVERY_MAX_ATTEMPTS !== undefined) return "PI_GOAL_NETWORK_RECOVERY_MAX_ATTEMPTS";
+		if (env.PI_GOAL_NETWORK_RECOVERY_MAX_DELAY_MS !== undefined) return "PI_GOAL_NETWORK_RECOVERY_MAX_DELAY_MS";
+	}
 	if (key === "settingsFile" && env[PI_GOAL_SETTINGS_FILE_ENV] !== undefined) return PI_GOAL_SETTINGS_FILE_ENV;
 	return null;
 }
@@ -1128,6 +1209,8 @@ export function effectiveSettingsReport(cwd: string, env: NodeJS.ProcessEnv = pr
 		{ key: "hideUnfocusedBanner", label: "hide unfocused banner", format: () => String(snapshot.value.hideUnfocusedBanner) },
 		{ key: "stallTimeoutMinutes", label: "stall timeout (minutes)", format: () => String(snapshot.value.stallTimeoutMinutes) },
 		{ key: "objectiveMaxChars", label: "max objective length (0 = none)", format: () => String(snapshot.value.objectiveMaxChars) },
+		{ key: "networkRecovery", label: "network recovery attempts (0 = unbounded)", format: () => String(snapshot.value.networkRecovery?.maxAttempts ?? 0) },
+		{ key: "networkRecovery", label: "network recovery max delay (ms)", format: () => String(snapshot.value.networkRecovery?.maxDelayMs ?? DEFAULT_NETWORK_RECOVERY_MAX_DELAY_MS) },
 		{ key: "keybindings", label: "dashboard keybindings", format: () => `${snapshot.value.keybindings!.dashboard.toggleExpand}, ${snapshot.value.keybindings!.dashboard.scrollUp}, ${snapshot.value.keybindings!.dashboard.scrollDown}` },
 	];
 	for (const row of rows) {

package/extensions/network-error-backoff.ts

@@ -1,25 +1,55 @@
 /**
- * Bounded, goal-level recovery after Pi has exhausted its provider retries.
+ * Goal-level recovery after Pi has exhausted its provider retries.
  *
  * Pi owns the immediate request retries. These longer delays are deliberately
- * small in number and only apply to terminal `network_error` failures, so an
- * unavailable provider never becomes an unbounded auto-continue loop.
+ * slow and only apply to transient provider failures, so an unavailable
+ * provider never becomes a rapid auto-continue loop.
+ *
+ * Default policy is UNBOUNDED: recovery keeps retrying forever on an
+ * escalating delay ladder that plateaus at `maxDelayMs`. A bounded cap can
+ * be configured via layered settings (`networkRecovery.maxAttempts`, where
+ * 0/unset means unbounded).
  */
 
 export const NETWORK_ERROR_BACKOFF_DELAYS_MS = [5_000, 10_000, 20_000, 40_000, 80_000] as const;
 
+/** Recovery policy: maxAttempts 0 = unbounded (default); delays plateau at maxDelayMs. */
+export interface NetworkErrorRecoveryPolicy {
+	maxAttempts: number;
+	maxDelayMs: number;
+}
+
+export const DEFAULT_NETWORK_ERROR_RECOVERY_POLICY: NetworkErrorRecoveryPolicy = {
+	maxAttempts: 0,
+	maxDelayMs: NETWORK_ERROR_BACKOFF_DELAYS_MS[NETWORK_ERROR_BACKOFF_DELAYS_MS.length - 1]!,
+};
+
 export interface NetworkErrorBackoffPlan {
 	attempt: number;
+	/** 0 = unbounded. */
 	maxAttempts: number;
 	delayMs: number;
 }
 
-/** Return the recovery plan for a one-based attempt, or undefined after the cap. */
-export function networkErrorBackoffPlan(attempt: number): NetworkErrorBackoffPlan | undefined {
-	if (!Number.isInteger(attempt) || attempt < 1 || attempt > NETWORK_ERROR_BACKOFF_DELAYS_MS.length) return undefined;
+function rawLadderDelay(attempt: number): number {
+	const last = NETWORK_ERROR_BACKOFF_DELAYS_MS.length - 1;
+	return NETWORK_ERROR_BACKOFF_DELAYS_MS[Math.min(attempt - 1, last)]!;
+}
+
+/**
+ * Return the recovery plan for a one-based attempt under the given policy,
+ * or undefined once a configured bounded cap is exhausted. With the default
+ * unbounded policy this never returns undefined.
+ */
+export function networkErrorBackoffPlan(
+	attempt: number,
+	policy: NetworkErrorRecoveryPolicy = DEFAULT_NETWORK_ERROR_RECOVERY_POLICY,
+): NetworkErrorBackoffPlan | undefined {
+	if (!Number.isInteger(attempt) || attempt < 1) return undefined;
+	if (policy.maxAttempts > 0 && attempt > policy.maxAttempts) return undefined;
 	return {
 		attempt,
-		maxAttempts: NETWORK_ERROR_BACKOFF_DELAYS_MS.length,
-		delayMs: NETWORK_ERROR_BACKOFF_DELAYS_MS[attempt - 1]!,
+		maxAttempts: policy.maxAttempts,
+		delayMs: Math.min(rawLadderDelay(attempt), policy.maxDelayMs),
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-x",
-  "version": "0.30.1",
+  "version": "0.30.3",
   "description": "Goal mode extension for pi: durable long-running objectives, five model tools, structured tasks, independent completion audit, Sisyphus mode, auto-continue, and a status overlay.",
   "license": "MIT",
   "author": "pi-goal-x contributors",