gsd-pi 2.38.0-dev.96dc7fb → 2.38.0-dev.add4f78

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -33,7 +33,6 @@ import { writeUnitRuntimeRecord, clearUnitRuntimeRecord } from "./unit-runtime.j
 import { runGSDDoctor, rebuildState, summarizeDoctorIssues } from "./doctor.js";
 import { recordHealthSnapshot, checkHealEscalation } from "./doctor-proactive.js";
 import { syncStateToProjectRoot } from "./auto-worktree-sync.js";
-import { resetRewriteCircuitBreaker } from "./auto-dispatch.js";
 import { isDbAvailable } from "./gsd-db.js";
 import { consumeSignal } from "./session-status-io.js";
 import {
@@ -56,6 +55,13 @@ import { join } from "node:path";
 /** Throttle STATE.md rebuilds — at most once per 30 seconds */
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 
+export interface PreVerificationOpts {
+  skipSettleDelay?: boolean;
+  skipDoctor?: boolean;
+  skipStateRebuild?: boolean;
+  skipWorktreeSync?: boolean;
+}
+
 export interface PostUnitContext {
   s: AutoSession;
   ctx: ExtensionContext;
@@ -73,7 +79,7 @@ export interface PostUnitContext {
  *
  * Returns "dispatched" if a signal caused stop/pause, "continue" to proceed.
  */
-export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"dispatched" | "continue"> {
+export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreVerificationOpts): Promise<"dispatched" | "continue"> {
   const { s, ctx, pi, buildSnapshotOpts, stopAuto, pauseAuto } = pctx;
 
   // ── Parallel worker signal check ──
@@ -95,8 +101,10 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
   // Invalidate all caches
   invalidateAllCaches();
 
-  // Small delay to let files settle
-  await new Promise(r => setTimeout(r, 500));
+  // Small delay to let files settle (skipped for sidecars where latency matters more)
+  if (!opts?.skipSettleDelay) {
+    await new Promise(r => setTimeout(r, 100));
+  }
 
   // Auto-commit
   if (s.currentUnit) {
@@ -120,8 +128,8 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
                   keyFiles: summary.frontmatter.key_files?.filter(f => !f.includes("{{")) || undefined,
                 };
               }
-            } catch {
-              // Non-fatal
+            } catch (e) {
+              debugLog("postUnit", { phase: "task-summary-parse", error: String(e) });
             }
           }
         }
@@ -131,12 +139,12 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
       if (commitMsg) {
         ctx.ui.notify(`Committed: ${commitMsg.split("\n")[0]}`, "info");
       }
-    } catch {
-      // Non-fatal
+    } catch (e) {
+      debugLog("postUnit", { phase: "auto-commit", error: String(e) });
     }
 
-    // Doctor: fix mechanical bookkeeping
-    try {
+    // Doctor: fix mechanical bookkeeping (skipped for lightweight sidecars)
+    if (!opts?.skipDoctor) try {
       const scopeParts = s.currentUnit.id.split("/").slice(0, 2);
       const doctorScope = scopeParts.join("/");
       const sliceTerminalUnits = new Set(["complete-slice", "run-uat"]);
@@ -168,24 +176,26 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
             const reportText = formatDoctorReport(report, { scope: doctorScope, includeWarnings: true });
             const structuredIssues = formatDoctorIssuesForPrompt(actionable);
             dispatchDoctorHeal(pi, doctorScope, reportText, structuredIssues);
-          } catch {
-            // Non-fatal
+          } catch (e) {
+            debugLog("postUnit", { phase: "doctor-heal-dispatch", error: String(e) });
           }
         }
       }
-    } catch {
-      // Non-fatal
+    } catch (e) {
+      debugLog("postUnit", { phase: "doctor", error: String(e) });
     }
 
-    // Throttled STATE.md rebuild
-    const now = Date.now();
-    if (now - s.lastStateRebuildAt >= STATE_REBUILD_MIN_INTERVAL_MS) {
-      try {
-        await rebuildState(s.basePath);
-        s.lastStateRebuildAt = now;
-        autoCommitCurrentBranch(s.basePath, "state-rebuild", s.currentUnit.id);
-      } catch {
-        // Non-fatal
+    // Throttled STATE.md rebuild (skipped for lightweight sidecars)
+    if (!opts?.skipStateRebuild) {
+      const now = Date.now();
+      if (now - s.lastStateRebuildAt >= STATE_REBUILD_MIN_INTERVAL_MS) {
+        try {
+          await rebuildState(s.basePath);
+          s.lastStateRebuildAt = now;
+          autoCommitCurrentBranch(s.basePath, "state-rebuild", s.currentUnit.id);
+        } catch (e) {
+          debugLog("postUnit", { phase: "state-rebuild", error: String(e) });
+        }
       }
     }
 
@@ -193,16 +203,16 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
     try {
       const { pruneDeadProcesses } = await import("../bg-shell/process-manager.js");
       pruneDeadProcesses();
-    } catch {
-      // Non-fatal
+    } catch (e) {
+      debugLog("postUnit", { phase: "prune-bg-shell", error: String(e) });
     }
 
-    // Sync worktree state back to project root
-    if (s.originalBasePath && s.originalBasePath !== s.basePath) {
+    // Sync worktree state back to project root (skipped for lightweight sidecars)
+    if (!opts?.skipWorktreeSync && s.originalBasePath && s.originalBasePath !== s.basePath) {
       try {
         syncStateToProjectRoot(s.basePath, s.originalBasePath, s.currentMilestoneId);
-      } catch {
-        // Non-fatal
+      } catch (e) {
+        debugLog("postUnit", { phase: "worktree-sync", error: String(e) });
       }
     }
 
@@ -210,10 +220,10 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
     if (s.currentUnit.type === "rewrite-docs") {
       try {
         await resolveAllOverrides(s.basePath);
-        resetRewriteCircuitBreaker();
+        s.rewriteAttemptCount = 0;
         ctx.ui.notify("Override(s) resolved — rewrite-docs completed.", "info");
-      } catch {
-        // Non-fatal
+      } catch (e) {
+        debugLog("postUnit", { phase: "rewrite-docs-resolve", error: String(e) });
       }
     }
 
@@ -226,8 +236,8 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
           const { clearReactiveState } = await import("./reactive-graph.js");
           clearReactiveState(s.basePath, mid, sid);
         }
-      } catch {
-        // Non-fatal
+      } catch (e) {
+        debugLog("postUnit", { phase: "reactive-state-cleanup", error: String(e) });
       }
     }
 
@@ -280,8 +290,8 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
         if (triggerArtifactVerified) {
           invalidateAllCaches();
         }
-      } catch {
-        // Non-fatal
+      } catch (e) {
+        debugLog("postUnit", { phase: "artifact-verify", error: String(e) });
       }
     } else {
       // Hook unit completed — finalize its runtime record
@@ -292,8 +302,8 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
           lastProgressKind: "hook-completed",
         });
         clearUnitRuntimeRecord(s.basePath, s.currentUnit.type, s.currentUnit.id);
-      } catch {
-        // Non-fatal
+      } catch (e) {
+        debugLog("postUnit", { phase: "hook-finalize", error: String(e) });
       }
     }
   }
@@ -429,8 +439,8 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
           }
         }
       }
-    } catch {
-      // Triage check failure is non-fatal
+    } catch (e) {
+      debugLog("postUnit", { phase: "triage-check", error: String(e) });
     }
   }
 
@@ -475,8 +485,8 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
       );
 
       return "continue";
-    } catch {
-      // Non-fatal — proceed to normal dispatch
+    } catch (e) {
+      debugLog("postUnit", { phase: "quick-task-dispatch", error: String(e) });
     }
   }
 

package/src/resources/extensions/gsd/auto-worktree-sync.ts

@@ -22,6 +22,8 @@ import { join, sep as pathSep } from "node:path";
 import { homedir } from "node:os";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Project Root → Worktree Sync ─────────────────────────────────────────
 
 /**
@@ -111,7 +113,7 @@ export function syncStateToProjectRoot(
  */
 export function readResourceVersion(): string | null {
   const agentDir =
-    process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
+    process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
   const manifestPath = join(agentDir, "managed-resources.json");
   try {
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));

package/src/resources/extensions/gsd/auto.ts

@@ -622,43 +622,28 @@ export async function stopAuto(
     if (existsSync(pausedPath)) unlinkSync(pausedPath);
   } catch { /* non-fatal */ }
 
-  s.active = false;
-  s.paused = false;
-  s.stepMode = false;
-  s.unitDispatchCount.clear();
-  s.unitRecoveryCount.clear();
-  clearInFlightTools();
-  s.lastBudgetAlertLevel = 0;
-  s.lastStateRebuildAt = 0;
-  s.unitLifetimeDispatches.clear();
-  s.currentUnit = null;
-  s.autoModeStartModel = null;
-  s.currentMilestoneId = null;
-  s.originalBasePath = "";
-  s.completedUnits = [];
-  s.pendingQuickTasks = [];
-  clearSliceProgressCache();
-  clearActivityLogState();
-  resetProactiveHealing();
-  s.pendingCrashRecovery = null;
-  s.pendingVerificationRetry = null;
-  s.verificationRetryCount.clear();
-  s.pausedSessionFile = null;
-  ctx?.ui.setStatus("gsd-auto", undefined);
-  ctx?.ui.setWidget("gsd-progress", undefined);
-  ctx?.ui.setFooter(undefined);
-
+  // Restore original model before reset() clears the IDs
   if (pi && ctx && s.originalModelId && s.originalModelProvider) {
     const original = ctx.modelRegistry.find(
       s.originalModelProvider,
       s.originalModelId,
     );
     if (original) await pi.setModel(original);
-    s.originalModelId = null;
-    s.originalModelProvider = null;
   }
 
-  s.cmdCtx = null;
+  // External cleanup (not covered by session reset)
+  clearInFlightTools();
+  clearSliceProgressCache();
+  clearActivityLogState();
+  resetProactiveHealing();
+
+  // UI cleanup
+  ctx?.ui.setStatus("gsd-auto", undefined);
+  ctx?.ui.setWidget("gsd-progress", undefined);
+  ctx?.ui.setFooter(undefined);
+
+  // Reset all session state in one call
+  s.reset();
 }
 
 /**

package/src/resources/extensions/gsd/commands-extensions.ts

@@ -11,6 +11,8 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFile
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Types (mirrored from extension-registry.ts) ────────────────────────────
 
 interface ExtensionManifest {
@@ -48,11 +50,11 @@ interface ExtensionRegistry {
 // ─── Registry I/O ───────────────────────────────────────────────────────────
 
 function getRegistryPath(): string {
-  return join(homedir(), ".gsd", "extensions", "registry.json");
+  return join(gsdHome, "extensions", "registry.json");
 }
 
 function getAgentExtensionsDir(): string {
-  return join(homedir(), ".gsd", "agent", "extensions");
+  return join(gsdHome, "agent", "extensions");
 }
 
 function loadRegistry(): ExtensionRegistry {

package/src/resources/extensions/gsd/commands.ts

@@ -10,6 +10,8 @@ import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
+
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 import { enableDebug } from "./debug-logger.js";
 import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
@@ -482,7 +484,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         if (parts.length === 3 && ["enable", "disable", "info"].includes(parts[1])) {
           const idPrefix = parts[2] ?? "";
           try {
-            const extDir = join(homedir(), ".gsd", "agent", "extensions");
+            const extDir = join(gsdHome, "agent", "extensions");
             const ids: { id: string; name: string }[] = [];
             for (const entry of readdirSync(extDir, { withFileTypes: true })) {
               if (!entry.isDirectory()) continue;

package/src/resources/extensions/gsd/detection.ts

@@ -11,6 +11,8 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { gsdRoot } from "./paths.js";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
 export interface ProjectDetection {
@@ -400,7 +402,6 @@ function detectVerificationCommands(
  * Check if global GSD setup exists (has ~/.gsd/ with preferences).
  */
 export function hasGlobalSetup(): boolean {
-  const gsdHome = join(homedir(), ".gsd");
   return (
     existsSync(join(gsdHome, "preferences.md")) ||
     existsSync(join(gsdHome, "PREFERENCES.md"))
@@ -412,7 +413,6 @@ export function hasGlobalSetup(): boolean {
  * Returns true if ~/.gsd/ doesn't exist or has no preferences or auth.
  */
 export function isFirstEverLaunch(): boolean {
-  const gsdHome = join(homedir(), ".gsd");
   if (!existsSync(gsdHome)) return true;
 
   // If we have preferences, not first launch

package/src/resources/extensions/gsd/export.ts

@@ -11,7 +11,7 @@ import {
 } from "./metrics.js";
 import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
-import { formatDuration, fileLink } from "../shared/mod.js";
+import { formatDuration, fileLink } from "../shared/format-utils.js";
 import { getErrorMessage } from "./error-utils.js";
 
 /**

package/src/resources/extensions/gsd/files.ts

@@ -7,7 +7,7 @@ import { promises as fs } from 'node:fs';
 import { resolve } from 'node:path';
 import { atomicWriteAsync } from './atomic-write.js';
 import { resolveMilestoneFile, relMilestoneFile, resolveGsdRootFile } from './paths.js';
-import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
+import { milestoneIdSort, findMilestoneIds } from './milestone-ids.js';
 
 import type {
   Roadmap, BoundaryMapEntry,
@@ -20,7 +20,7 @@ import type {
   ManifestStatus,
 } from './types.js';
 
-import { checkExistingEnvKeys } from '../get-secrets-from-user.js';
+import { checkExistingEnvKeys } from '../env-utils.js';
 import { parseRoadmapSlices } from './roadmap-slices.js';
 import { nativeParseRoadmap, nativeExtractSection, nativeParsePlanFile, nativeParseSummaryFile, NATIVE_UNAVAILABLE } from './native-parser-bridge.js';
 import { debugTime, debugCount } from './debug-logger.js';

package/src/resources/extensions/gsd/forensics.ts

@@ -27,7 +27,7 @@ import { deriveState } from "./state.js";
 import { isAutoActive } from "./auto.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { formatDuration } from "../shared/mod.js";
+import { formatDuration } from "../shared/format-utils.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/index.ts

@@ -60,6 +60,8 @@ import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { shortcutDesc } from "../shared/mod.js";
+
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 import { Text } from "@gsd/pi-tui";
 import { pauseAutoForProviderError, classifyProviderError } from "./provider-error-pause.js";
 import { toPosixPath } from "../shared/mod.js";
@@ -73,7 +75,7 @@ import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../cmux/index.js"
 
 function warnDeprecatedAgentInstructions(): void {
   const paths = [
-    join(homedir(), ".gsd", "agent-instructions.md"),
+    join(gsdHome, "agent-instructions.md"),
     join(process.cwd(), ".gsd", "agent-instructions.md"),
   ];
   for (const p of paths) {

package/src/resources/extensions/gsd/migrate/parsers.ts

@@ -3,7 +3,7 @@
 // Zero Pi dependencies — uses only exported helpers from files.ts.
 
 import { splitFrontmatter, parseFrontmatterMap, extractBoldField } from '../files.js';
-import { normalizeStringArray } from '../../shared/mod.js';
+import { normalizeStringArray } from '../../shared/format-utils.js';
 
 import type {
   PlanningRoadmap,

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -10,7 +10,7 @@ import type { GitPreferences } from "./git-service.js";
 import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile, PhaseSkipPreferences } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { VALID_BRANCH_NAME } from "./git-service.js";
-import { normalizeStringArray } from "../shared/mod.js";
+import { normalizeStringArray } from "../shared/format-utils.js";
 
 import {
   KNOWN_PREFERENCE_KEYS,

package/src/resources/extensions/gsd/preferences.ts

@@ -13,11 +13,13 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
 import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
-import { normalizeStringArray } from "../shared/mod.js";
+import { normalizeStringArray } from "../shared/format-utils.js";
 import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 
 import {
@@ -82,14 +84,14 @@ export {
 
 // ─── Path Constants & Getters ───────────────────────────────────────────────
 
-const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
+const GLOBAL_PREFERENCES_PATH = join(gsdHome, "preferences.md");
 const LEGACY_GLOBAL_PREFERENCES_PATH = join(homedir(), ".pi", "agent", "gsd-preferences.md");
 function projectPreferencesPath(): string {
   return join(gsdRoot(process.cwd()), "preferences.md");
 }
 // Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake.
 // Check uppercase as a fallback so those files aren't silently ignored.
-const GLOBAL_PREFERENCES_PATH_UPPERCASE = join(homedir(), ".gsd", "PREFERENCES.md");
+const GLOBAL_PREFERENCES_PATH_UPPERCASE = join(gsdHome, "PREFERENCES.md");
 function projectPreferencesPathUppercase(): string {
   return join(gsdRoot(process.cwd()), "PREFERENCES.md");
 }

package/src/resources/extensions/gsd/repo-identity.ts

@@ -12,6 +12,8 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, s
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Repo Identity ──────────────────────────────────────────────────────────
 
 /**
@@ -113,7 +115,7 @@ export function repoIdentity(basePath: string): string {
  * otherwise `~/.gsd/projects/<hash>`.
  */
 export function externalGsdRoot(basePath: string): string {
-  const base = process.env.GSD_STATE_DIR || join(homedir(), ".gsd");
+  const base = process.env.GSD_STATE_DIR || gsdHome;
   return join(base, "projects", repoIdentity(basePath));
 }
 

package/src/resources/extensions/gsd/resource-version.ts

@@ -11,6 +11,8 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { resolveProjectRoot } from "./worktree.js";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Resource Staleness ───────────────────────────────────────────────────
 
 /**
@@ -23,7 +25,7 @@ function isManifestWithVersion(data: unknown): data is { gsdVersion: string } {
 }
 
 export function readResourceVersion(): string | null {
-  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
+  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
   const manifestPath = join(agentDir, "managed-resources.json");
   const manifest = loadJsonFileOrNull(manifestPath, isManifestWithVersion);
   return manifest?.gsdVersion ?? null;

package/src/resources/extensions/gsd/state.ts

@@ -31,7 +31,7 @@ import {
   gsdRoot,
 } from './paths.js';
 
-import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
+import { milestoneIdSort, findMilestoneIds } from './milestone-ids.js';
 import { nativeBatchParseGsdFiles, type BatchParsedFile } from './native-parser-bridge.js';
 
 import { join, resolve } from 'path';

package/src/resources/extensions/gsd/visualizer-data.ts

@@ -3,7 +3,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { deriveState } from './state.js';
 import { parseRoadmap, parsePlan, parseSummary, loadFile } from './files.js';
-import { findMilestoneIds } from './guided-flow.js';
+import { findMilestoneIds } from './milestone-ids.js';
 import { resolveMilestoneFile, resolveSliceFile, resolveGsdRootFile } from './paths.js';
 import {
   getLedger,

package/src/resources/extensions/remote-questions/status.ts

@@ -7,6 +7,8 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { readPromptRecord } from "./store.js";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 export interface LatestPromptSummary {
   id: string;
   status: string;
@@ -14,7 +16,7 @@ export interface LatestPromptSummary {
 }
 
 export function getLatestPromptSummary(): LatestPromptSummary | null {
-  const runtimeDir = join(homedir(), ".gsd", "runtime", "remote-questions");
+  const runtimeDir = join(gsdHome, "runtime", "remote-questions");
   if (!existsSync(runtimeDir)) return null;
   const files = readdirSync(runtimeDir).filter((f) => f.endsWith(".json"));
   if (files.length === 0) return null;

package/src/resources/extensions/remote-questions/store.ts

@@ -7,8 +7,10 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import type { RemotePrompt, RemotePromptRecord, RemotePromptRef, RemoteAnswer, RemotePromptStatus } from "./types.js";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 function runtimeDir(): string {
-  return join(homedir(), ".gsd", "runtime", "remote-questions");
+  return join(gsdHome, "runtime", "remote-questions");
 }
 
 function recordPath(id: string): string {

package/src/resources/extensions/search-the-web/provider.ts

@@ -17,7 +17,8 @@ import { resolveSearchProviderFromPreferences } from '../gsd/preferences.js'
 // Compute authFilePath locally instead of importing from app-paths.ts,
 // because extensions are copied to ~/.gsd/agent/extensions/ at runtime
 // where the relative import '../../../app-paths.ts' doesn't resolve.
-const authFilePath = join(homedir(), '.gsd', 'agent', 'auth.json')
+const gsdHome = process.env.GSD_HOME || join(homedir(), '.gsd')
+const authFilePath = join(gsdHome, 'agent', 'auth.json')
 
 export type SearchProvider = 'tavily' | 'brave' | 'ollama'
 export type SearchProviderPreference = SearchProvider | 'auto'

package/src/resources/extensions/subagent/isolation.ts

@@ -57,8 +57,10 @@ function encodeCwd(cwd: string): string {
 	return cwd.replace(/\//g, "--");
 }
 
+const gsdHome = process.env.GSD_HOME || path.join(os.homedir(), ".gsd");
+
 function getIsolationBaseDir(cwd: string, taskId: string): string {
-	return path.join(os.homedir(), ".gsd", "wt", encodeCwd(cwd), taskId);
+	return path.join(gsdHome, "wt", encodeCwd(cwd), taskId);
 }
 
 // Track active isolation dirs for cleanup on exit

package/src/resources/extensions/ttsr/rule-loader.ts

@@ -8,6 +8,8 @@
 import { readdirSync, readFileSync, existsSync } from "node:fs";
 import { join, basename } from "node:path";
 import { homedir } from "node:os";
+
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 import type { Rule } from "./ttsr-manager.js";
 import { splitFrontmatter, parseFrontmatterMap } from "../shared/frontmatter.js";
 
@@ -59,7 +61,7 @@ function scanDir(dir: string): Rule[] {
  * Project rules override global rules with the same name.
  */
 export function loadRules(cwd: string): Rule[] {
-	const globalDir = join(homedir(), ".gsd", "agent", "rules");
+	const globalDir = join(gsdHome, "agent", "rules");
 	const projectDir = join(cwd, ".gsd", "rules");
 
 	const globalRules = scanDir(globalDir);