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

package/dist/app-paths.js

@@ -1,6 +1,6 @@
 import { homedir } from 'os';
 import { join } from 'path';
-export const appRoot = join(homedir(), '.gsd');
+export const appRoot = process.env.GSD_HOME || join(homedir(), '.gsd');
 export const agentDir = join(appRoot, 'agent');
 export const sessionsDir = join(appRoot, 'sessions');
 export const authFilePath = join(agentDir, 'auth.json');

package/dist/extension-registry.js

@@ -6,7 +6,7 @@
  * The only way an extension stops loading is an explicit `gsd extensions disable <id>`.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { appRoot } from "./app-paths.js";
 import { dirname, join } from "node:path";
 // ─── Validation ─────────────────────────────────────────────────────────────
 function isRegistry(data) {
@@ -26,7 +26,7 @@ function isManifest(data) {
 }
 // ─── Registry Path ──────────────────────────────────────────────────────────
 export function getRegistryPath() {
-    return join(homedir(), ".gsd", "extensions", "registry.json");
+    return join(appRoot, "extensions", "registry.json");
 }
 // ─── Registry I/O ───────────────────────────────────────────────────────────
 function defaultRegistry() {

package/dist/remote-questions-config.js

@@ -9,12 +9,12 @@
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { homedir } from "node:os";
+import { appRoot } from "./app-paths.js";
 // Inlined from preferences.ts to avoid crossing the compiled/uncompiled
 // boundary — this file is compiled by tsc, but preferences.ts is loaded
 // via jiti at runtime. Importing it as .js fails because no .js exists
 // in dist/. See #592, #1110.
-const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
+const GLOBAL_PREFERENCES_PATH = join(appRoot, "preferences.md");
 export function saveRemoteQuestionsConfig(channel, channelId) {
     const prefsPath = GLOBAL_PREFERENCES_PATH;
     const block = [

package/dist/resources/extensions/env-utils.js

@@ -0,0 +1,29 @@
+// GSD Extension — Environment variable utilities
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+//
+// Pure utility for checking existing env keys in .env files and process.env.
+// Extracted from get-secrets-from-user.ts to avoid pulling in @gsd/pi-tui
+// when only env-checking is needed (e.g. from files.ts during report generation).
+import { readFile } from "node:fs/promises";
+/**
+ * Check which keys already exist in a .env file or process.env.
+ * Returns the subset of `keys` that are already set.
+ */
+export async function checkExistingEnvKeys(keys, envFilePath) {
+    let fileContent = "";
+    try {
+        fileContent = await readFile(envFilePath, "utf8");
+    }
+    catch {
+        // ENOENT or other read error — proceed with empty content
+    }
+    const existing = [];
+    for (const key of keys) {
+        const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const regex = new RegExp(`^${escaped}\\s*=`, "m");
+        if (regex.test(fileContent) || key in process.env) {
+            existing.push(key);
+        }
+    }
+    return existing;
+}

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

@@ -46,30 +46,11 @@ async function writeEnvKey(filePath, key, value) {
     await writeFile(filePath, content, "utf8");
 }
 // ─── Exported utilities ───────────────────────────────────────────────────────
-/**
- * Check which keys already exist in the .env file or process.env.
- * Returns the subset of `keys` that are already set.
- * Handles ENOENT gracefully (still checks process.env).
- * Empty-string values count as existing.
- */
-export async function checkExistingEnvKeys(keys, envFilePath) {
-    let fileContent = "";
-    try {
-        fileContent = await readFile(envFilePath, "utf8");
-    }
-    catch {
-        // ENOENT or other read error — proceed with empty content
-    }
-    const existing = [];
-    for (const key of keys) {
-        const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        const regex = new RegExp(`^${escaped}\\s*=`, "m");
-        if (regex.test(fileContent) || key in process.env) {
-            existing.push(key);
-        }
-    }
-    return existing;
-}
+// Re-export from env-utils.ts so existing consumers still work.
+// The implementation lives in env-utils.ts to avoid pulling @gsd/pi-tui
+// into modules that only need env-checking (e.g. files.ts during reports).
+import { checkExistingEnvKeys } from "./env-utils.js";
+export { checkExistingEnvKeys };
 /**
  * Detect the write destination based on project files in basePath.
  * Priority: vercel.json → convex/ dir → fallback "dotenv".

package/dist/resources/extensions/gsd/auto-worktree-sync.js

@@ -13,6 +13,7 @@ import { existsSync, readFileSync, unlinkSync, readdirSync, } from "node:fs";
 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 ─────────────────────────────────────────
 /**
  * Sync milestone artifacts from project root INTO worktree before deriveState.
@@ -75,7 +76,7 @@ export function syncStateToProjectRoot(worktreePath, projectRoot, milestoneId) {
  * doesn't falsely trigger staleness (#804).
  */
 export function readResourceVersion() {
-    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");
     try {
         const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));

package/dist/resources/extensions/gsd/commands-extensions.js

@@ -8,12 +8,13 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 // ─── Registry I/O ───────────────────────────────────────────────────────────
 function getRegistryPath() {
-    return join(homedir(), ".gsd", "extensions", "registry.json");
+    return join(gsdHome, "extensions", "registry.json");
 }
 function getAgentExtensionsDir() {
-    return join(homedir(), ".gsd", "agent", "extensions");
+    return join(gsdHome, "agent", "extensions");
 }
 function loadRegistry() {
     const filePath = getRegistryPath();

package/dist/resources/extensions/gsd/commands.js

@@ -7,6 +7,7 @@ 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";
@@ -437,7 +438,7 @@ export function registerGSDCommand(pi) {
                 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 = [];
                         for (const entry of readdirSync(extDir, { withFileTypes: true })) {
                             if (!entry.isDirectory())

package/dist/resources/extensions/gsd/detection.js

@@ -9,6 +9,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { gsdRoot } from "./paths.js";
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 // ─── Project File Markers ───────────────────────────────────────────────────────
 const PROJECT_FILES = [
     "package.json",
@@ -309,7 +310,6 @@ function detectVerificationCommands(basePath, detectedFiles, packageManager) {
  * Check if global GSD setup exists (has ~/.gsd/ with preferences).
  */
 export function hasGlobalSetup() {
-    const gsdHome = join(homedir(), ".gsd");
     return (existsSync(join(gsdHome, "preferences.md")) ||
         existsSync(join(gsdHome, "PREFERENCES.md")));
 }
@@ -318,7 +318,6 @@ export function hasGlobalSetup() {
  * Returns true if ~/.gsd/ doesn't exist or has no preferences or auth.
  */
 export function isFirstEverLaunch() {
-    const gsdHome = join(homedir(), ".gsd");
     if (!existsSync(gsdHome))
         return true;
     // If we have preferences, not first launch

package/dist/resources/extensions/gsd/export.js

@@ -5,7 +5,7 @@ import { join, basename } from "node:path";
 import { exec } from "node:child_process";
 import { getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice, aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk, } 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";
 /**
  * Open a file in the user's default browser.

package/dist/resources/extensions/gsd/files.js

@@ -6,8 +6,8 @@ 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 { findMilestoneIds } from './guided-flow.js';
-import { checkExistingEnvKeys } from '../get-secrets-from-user.js';
+import { findMilestoneIds } from './milestone-ids.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/dist/resources/extensions/gsd/forensics.js

@@ -21,7 +21,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";
 // ─── Entry Point ──────────────────────────────────────────────────────────────
 export async function handleForensics(args, ctx, pi) {

package/dist/resources/extensions/gsd/index.js

@@ -41,6 +41,7 @@ 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";
@@ -52,7 +53,7 @@ import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../cmux/index.js"
 // Pi core natively supports AGENTS.md (with CLAUDE.md fallback) per directory.
 function warnDeprecatedAgentInstructions() {
     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/dist/resources/extensions/gsd/migrate/parsers.js

@@ -2,7 +2,7 @@
 // Pure functions that take file content (string) and return typed data.
 // 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';
 // Re-export PlanningProjectMeta — not in types.ts yet, use string for project field
 // Actually PlanningProjectMeta isn't in types.ts — project is stored as string | null.
 // We'll keep parseOldProject returning a simple shape.

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -6,7 +6,7 @@
  * together with any errors and warnings.
  */
 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, KNOWN_UNIT_TYPES, SKILL_ACTIONS, } from "./preferences-types.js";
 const VALID_TOKEN_PROFILES = new Set(["budget", "balanced", "quality"]);
 export function validatePreferences(preferences) {

package/dist/resources/extensions/gsd/preferences.js

@@ -12,9 +12,10 @@
 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 { normalizeStringArray } from "../shared/mod.js";
+import { normalizeStringArray } from "../shared/format-utils.js";
 import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 import { MODE_DEFAULTS, } from "./preferences-types.js";
 import { validatePreferences } from "./preferences-validation.js";
@@ -26,14 +27,14 @@ export { resolveAllSkillReferences, resolveSkillDiscoveryMode, resolveSkillStale
 // ─── Re-exports: models ─────────────────────────────────────────────────────
 export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, isTransientNetworkError, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, resolveEffectiveProfile, resolveInlineLevel, resolveCompressionStrategy, resolveContextSelection, resolveSearchProviderFromPreferences, } from "./preferences-models.js";
 // ─── 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() {
     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() {
     return join(gsdRoot(process.cwd()), "PREFERENCES.md");
 }

package/dist/resources/extensions/gsd/repo-identity.js

@@ -10,6 +10,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 // ─── Repo Identity ──────────────────────────────────────────────────────────
 /**
  * Get the git remote URL for "origin", or "" if no remote is configured.
@@ -105,7 +106,7 @@ export function repoIdentity(basePath) {
  * otherwise `~/.gsd/projects/<hash>`.
  */
 export function externalGsdRoot(basePath) {
-    const base = process.env.GSD_STATE_DIR || join(homedir(), ".gsd");
+    const base = process.env.GSD_STATE_DIR || gsdHome;
     return join(base, "projects", repoIdentity(basePath));
 }
 // ─── Symlink Management ─────────────────────────────────────────────────────

package/dist/resources/extensions/gsd/resource-version.js

@@ -9,6 +9,7 @@ import { loadJsonFileOrNull } from "./json-persistence.js";
 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 ───────────────────────────────────────────────────
 /**
  * Read the resource version (semver) from the managed-resources manifest.
@@ -19,7 +20,7 @@ function isManifestWithVersion(data) {
     return data !== null && typeof data === "object" && "gsdVersion" in data && typeof data.gsdVersion === "string";
 }
 export function readResourceVersion() {
-    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/dist/resources/extensions/gsd/state.js

@@ -3,7 +3,7 @@
 // Pure TypeScript, zero Pi dependencies.
 import { parseRoadmap, parsePlan, parseSummary, loadFile, parseRequirementCounts, parseContextDependsOn, } from './files.js';
 import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveGsdRootFile, gsdRoot, } from './paths.js';
-import { findMilestoneIds } from './guided-flow.js';
+import { findMilestoneIds } from './milestone-ids.js';
 import { nativeBatchParseGsdFiles } from './native-parser-bridge.js';
 import { join, resolve } from 'path';
 import { existsSync, readdirSync } from 'node:fs';

package/dist/resources/extensions/gsd/visualizer-data.js

@@ -2,7 +2,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, getProjectTotals, aggregateByPhase, aggregateBySlice, aggregateByModel, aggregateByTier, formatTierSavings, loadLedgerFromDisk, } from './metrics.js';
 import { loadAllCaptures, countPendingCaptures } from './captures.js';

package/dist/resources/extensions/remote-questions/status.js

@@ -5,8 +5,9 @@ import { existsSync, readdirSync } from "node:fs";
 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 function getLatestPromptSummary() {
-    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"));

package/dist/resources/extensions/remote-questions/store.js

@@ -4,8 +4,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 function runtimeDir() {
-    return join(homedir(), ".gsd", "runtime", "remote-questions");
+    return join(gsdHome, "runtime", "remote-questions");
 }
 function recordPath(id) {
     return join(runtimeDir(), `${id}.json`);

package/dist/resources/extensions/search-the-web/provider.js

@@ -15,7 +15,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');
 const VALID_PREFERENCES = new Set(['tavily', 'brave', 'ollama', 'auto']);
 const PREFERENCE_KEY = 'search_provider';
 /** Returns the Tavily API key from the environment, or empty string if not set. */

package/dist/resources/extensions/subagent/isolation.js

@@ -17,8 +17,9 @@ const execFile = promisify(execFileCb);
 function encodeCwd(cwd) {
     return cwd.replace(/\//g, "--");
 }
+const gsdHome = process.env.GSD_HOME || path.join(os.homedir(), ".gsd");
 function getIsolationBaseDir(cwd, taskId) {
-    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
 const activeIsolations = new Set();

package/dist/resources/extensions/ttsr/rule-loader.js

@@ -8,6 +8,7 @@
 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 { splitFrontmatter, parseFrontmatterMap } from "../shared/frontmatter.js";
 function parseRuleFile(filePath) {
     let content;
@@ -56,7 +57,7 @@ function scanDir(dir) {
  * Project rules override global rules with the same name.
  */
 export function loadRules(cwd) {
-    const globalDir = join(homedir(), ".gsd", "agent", "rules");
+    const globalDir = join(gsdHome, "agent", "rules");
     const projectDir = join(cwd, ".gsd", "rules");
     const globalRules = scanDir(globalDir);
     const projectRules = scanDir(projectDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "2.38.0-dev.96dc7fb",
+  "version": "2.38.0-dev.e40f839",
   "description": "GSD — Get Shit Done coding agent",
   "license": "MIT",
   "repository": {

package/src/resources/extensions/env-utils.ts

@@ -0,0 +1,31 @@
+// GSD Extension — Environment variable utilities
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+//
+// Pure utility for checking existing env keys in .env files and process.env.
+// Extracted from get-secrets-from-user.ts to avoid pulling in @gsd/pi-tui
+// when only env-checking is needed (e.g. from files.ts during report generation).
+
+import { readFile } from "node:fs/promises";
+
+/**
+ * Check which keys already exist in a .env file or process.env.
+ * Returns the subset of `keys` that are already set.
+ */
+export async function checkExistingEnvKeys(keys: string[], envFilePath: string): Promise<string[]> {
+	let fileContent = "";
+	try {
+		fileContent = await readFile(envFilePath, "utf8");
+	} catch {
+		// ENOENT or other read error — proceed with empty content
+	}
+
+	const existing: string[] = [];
+	for (const key of keys) {
+		const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const regex = new RegExp(`^${escaped}\\s*=`, "m");
+		if (regex.test(fileContent) || key in process.env) {
+			existing.push(key);
+		}
+	}
+	return existing;
+}

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

@@ -67,30 +67,11 @@ async function writeEnvKey(filePath: string, key: string, value: string): Promis
 
 // ─── Exported utilities ───────────────────────────────────────────────────────
 
-/**
- * Check which keys already exist in the .env file or process.env.
- * Returns the subset of `keys` that are already set.
- * Handles ENOENT gracefully (still checks process.env).
- * Empty-string values count as existing.
- */
-export async function checkExistingEnvKeys(keys: string[], envFilePath: string): Promise<string[]> {
-	let fileContent = "";
-	try {
-		fileContent = await readFile(envFilePath, "utf8");
-	} catch {
-		// ENOENT or other read error — proceed with empty content
-	}
-
-	const existing: string[] = [];
-	for (const key of keys) {
-		const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-		const regex = new RegExp(`^${escaped}\\s*=`, "m");
-		if (regex.test(fileContent) || key in process.env) {
-			existing.push(key);
-		}
-	}
-	return existing;
-}
+// Re-export from env-utils.ts so existing consumers still work.
+// The implementation lives in env-utils.ts to avoid pulling @gsd/pi-tui
+// into modules that only need env-checking (e.g. files.ts during reports).
+import { checkExistingEnvKeys } from "./env-utils.js";
+export { checkExistingEnvKeys };
 
 /**
  * Detect the write destination based on project files in basePath.

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/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);