gsd-pi 2.38.0-dev.eeb3520 → 2.39.0-dev.20aba06

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.
@@ -84,14 +85,30 @@ function resolveGitRoot(basePath) {
         return resolve(basePath);
     }
 }
+/**
+ * Validate a GSD_PROJECT_ID value.
+ *
+ * Must contain only alphanumeric characters, hyphens, and underscores.
+ * Call this once at startup so the user gets immediate feedback on bad values.
+ */
+export function validateProjectId(id) {
+    return /^[a-zA-Z0-9_-]+$/.test(id);
+}
 /**
  * Compute a stable identity for a repository.
  *
- * SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated to 12 hex chars.
- * Deterministic: same repo always produces the same hash regardless of
- * which worktree the caller is inside.
+ * If `GSD_PROJECT_ID` is set, returns it directly (validation is expected
+ * to have already happened at startup via `validateProjectId`).
+ *
+ * Otherwise returns SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated
+ * to 12 hex chars. Deterministic: same repo always produces the same hash
+ * regardless of which worktree the caller is inside.
  */
 export function repoIdentity(basePath) {
+    const projectId = process.env.GSD_PROJECT_ID;
+    if (projectId) {
+        return projectId;
+    }
     const remoteUrl = getRemoteUrl(basePath);
     const root = resolveGitRoot(basePath);
     const input = `${remoteUrl}\n${root}`;
@@ -105,7 +122,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/roadmap-mutations.js

@@ -32,6 +32,30 @@ export function markSliceDoneInRoadmap(basePath, mid, sid) {
     clearParseCache();
     return true;
 }
+/**
+ * Mark a slice as not done ([ ]) in the milestone roadmap.
+ * Idempotent — no-op if already unchecked or if the slice isn't found.
+ *
+ * @returns true if the roadmap was modified, false if no change was needed
+ */
+export function markSliceUndoneInRoadmap(basePath, mid, sid) {
+    const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+    if (!roadmapFile)
+        return false;
+    let content;
+    try {
+        content = readFileSync(roadmapFile, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const updated = content.replace(new RegExp(`^(\\s*-\\s+)\\[x\\]\\s+\\*\\*${sid}:`, "m"), `$1[ ] **${sid}:`);
+    if (updated === content)
+        return false;
+    atomicWriteSync(roadmapFile, updated);
+    clearParseCache();
+    return true;
+}
 /**
  * Mark a task as done ([x]) in the slice plan.
  * Idempotent — no-op if already checked or if the task isn't found.

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';
@@ -82,8 +82,13 @@ export async function getActiveMilestoneId(basePath) {
             // A draft milestone is still "active" — this function only determines which milestone is current.
         }
         const roadmap = parseRoadmap(content);
-        if (!isMilestoneComplete(roadmap))
-            return mid;
+        if (!isMilestoneComplete(roadmap)) {
+            // Summary is the terminal artifact — if it exists, the milestone is
+            // complete even when roadmap checkboxes weren't ticked (#864).
+            const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+            if (!summaryFile)
+                return mid;
+        }
     }
     return null;
 }
@@ -202,8 +207,14 @@ async function _deriveStateImpl(basePath) {
         }
         const rmap = parseRoadmap(rc);
         roadmapCache.set(mid, rmap);
-        if (!isMilestoneComplete(rmap))
+        if (!isMilestoneComplete(rmap)) {
+            // Summary is the terminal artifact — if it exists, the milestone is
+            // complete even when roadmap checkboxes weren't ticked (#864).
+            const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
+            if (sf)
+                completeMilestoneIds.add(mid);
             continue;
+        }
         const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
         if (sf)
             completeMilestoneIds.add(mid);
@@ -303,29 +314,37 @@ async function _deriveStateImpl(basePath) {
                 registry.push({ id: mid, title, status: 'complete' });
             }
         }
-        else if (!activeMilestoneFound) {
-            // Check milestone-level dependencies before promoting to active
-            const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
-            const contextContent = contextFile ? await cachedLoadFile(contextFile) : null;
-            const deps = parseContextDependsOn(contextContent);
-            const depsUnmet = deps.some(dep => !completeMilestoneIds.has(dep));
-            if (depsUnmet) {
-                registry.push({ id: mid, title, status: 'pending', dependsOn: deps });
-                // Do NOT set activeMilestoneFound — let the loop continue to the next milestone
+        else {
+            // Roadmap slices not all checked — but if a summary exists, the milestone
+            // is still complete. The summary is the terminal artifact (#864).
+            const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+            if (summaryFile) {
+                registry.push({ id: mid, title, status: 'complete' });
+            }
+            else if (!activeMilestoneFound) {
+                // Check milestone-level dependencies before promoting to active
+                const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
+                const contextContent = contextFile ? await cachedLoadFile(contextFile) : null;
+                const deps = parseContextDependsOn(contextContent);
+                const depsUnmet = deps.some(dep => !completeMilestoneIds.has(dep));
+                if (depsUnmet) {
+                    registry.push({ id: mid, title, status: 'pending', dependsOn: deps });
+                    // Do NOT set activeMilestoneFound — let the loop continue to the next milestone
+                }
+                else {
+                    activeMilestone = { id: mid, title };
+                    activeRoadmap = roadmap;
+                    activeMilestoneFound = true;
+                    registry.push({ id: mid, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
+                }
             }
             else {
-                activeMilestone = { id: mid, title };
-                activeRoadmap = roadmap;
-                activeMilestoneFound = true;
-                registry.push({ id: mid, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
+                const contextFile2 = resolveMilestoneFile(basePath, mid, "CONTEXT");
+                const contextContent2 = contextFile2 ? await cachedLoadFile(contextFile2) : null;
+                const deps2 = parseContextDependsOn(contextContent2);
+                registry.push({ id: mid, title, status: 'pending', ...(deps2.length > 0 ? { dependsOn: deps2 } : {}) });
             }
         }
-        else {
-            const contextFile2 = resolveMilestoneFile(basePath, mid, "CONTEXT");
-            const contextContent2 = contextFile2 ? await cachedLoadFile(contextFile2) : null;
-            const deps2 = parseContextDependsOn(contextContent2);
-            registry.push({ id: mid, title, status: 'pending', ...(deps2.length > 0 ? { dependsOn: deps2 } : {}) });
-        }
     }
     const milestoneProgress = {
         done: registry.filter(entry => entry.status === 'complete').length,

package/dist/resources/extensions/gsd/templates/runtime.md

@@ -0,0 +1,21 @@
+# Runtime Context
+
+## Stack
+- **Language:** (e.g., TypeScript, Python, Go)
+- **Framework:** (e.g., Next.js, FastAPI, Gin)
+- **Build:** (e.g., npm run build, cargo build)
+- **Test:** (e.g., npm run test, pytest)
+- **Lint:** (e.g., npm run lint, ruff check)
+
+## Environment
+- **Node version:** (e.g., 20.x)
+- **Package manager:** (e.g., npm, pnpm, yarn)
+- **Required env vars:** (list any needed for local dev)
+
+## Dev Server
+- **Start command:** (e.g., npm run dev)
+- **Default port:** (e.g., 3000)
+- **Health check:** (e.g., curl http://localhost:3000/health)
+
+## Notes
+(Any runtime-specific context the executor needs to know)

package/dist/resources/extensions/gsd/templates/task-plan.md

@@ -3,6 +3,9 @@
 # Tasks with 10+ estimated steps or 12+ estimated files trigger a warning to consider splitting.
 estimated_steps: {{estimatedSteps}}
 estimated_files: {{estimatedFiles}}
+# Installed skills the planner expects the executor to load before coding.
+skills_used:
+  - {{skillName}}
 ---
 
 # {{taskId}}: {{taskTitle}}

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

@@ -1,15 +1,18 @@
 // Data loader for workflow visualizer overlay — aggregates state + metrics.
 import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 import { deriveState } from './state.js';
 import { parseRoadmap, parsePlan, parseSummary, loadFile } from './files.js';
-import { findMilestoneIds } from './guided-flow.js';
-import { resolveMilestoneFile, resolveSliceFile, resolveGsdRootFile } from './paths.js';
+import { findMilestoneIds } from './milestone-ids.js';
+import { resolveMilestoneFile, resolveSliceFile, resolveGsdRootFile, gsdRoot } from './paths.js';
 import { getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice, aggregateByModel, aggregateByTier, formatTierSavings, loadLedgerFromDisk, } from './metrics.js';
 import { loadAllCaptures, countPendingCaptures } from './captures.js';
 import { loadEffectiveGSDPreferences } from './preferences.js';
 import { runProviderChecks } from './doctor-providers.js';
 import { generateSkillHealthReport } from './skill-health.js';
 import { runEnvironmentChecks } from './doctor-environment.js';
+import { computeProgressScore } from './progress-score.js';
+import { getHealthHistory } from './doctor-proactive.js';
 // ─── Critical Path ────────────────────────────────────────────────────────────
 export function computeCriticalPath(milestones) {
     const empty = {
@@ -392,6 +395,26 @@ function loadHealth(units, totals, basePath) {
         environmentIssues = runEnvironmentChecks(basePath).filter(r => r.status !== "ok");
     }
     catch { /* non-fatal */ }
+    // Doctor run history — persisted across sessions (sync read to keep loadHealth sync)
+    let doctorHistory = [];
+    try {
+        const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+        if (existsSync(historyPath)) {
+            const lines = readFileSync(historyPath, "utf-8").split("\n").filter(l => l.trim());
+            doctorHistory = lines.slice(-20).reverse().map(l => JSON.parse(l));
+        }
+    }
+    catch { /* non-fatal */ }
+    // Current progress score — only meaningful when auto-mode has health data
+    let progressScore = null;
+    try {
+        const history = getHealthHistory();
+        if (history.length > 0) {
+            const score = computeProgressScore();
+            progressScore = { level: score.level, summary: score.summary, signals: score.signals };
+        }
+    }
+    catch { /* non-fatal */ }
     return {
         budgetCeiling,
         tokenProfile,
@@ -405,6 +428,8 @@ function loadHealth(units, totals, basePath) {
         providers,
         skillSummary,
         environmentIssues,
+        doctorHistory,
+        progressScore,
     };
 }
 const RECENT_ENTRY_LIMIT = 3;

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

@@ -872,6 +872,58 @@ export function renderHealthView(data, th, width) {
             }
         }
     }
+    // Progress score section — current traffic light status
+    if (health.progressScore) {
+        lines.push("");
+        lines.push(th.fg("accent", th.bold("Progress Score")));
+        lines.push("");
+        const ps = health.progressScore;
+        const scoreColor = ps.level === "green" ? "success" : ps.level === "yellow" ? "warning" : "error";
+        const scoreIcon = ps.level === "green" ? "●" : ps.level === "yellow" ? "◐" : "○";
+        lines.push(`  ${th.fg(scoreColor, scoreIcon)} ${th.fg(scoreColor, ps.summary)}`);
+        for (const signal of ps.signals) {
+            const prefix = signal.kind === "positive" ? th.fg("success", "  ✓")
+                : signal.kind === "negative" ? th.fg("error", "  ✗")
+                    : th.fg("dim", "  ·");
+            lines.push(`  ${prefix} ${th.fg("dim", signal.label)}`);
+        }
+    }
+    // Doctor history section — persisted across sessions
+    const doctorHistory = health.doctorHistory ?? [];
+    if (doctorHistory.length > 0) {
+        lines.push("");
+        lines.push(th.fg("accent", th.bold("Doctor History")));
+        lines.push("");
+        for (const entry of doctorHistory.slice(0, 10)) {
+            const icon = entry.ok ? th.fg("success", "✓") : th.fg("error", "✗");
+            const ts = entry.ts.replace("T", " ").slice(0, 19);
+            const scopeTag = entry.scope ? th.fg("accent", ` [${entry.scope}]`) : "";
+            // Prefer human-readable summary, fall back to counts
+            const detail = entry.summary
+                ? th.fg("text", entry.summary)
+                : th.fg("text", `${entry.errors} errors, ${entry.warnings} warnings, ${entry.fixes} fixes`);
+            lines.push(`  ${icon} ${th.fg("dim", ts)}${scopeTag}  ${detail}`);
+            // Show issue details if available
+            if (entry.issues && entry.issues.length > 0) {
+                for (const issue of entry.issues.slice(0, 3)) {
+                    const issuePfx = issue.severity === "error" ? th.fg("error", "    ✗") : th.fg("warning", "    ⚠");
+                    lines.push(`  ${issuePfx} ${th.fg("dim", truncateToWidth(issue.message, width - 12))}`);
+                }
+                if (entry.issues.length > 3) {
+                    lines.push(`    ${th.fg("dim", `+${entry.issues.length - 3} more`)}`);
+                }
+            }
+            // Show fixes if available
+            if (entry.fixDescriptions && entry.fixDescriptions.length > 0) {
+                for (const fix of entry.fixDescriptions.slice(0, 2)) {
+                    lines.push(`    ${th.fg("success", "↳")} ${th.fg("dim", truncateToWidth(fix, width - 12))}`);
+                }
+            }
+        }
+        if (doctorHistory.length > 10) {
+            lines.push(`  ${th.fg("dim", `...${doctorHistory.length - 10} older entries`)}`);
+        }
+    }
     // Skills section
     if (health.skillSummary?.total > 0) {
         lines.push("");

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

@@ -57,42 +57,61 @@ export function captureIntegrationBranch(basePath, milestoneId, options) {
     writeIntegrationBranch(basePath, milestoneId, current, options);
 }
 // ─── Pure Utility Functions (unchanged) ────────────────────────────────────
+/**
+ * Find the worktrees segment in a path, supporting both direct
+ * (`/.gsd/worktrees/`) and symlink-resolved (`/.gsd/projects/<hash>/worktrees/`)
+ * layouts.  When `.gsd` is a symlink to `~/.gsd/projects/<hash>`, resolved
+ * paths contain the intermediate `projects/<hash>/` segment that the old
+ * single-marker check missed.
+ */
+function findWorktreeSegment(normalizedPath) {
+    // Direct layout: /.gsd/worktrees/<name>
+    const directMarker = "/.gsd/worktrees/";
+    const idx = normalizedPath.indexOf(directMarker);
+    if (idx !== -1) {
+        return { gsdIdx: idx, afterWorktrees: idx + directMarker.length };
+    }
+    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/<name>
+    const symlinkRe = /\/\.gsd\/projects\/[a-f0-9]+\/worktrees\//;
+    const match = normalizedPath.match(symlinkRe);
+    if (match && match.index !== undefined) {
+        return { gsdIdx: match.index, afterWorktrees: match.index + match[0].length };
+    }
+    return null;
+}
 /**
  * Detect the active worktree name from the current working directory.
  * Returns null if not inside a GSD worktree (.gsd/worktrees/<name>/).
  */
 export function detectWorktreeName(basePath) {
     const normalizedPath = basePath.replaceAll("\\", "/");
-    const marker = "/.gsd/worktrees/";
-    const idx = normalizedPath.indexOf(marker);
-    if (idx === -1)
+    const seg = findWorktreeSegment(normalizedPath);
+    if (!seg)
         return null;
-    const afterMarker = normalizedPath.slice(idx + marker.length);
+    const afterMarker = normalizedPath.slice(seg.afterWorktrees);
     const name = afterMarker.split("/")[0];
     return name || null;
 }
 /**
  * Resolve the project root from a path that may be inside a worktree.
- * If the path contains `/.gsd/worktrees/<name>/`, returns the portion
- * before `/.gsd/`. Otherwise returns the input unchanged.
+ * If the path contains a worktrees segment, returns the portion before
+ * `/.gsd/`. Otherwise returns the input unchanged.
  *
  * Use this in commands that call `process.cwd()` to ensure they always
  * operate against the real project root, not a worktree subdirectory.
  */
 export function resolveProjectRoot(basePath) {
     const normalizedPath = basePath.replaceAll("\\", "/");
-    const marker = "/.gsd/worktrees/";
-    const idx = normalizedPath.indexOf(marker);
-    if (idx === -1)
+    const seg = findWorktreeSegment(normalizedPath);
+    if (!seg)
         return basePath;
-    // Return the original path up to the .gsd/ marker (un-normalized)
-    // Account for potential OS-specific separators
+    // Return the original path up to the /.gsd/ boundary
     const sep = basePath.includes("\\") ? "\\" : "/";
-    const markerOs = `${sep}.gsd${sep}worktrees${sep}`;
-    const idxOs = basePath.indexOf(markerOs);
-    if (idxOs !== -1)
-        return basePath.slice(0, idxOs);
-    return basePath.slice(0, idx);
+    const gsdMarker = `${sep}.gsd${sep}`;
+    const gsdIdx = basePath.indexOf(gsdMarker);
+    if (gsdIdx !== -1)
+        return basePath.slice(0, gsdIdx);
+    return basePath.slice(0, seg.gsdIdx);
 }
 /**
  * Get the slice branch name, namespaced by worktree when inside one.

package/dist/resources/extensions/mcp-client/index.js

@@ -76,6 +76,19 @@ function readConfigs() {
 function getServerConfig(name) {
     return readConfigs().find((s) => s.name === name);
 }
+/** Resolve ${VAR} references in env values against process.env. */
+function resolveEnv(env) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (typeof value === "string") {
+            resolved[key] = value.replace(/\$\{([^}]+)\}/g, (_match, varName) => process.env[varName] ?? "");
+        }
+        else {
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}
 async function getOrConnect(name, signal) {
     const existing = connections.get(name);
     if (existing)
@@ -89,7 +102,7 @@ async function getOrConnect(name, signal) {
         transport = new StdioClientTransport({
             command: config.command,
             args: config.args,
-            env: config.env ? { ...process.env, ...config.env } : undefined,
+            env: config.env ? { ...process.env, ...resolveEnv(config.env) } : undefined,
             cwd: config.cwd,
             stderr: "pipe",
         });

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

@@ -5,8 +5,11 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { readPromptRecord } from "./store.js";
+function getGsdHome() {
+    return process.env.GSD_HOME || join(homedir(), ".gsd");
+}
 export function getLatestPromptSummary() {
-    const runtimeDir = join(homedir(), ".gsd", "runtime", "remote-questions");
+    const runtimeDir = join(getGsdHome(), "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,11 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+function getGsdHome() {
+    return process.env.GSD_HOME || join(homedir(), ".gsd");
+}
 function runtimeDir() {
-    return join(homedir(), ".gsd", "runtime", "remote-questions");
+    return join(getGsdHome(), "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/shared/frontmatter.js

@@ -45,7 +45,7 @@ export function parseFrontmatterMap(lines) {
             continue;
         }
         // Array item (2-space indent)
-        const arrayMatch = line.match(/^  - (.*)$/);
+        const arrayMatch = line.match(/^  - ?(.*)$/);
         if (arrayMatch && currentKey) {
             // If there's a pending nested object, push it
             if (currentObj && Object.keys(currentObj).length > 0) {

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

@@ -360,7 +360,7 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             }
     }
 }
-async function runSingleAgentInCmuxSplit(cmuxClient, direction, defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails) {
+async function runSingleAgentInCmuxSplit(cmuxClient, directionOrSurfaceId, defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails) {
     const agent = agents.find((a) => a.name === agentName);
     if (!agent) {
         return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails);
@@ -397,7 +397,12 @@ async function runSingleAgentInCmuxSplit(cmuxClient, direction, defaultCwd, agen
         const stdoutPath = path.join(tmpOutputDir, "stdout.jsonl");
         const stderrPath = path.join(tmpOutputDir, "stderr.log");
         const exitPath = path.join(tmpOutputDir, "exit.code");
-        const cmuxSurfaceId = await cmuxClient.createSplit(direction);
+        // Accept either a pre-created surface ID or a direction to create a new split
+        const isDirection = directionOrSurfaceId === "right" || directionOrSurfaceId === "down"
+            || directionOrSurfaceId === "left" || directionOrSurfaceId === "up";
+        const cmuxSurfaceId = isDirection
+            ? await cmuxClient.createSplit(directionOrSurfaceId)
+            : directionOrSurfaceId;
         if (!cmuxSurfaceId) {
             return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails);
         }
@@ -656,10 +661,14 @@ export default function (pi) {
                 const MAX_RETRIES = 1; // Retry failed tasks once
                 const batchId = crypto.randomUUID();
                 const batchSize = params.tasks.length;
+                // Pre-create a grid layout for cmux splits so agents get a clean tiled arrangement
+                const gridSurfaces = cmuxSplitsEnabled
+                    ? await cmuxClient.createGridLayout(Math.min(batchSize, MAX_CONCURRENCY))
+                    : [];
                 const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
                     const workerId = registerWorker(t.agent, t.task, index, batchSize, batchId);
                     const runTask = () => cmuxSplitsEnabled
-                        ? runSingleAgentInCmuxSplit(cmuxClient, index % 2 === 0 ? "right" : "down", ctx.cwd, agents, t.agent, t.task, t.cwd, undefined, signal, (partial) => {
+                        ? runSingleAgentInCmuxSplit(cmuxClient, gridSurfaces[index] ?? (index % 2 === 0 ? "right" : "down"), ctx.cwd, agents, t.agent, t.task, t.cwd, undefined, signal, (partial) => {
                             if (partial.details?.results[0]) {
                                 allResults[index] = partial.details.results[0];
                                 emitParallelUpdate();

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/dist/resources/extensions/universal-config/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.js"
     ]
   }
 }

package/dist/welcome-screen.d.ts

@@ -0,0 +1,13 @@
+/**
+ * GSD Welcome Screen
+ *
+ * Two-panel bar layout: full-width accent bars at top/bottom (matching the
+ * auto-mode progress widget style), logo left (fixed width), info right.
+ * Falls back to simple text on narrow terminals (<70 cols) or non-TTY.
+ */
+export interface WelcomeScreenOptions {
+    version: string;
+    modelName?: string;
+    provider?: string;
+}
+export declare function printWelcomeScreen(opts: WelcomeScreenOptions): void;