gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/dist/resources/extensions/bg-shell/overlay.ts

@@ -125,6 +125,10 @@ export class BgManagerOverlay {
 				restartProcess(proc.id).then(() => {
 					this.invalidate();
 					this.tui.requestRender();
+				}).catch((err) => {
+					if (process.env.GSD_DEBUG) console.error('[bg-shell] restart failed:', err);
+					this.invalidate();
+					this.tui.requestRender();
 				});
 			}
 			return;

package/dist/resources/extensions/bg-shell/process-manager.ts

@@ -375,6 +375,19 @@ export function cleanupAll(): void {
 	processes.clear();
 }
 
+/**
+ * Kill all alive, non-persistent bg processes.
+ * Called between auto-mode units to prevent orphaned servers from
+ * keeping ports bound across task boundaries (#1209).
+ */
+export function killSessionProcesses(): void {
+	for (const [id, bg] of processes) {
+		if (bg.alive && !bg.persistAcrossSessions) {
+			killProcess(id, "SIGTERM");
+		}
+	}
+}
+
 async function waitForProcessExit(bg: BgProcess, timeoutMs: number): Promise<boolean> {
 	if (!bg.alive) return true;
 	await new Promise<void>((resolve) => {

package/dist/resources/extensions/bg-shell/utilities.ts

@@ -34,26 +34,14 @@ export function restoreWindowsVTInput(): void {
 
 // ── Time Formatting ────────────────────────────────────────────────────────
 
-export function formatUptime(ms: number): string {
-	const seconds = Math.floor(ms / 1000);
-	if (seconds < 60) return `${seconds}s`;
-	const minutes = Math.floor(seconds / 60);
-	if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
-	const hours = Math.floor(minutes / 60);
-	return `${hours}h ${minutes % 60}m`;
-}
+import { formatDuration } from "../shared/mod.js";
+
+export const formatUptime = formatDuration;
 
 export function formatTimeAgo(timestamp: number): string {
-	return formatUptime(Date.now() - timestamp) + " ago";
+	return formatDuration(Date.now() - timestamp) + " ago";
 }
 
-export function formatTokenCount(count: number): string {
-	if (count < 1000) return count.toString();
-	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
-	if (count < 1000000) return `${Math.round(count / 1000)}k`;
-	if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
-	return `${Math.round(count / 1000000)}M`;
-}
 
 export function resolveBgShellPersistenceCwd(
 	cachedCwd: string,

package/dist/resources/extensions/browser-tools/capture.ts

@@ -13,8 +13,40 @@ import { formatCompactStateSummary } from "./utils.js";
 // Anthropic vision: 1568px is the recommended optimal width. Height is capped
 // generously at 8000px so tall full-page screenshots remain readable rather
 // than being squished into a square constraint.
-const MAX_SCREENSHOT_WIDTH = 1568;
-const MAX_SCREENSHOT_HEIGHT = 8000;
+//
+// Override via environment variables:
+//   SCREENSHOT_MAX_WIDTH=0   → uncap width (use raw resolution)
+//   SCREENSHOT_MAX_HEIGHT=0  → uncap height
+//   SCREENSHOT_FORMAT=png    → lossless PNG for all viewport/fullpage screenshots
+//   SCREENSHOT_QUALITY=100   → max JPEG quality (1-100, default 80)
+const MAX_SCREENSHOT_WIDTH = parseScreenshotDimension(process.env.SCREENSHOT_MAX_WIDTH, 1568);
+const MAX_SCREENSHOT_HEIGHT = parseScreenshotDimension(process.env.SCREENSHOT_MAX_HEIGHT, 8000);
+
+/** Parse a dimension env var: positive int = that value, 0 = Infinity (uncapped), absent/invalid = default. */
+function parseScreenshotDimension(value: string | undefined, fallback: number): number {
+	if (value === undefined || value === "") return fallback;
+	const n = parseInt(value, 10);
+	if (isNaN(n) || n < 0) return fallback;
+	if (n === 0) return Infinity;
+	return n;
+}
+
+/** Return the user-configured screenshot format override, or null for default behavior. */
+export function getScreenshotFormatOverride(): "png" | "jpeg" | null {
+	const fmt = process.env.SCREENSHOT_FORMAT?.toLowerCase();
+	if (fmt === "png") return "png";
+	if (fmt === "jpeg" || fmt === "jpg") return "jpeg";
+	return null;
+}
+
+/** Return the user-configured default JPEG quality, or the provided fallback. */
+export function getScreenshotQualityDefault(fallback: number): number {
+	const q = process.env.SCREENSHOT_QUALITY;
+	if (q === undefined || q === "") return fallback;
+	const n = parseInt(q, 10);
+	if (isNaN(n) || n < 1 || n > 100) return fallback;
+	return n;
+}
 
 // ---------------------------------------------------------------------------
 // Compact page state capture

package/dist/resources/extensions/browser-tools/lifecycle.ts

@@ -103,10 +103,10 @@ export function attachPageListeners(p: Page, pageId: number): void {
 				try {
 					const body = await response.text();
 					entry.responseBody = body.slice(0, 2000);
-				} catch {}
+				} catch { /* non-fatal — response body may be unavailable or already consumed */ }
 			}
 			logPusher(networkLogs, entry);
-		} catch {}
+		} catch { /* non-fatal — request may have been aborted or page closed */ }
 	});
 
 	p.on("requestfailed", (request) => {
@@ -137,7 +137,7 @@ export function attachPageListeners(p: Page, pageId: number): void {
 			pageId,
 		});
 		// Auto-accept all dialogs to prevent page freezes
-		await dialog.accept().catch(() => {});
+		await dialog.accept().catch(() => { /* cleanup — dialog may already be dismissed */ });
 	});
 
 	// Frame detach handler — clears activeFrame if the selected frame detaches
@@ -236,7 +236,7 @@ export async function ensureBrowser(): Promise<{ browser: Browser; context: Brow
 		newPage.waitForLoadState("domcontentloaded", { timeout: 5000 })
 			.then(() => newPage.title())
 			.then((title) => { entry.title = title; })
-			.catch(() => {});
+			.catch(() => { /* best-effort title fetch — page may have closed or navigated away */ });
 	});
 
 	return { browser, context, page: getActivePage() };
@@ -264,7 +264,7 @@ export function getActivePageOrNull(): Page | null {
 export async function closeBrowser(): Promise<void> {
 	const browser = getBrowser();
 	if (browser) {
-		await browser.close().catch(() => {});
+		await browser.close().catch(() => { /* cleanup — browser may already be closed */ });
 	}
 	resetAllState();
 }

package/dist/resources/extensions/browser-tools/settle.ts

@@ -126,7 +126,7 @@ export async function settleAfterActionAdaptive(
 	// Install mutation counter + read initial state in one evaluate sequence.
 	// ensureMutationCounter must run first (installs the observer), then we
 	// read the baseline via the combined reader.
-	await ensureMutationCounter(p).catch(() => {});
+	await ensureMutationCounter(p).catch((e) => { if (process.env.GSD_DEBUG) console.error("[browser-tools] ensureMutationCounter failed:", e.message); });
 	const initial = await readSettleState(p, checkFocus);
 	let previousMutationCount = initial.mutationCount;
 	let previousFocus = initial.focusDescriptor;

package/dist/resources/extensions/browser-tools/state.ts

@@ -139,16 +139,16 @@ export interface ClickTargetStateSnapshot {
 	open: boolean | null;
 }
 
-export interface VerificationCheck {
+export interface BrowserVerificationCheck {
 	name: string;
 	passed: boolean;
 	value?: unknown;
 	expected?: unknown;
 }
 
-export interface VerificationResult {
+export interface BrowserVerificationResult {
 	verified: boolean;
-	checks: VerificationCheck[];
+	checks: BrowserVerificationCheck[];
 	verificationSummary: string;
 	retryHint?: string;
 }
@@ -379,8 +379,8 @@ export interface ToolDeps {
 
 	// Utilities (forwarded from utils.ts)
 	truncateText: (text: string) => string;
-	verificationFromChecks: (checks: VerificationCheck[], retryHint?: string) => VerificationResult;
-	verificationLine: (verification: VerificationResult) => string;
+	verificationFromChecks: (checks: BrowserVerificationCheck[], retryHint?: string) => BrowserVerificationResult;
+	verificationLine: (verification: BrowserVerificationResult) => string;
 	collectAssertionState: (
 		p: Page,
 		checks: BrowserAssertionCheckInput[],

package/dist/resources/extensions/browser-tools/tests/browser-tools-integration.test.mjs

@@ -92,7 +92,7 @@ let page;
 
 before(async () => {
   browser = await chromium.launch({ headless: true });
-  const context = await browser.newContext({ viewport: { width: 1280, height: 720 } });
+  const context = await browser.newContext({ viewport: { width: 1280, height: 800 }, deviceScaleFactor: 2 });
   page = await context.newPage();
 });
 

package/dist/resources/extensions/browser-tools/tests/browser-tools-unit.test.cjs

@@ -602,14 +602,14 @@ describe("constrainScreenshot", () => {
 	});
 
 	it("handles an image where only height exceeds the limit", async () => {
-		const buf = await createTestJpeg(1000, 2000);
+		const buf = await createTestJpeg(1000, 9000);
 		const result = await constrainScreenshot(null, buf, "image/jpeg", 80);
 		const sharp = require("sharp");
 		const meta = await sharp(result).metadata();
 		assert.ok(meta.width <= 1568);
-		assert.ok(meta.height <= 1568);
+		assert.ok(meta.height <= 8000);
 		// Height was the constraining dimension
-		assert.equal(meta.height, 1568);
+		assert.equal(meta.height, 8000);
 	});
 });
 

package/dist/resources/extensions/browser-tools/tools/assertions.ts

@@ -175,7 +175,7 @@ export function registerAssertionTools(pi: ExtensionAPI, deps: ToolDeps): void {
 						switch (step.action) {
 							case "navigate": {
 								await p.goto(step.url, { waitUntil: "domcontentloaded", timeout: 30000 });
-								await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+								await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => { /* networkidle timeout — non-fatal, page may still be usable */ });
 								return { ok: true, action: step.action, url: p.url() };
 							}
 							case "click": {

package/dist/resources/extensions/browser-tools/tools/device.ts

@@ -134,7 +134,7 @@ export function registerDeviceTools(pi: ExtensionAPI, deps: ToolDeps): void {
 
 				// Navigate back to previous URL if it wasn't about:blank
 				if (currentUrl && currentUrl !== "about:blank") {
-					await page.goto(currentUrl, { waitUntil: "domcontentloaded", timeout: 15000 }).catch(() => {});
+					await page.goto(currentUrl, { waitUntil: "domcontentloaded", timeout: 15000 }).catch((e) => { if (process.env.GSD_DEBUG) console.error("[browser-tools] device goto restore failed:", e.message); });
 				}
 
 				const viewport = deviceDescriptor.viewport;

package/dist/resources/extensions/browser-tools/tools/extract.ts

@@ -39,7 +39,7 @@ export function registerExtractTools(pi: ExtensionAPI, deps: ToolDeps): void {
 				const { page: p } = await deps.ensureBrowser();
 
 				// Wait for network idle before extraction
-				await p.waitForLoadState("networkidle", { timeout: 10000 }).catch(() => {});
+				await p.waitForLoadState("networkidle", { timeout: 10000 }).catch(() => { /* networkidle timeout — non-fatal, page may still be usable */ });
 
 				const schema = params.schema as any;
 				const scopeSelector = params.selector;

package/dist/resources/extensions/browser-tools/tools/navigation.ts

@@ -31,7 +31,7 @@ export function registerNavigationTools(pi: ExtensionAPI, deps: ToolDeps): void
 				beforeState = await deps.captureCompactPageState(p, { includeBodyText: true });
 				actionId = deps.beginTrackedAction("browser_navigate", params, beforeState.url).id;
 				await p.goto(params.url, { waitUntil: "domcontentloaded", timeout: 30000 });
-				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => { /* networkidle timeout — non-fatal, page may still be usable */ });
 				await new Promise(resolve => setTimeout(resolve, 300));
 
 				const title = await p.title();
@@ -60,7 +60,7 @@ export function registerNavigationTools(pi: ExtensionAPI, deps: ToolDeps): void
 						let buf = await p.screenshot({ type: "jpeg", quality: 80, scale: "css" });
 						buf = await deps.constrainScreenshot(p, buf, "image/jpeg", 80);
 						screenshotContent = [{ type: "image", data: buf.toString("base64"), mimeType: "image/jpeg" }];
-					} catch {}
+					} catch { /* non-fatal — screenshot is optional, navigation result is still valid */ }
 				}
 
 				return {
@@ -110,7 +110,7 @@ export function registerNavigationTools(pi: ExtensionAPI, deps: ToolDeps): void
 					};
 				}
 
-				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => { /* networkidle timeout — non-fatal, page may still be usable */ });
 
 				const title = await p.title();
 				const url = p.url();
@@ -154,7 +154,7 @@ export function registerNavigationTools(pi: ExtensionAPI, deps: ToolDeps): void
 					};
 				}
 
-				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => { /* networkidle timeout — non-fatal, page may still be usable */ });
 
 				const title = await p.title();
 				const url = p.url();
@@ -189,7 +189,7 @@ export function registerNavigationTools(pi: ExtensionAPI, deps: ToolDeps): void
 			try {
 				const { page: p } = await deps.ensureBrowser();
 				await p.reload({ waitUntil: "domcontentloaded", timeout: 30000 });
-				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => { /* networkidle timeout — non-fatal, page may still be usable */ });
 
 				const title = await p.title();
 				const url = p.url();
@@ -207,7 +207,7 @@ export function registerNavigationTools(pi: ExtensionAPI, deps: ToolDeps): void
 						data: buf.toString("base64"),
 						mimeType: "image/jpeg",
 					}];
-				} catch {}
+				} catch { /* non-fatal — screenshot is optional, reload result is still valid */ }
 
 				return {
 					content: [

package/dist/resources/extensions/browser-tools/tools/network-mock.ts

@@ -161,7 +161,7 @@ export function registerNetworkMockTools(pi: ExtensionAPI, deps: ToolDeps): void
 					const cleanup = async () => {
 						try {
 							await p.unroute(pattern, handler);
-						} catch {}
+						} catch { /* cleanup — route may already be removed or page closed */ }
 					};
 
 					const routeInfo: ActiveRoute = {

package/dist/resources/extensions/browser-tools/tools/pages.ts

@@ -137,7 +137,7 @@ export function registerPageTools(pi: ExtensionAPI, deps: ToolDeps): void {
 					try {
 						remaining.title = await remaining.page.title();
 						remaining.url = remaining.page.url();
-					} catch {}
+					} catch { /* non-fatal — page may have been closed or navigated away */ }
 				}
 				const pages = registryListPages(pageRegistry);
 				const lines = pages.map((p: any) => {

package/dist/resources/extensions/browser-tools/tools/screenshot.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { ToolDeps } from "../state.js";
+import { getScreenshotFormatOverride, getScreenshotQualityDefault } from "../capture.js";
 
 export function registerScreenshotTools(pi: ExtensionAPI, deps: ToolDeps): void {
 	pi.registerTool({
@@ -32,20 +33,37 @@ export function registerScreenshotTools(pi: ExtensionAPI, deps: ToolDeps): void
 
 				let screenshotBuffer: Buffer;
 				let mimeType: string;
-				const quality = params.quality ?? 80;
+				const formatOverride = getScreenshotFormatOverride();
+				const quality = params.quality ?? getScreenshotQualityDefault(80);
 
 				if (params.selector) {
+					const fmt = formatOverride ?? "png";
 					const locator = p.locator(params.selector).first();
-					screenshotBuffer = await locator.screenshot({ type: "png", scale: "css" });
-					mimeType = "image/png";
+					if (fmt === "jpeg") {
+						screenshotBuffer = await locator.screenshot({ type: "jpeg", quality, scale: "css" });
+						mimeType = "image/jpeg";
+					} else {
+						screenshotBuffer = await locator.screenshot({ type: "png", scale: "css" });
+						mimeType = "image/png";
+					}
 				} else {
-					screenshotBuffer = await p.screenshot({
-						fullPage: params.fullPage ?? false,
-						type: "jpeg",
-						quality,
-						scale: "css",
-					});
-					mimeType = "image/jpeg";
+					const fmt = formatOverride ?? "jpeg";
+					if (fmt === "png") {
+						screenshotBuffer = await p.screenshot({
+							fullPage: params.fullPage ?? false,
+							type: "png",
+							scale: "css",
+						});
+						mimeType = "image/png";
+					} else {
+						screenshotBuffer = await p.screenshot({
+							fullPage: params.fullPage ?? false,
+							type: "jpeg",
+							quality,
+							scale: "css",
+						});
+						mimeType = "image/jpeg";
+					}
 				}
 
 				screenshotBuffer = await deps.constrainScreenshot(p, screenshotBuffer, mimeType, quality);

package/dist/resources/extensions/browser-tools/tools/state-persistence.ts

@@ -69,7 +69,7 @@ export function registerStatePersistenceTools(pi: ExtensionAPI, deps: ToolDeps):
 
 				// Ensure .gitignore covers the state dir
 				const gitignorePath = path.resolve(process.cwd(), STATE_DIR, ".gitignore");
-				await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => {});
+				await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => { /* best-effort — .gitignore may already exist or dir may be read-only */ });
 
 				const cookieCount = storageState.cookies?.length ?? 0;
 				const localStorageOrigins = storageState.origins?.length ?? 0;

package/dist/resources/extensions/browser-tools/tools/visual-diff.ts

@@ -55,7 +55,7 @@ export function registerVisualDiffTools(pi: ExtensionAPI, deps: ToolDeps): void
 
 				// Ensure .gitignore
 				const gitignorePath = pathMod.join(baselineDir, ".gitignore");
-				await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => {});
+				await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => { /* best-effort — .gitignore may already exist or dir may be read-only */ });
 
 				// Generate baseline name
 				const url = p.url();

package/dist/resources/extensions/browser-tools/utils.ts

@@ -44,8 +44,8 @@ import {
 	type CompactPageState,
 	type CompactSelectorState,
 	type ClickTargetStateSnapshot,
-	type VerificationCheck,
-	type VerificationResult,
+	type BrowserVerificationCheck,
+	type BrowserVerificationResult,
 	type BrowserAssertionCheckInput,
 	type AdaptiveSettleOptions,
 	type AdaptiveSettleDetails,
@@ -265,9 +265,9 @@ export function getPendingCriticalRequests(p: Page): number {
 // ---------------------------------------------------------------------------
 
 export function verificationFromChecks(
-	checks: VerificationCheck[],
+	checks: BrowserVerificationCheck[],
 	retryHint?: string,
-): VerificationResult {
+): BrowserVerificationResult {
 	const passedChecks = checks
 		.filter((check) => check.passed)
 		.map((check) => check.name);
@@ -282,7 +282,7 @@ export function verificationFromChecks(
 	};
 }
 
-export function verificationLine(verification: VerificationResult): string {
+export function verificationLine(verification: BrowserVerificationResult): string {
 	return `Verification: ${verification.verificationSummary}`;
 }
 

package/dist/resources/extensions/get-secrets-from-user.ts

@@ -13,7 +13,7 @@ import { resolve } from "node:path";
 import type { ExtensionAPI, Theme } from "@gsd/pi-coding-agent";
 import { CURSOR_MARKER, Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth, wrapTextWithAnsi } from "@gsd/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { makeUI, type ProgressStatus } from "./shared/ui.js";
+import { makeUI, type ProgressStatus } from "./shared/mod.js";
 import { parseSecretsManifest, formatSecretsManifest } from "./gsd/files.js";
 import { resolveMilestoneFile } from "./gsd/paths.js";
 import type { SecretsManifestEntry } from "./gsd/types.js";

package/dist/resources/extensions/google-search/index.ts

@@ -265,14 +265,27 @@ export default function (pi: ExtensionAPI) {
 			try {
 				if (process.env.GEMINI_API_KEY) {
 					const ai = await getClient();
-					const response = await ai.models.generateContent({
-						model: process.env.GEMINI_SEARCH_MODEL || "gemini-2.5-flash",
-						contents: params.query,
-						config: {
-							tools: [{ googleSearch: {} }],
-							abortSignal: signal,
-						},
-					});
+
+					// Add a 30-second timeout to prevent hanging (#1100)
+					const timeoutController = new AbortController();
+					const timeoutId = setTimeout(() => timeoutController.abort(), 30_000);
+					const combinedSignal = signal
+						? AbortSignal.any([signal, timeoutController.signal])
+						: timeoutController.signal;
+
+					let response;
+					try {
+						response = await ai.models.generateContent({
+							model: process.env.GEMINI_SEARCH_MODEL || "gemini-2.5-flash",
+							contents: params.query,
+							config: {
+								tools: [{ googleSearch: {} }],
+								abortSignal: combinedSignal,
+							},
+						});
+					} finally {
+						clearTimeout(timeoutId);
+					}
 
 					// Extract answer text
 					const answer = response.text ?? "";

package/dist/resources/extensions/gsd/activity-log.ts

@@ -11,6 +11,7 @@
 import { writeFileSync, writeSync, mkdirSync, readdirSync, unlinkSync, statSync, openSync, closeSync, constants } from "node:fs";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
+import { GSDError, GSD_IO_ERROR } from "./errors.js";
 
 const SEQ_PREFIX_RE = /^(\d+)-/;
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
@@ -95,7 +96,7 @@ function nextActivityFilePath(
     }
   }
   // Fallback: should never reach here in practice
-  throw new Error(`Failed to find available activity log sequence in ${activityDir}`);
+  throw new GSDError(GSD_IO_ERROR, `Failed to find available activity log sequence in ${activityDir}`);
 }
 
 export function saveActivityLog(

package/dist/resources/extensions/gsd/atomic-write.ts

@@ -0,0 +1,35 @@
+import { writeFileSync, renameSync, unlinkSync, mkdirSync, promises as fs } from "node:fs"
+import { dirname } from "node:path"
+import { randomBytes } from "node:crypto"
+
+/**
+ * Atomically writes content to a file by writing to a temp file first,
+ * then renaming. Prevents partial/corrupt files on crash.
+ */
+export function atomicWriteSync(filePath: string, content: string, encoding: BufferEncoding = "utf-8"): void {
+  mkdirSync(dirname(filePath), { recursive: true })
+  const tmpPath = filePath + `.tmp.${randomBytes(4).toString("hex")}`
+  writeFileSync(tmpPath, content, encoding)
+  try {
+    renameSync(tmpPath, filePath)
+  } catch (err) {
+    try { unlinkSync(tmpPath) } catch { /* orphan cleanup best-effort */ }
+    throw err
+  }
+}
+
+/**
+ * Async variant of atomicWriteSync. Atomically writes content to a file
+ * by writing to a temp file first, then renaming.
+ */
+export async function atomicWriteAsync(filePath: string, content: string, encoding: BufferEncoding = "utf-8"): Promise<void> {
+  await fs.mkdir(dirname(filePath), { recursive: true })
+  const tmpPath = filePath + `.tmp.${randomBytes(4).toString("hex")}`
+  await fs.writeFile(tmpPath, content, encoding)
+  try {
+    await fs.rename(tmpPath, filePath)
+  } catch (err) {
+    await fs.unlink(tmpPath).catch(() => { /* orphan cleanup best-effort */ })
+    throw err
+  }
+}

package/dist/resources/extensions/gsd/auto/session.ts

@@ -8,6 +8,12 @@
  * - toJSON() provides diagnostic snapshots
  * - grep `s.` shows every state access
  * - Constructable for testing
+ *
+ * MAINTENANCE RULE: All new mutable auto-mode state MUST be added here as a
+ * class property, not as a module-level variable in auto.ts. If the state
+ * needs clearing on stop, add it to reset(). Tests in
+ * auto-session-encapsulation.test.ts enforce that auto.ts has no module-level
+ * `let` or `var` declarations.
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
@@ -54,6 +60,8 @@ export const MAX_LIFETIME_DISPATCHES = 6;
 export const MAX_CONSECUTIVE_SKIPS = 3;
 export const DISPATCH_GAP_TIMEOUT_MS = 5_000;
 export const MAX_SKIP_DEPTH = 20;
+export const NEW_SESSION_TIMEOUT_MS = 30_000;
+export const DISPATCH_HANG_TIMEOUT_MS = 60_000;
 
 // ─── AutoSession ─────────────────────────────────────────────────────────────
 
@@ -61,6 +69,7 @@ export class AutoSession {
   // ── Lifecycle ────────────────────────────────────────────────────────────
   active = false;
   paused = false;
+  pausedForSecrets = false;
   stepMode = false;
   verbose = false;
   cmdCtx: ExtensionCommandContext | null = null;
@@ -106,6 +115,7 @@ export class AutoSession {
 
   // ── Guards ───────────────────────────────────────────────────────────────
   handlingAgentEnd = false;
+  pendingAgentEndRetry = false;
   dispatching = false;
   skipDepth = 0;
   readonly recentlyEvictedKeys = new Set<string>();
@@ -153,6 +163,7 @@ export class AutoSession {
     // Lifecycle
     this.active = false;
     this.paused = false;
+    this.pausedForSecrets = false;
     this.stepMode = false;
     this.verbose = false;
     this.cmdCtx = null;
@@ -192,6 +203,7 @@ export class AutoSession {
 
     // Guards
     this.handlingAgentEnd = false;
+    this.pendingAgentEndRetry = false;
     this.dispatching = false;
     this.skipDepth = 0;
     this.recentlyEvictedKeys.clear();