gsd-pi 2.37.1 → 2.38.0-dev.29edcdc

package/dist/resources/extensions/gsd/reactive-graph.js

@@ -0,0 +1,227 @@
+/**
+ * Reactive Task Graph — derives dependency edges from task plan IO signatures.
+ *
+ * Pure functions that build a DAG from task IO intersections and resolve
+ * which tasks are currently ready for parallel dispatch. Used by the
+ * reactive-execute dispatch path (ADR-004).
+ *
+ * Graph derivation and resolution functions are pure (no filesystem access).
+ * The `loadSliceTaskIO` loader at the bottom is the only async/IO function.
+ */
+import { loadFile, parsePlan, parseTaskPlanIO } from "./files.js";
+import { resolveTasksDir, resolveTaskFiles } from "./paths.js";
+import { join } from "node:path";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { existsSync, unlinkSync } from "node:fs";
+// ─── Graph Construction ───────────────────────────────────────────────────
+/**
+ * Build a dependency graph from task IO signatures.
+ *
+ * A task T_b depends on T_a when any of T_b's inputFiles appear in T_a's
+ * outputFiles. Self-references are excluded.
+ *
+ * Tasks are returned in the same order as the input array.
+ */
+export function deriveTaskGraph(tasks) {
+    // Build output → producer lookup
+    const outputToProducer = new Map();
+    for (const task of tasks) {
+        for (const outFile of task.outputFiles) {
+            const existing = outputToProducer.get(outFile);
+            if (existing) {
+                existing.push(task.id);
+            }
+            else {
+                outputToProducer.set(outFile, [task.id]);
+            }
+        }
+    }
+    return tasks.map((task) => {
+        const deps = new Set();
+        for (const inFile of task.inputFiles) {
+            const producers = outputToProducer.get(inFile);
+            if (producers) {
+                for (const pid of producers) {
+                    if (pid !== task.id)
+                        deps.add(pid);
+                }
+            }
+        }
+        return {
+            ...task,
+            dependsOn: [...deps].sort(),
+        };
+    });
+}
+// ─── Ready Set Resolution ─────────────────────────────────────────────────
+/**
+ * Return task IDs whose dependencies are all in `completed`.
+ * Excludes tasks that are already done or in-flight.
+ */
+export function getReadyTasks(graph, completed, inFlight) {
+    return graph
+        .filter((node) => {
+        if (node.done || completed.has(node.id) || inFlight.has(node.id))
+            return false;
+        return node.dependsOn.every((dep) => completed.has(dep));
+    })
+        .map((node) => node.id);
+}
+// ─── Conflict-Free Subset Selection ──────────────────────────────────────
+/**
+ * Greedy selection of non-conflicting tasks up to `maxParallel`.
+ *
+ * Two tasks conflict if they share any outputFile. We also exclude tasks
+ * whose outputs overlap with `inFlightOutputs` (files being written by
+ * tasks currently in progress).
+ */
+export function chooseNonConflictingSubset(readyIds, graph, maxParallel, inFlightOutputs) {
+    const nodeMap = new Map(graph.map((n) => [n.id, n]));
+    const claimed = new Set(inFlightOutputs);
+    const selected = [];
+    for (const id of readyIds) {
+        if (selected.length >= maxParallel)
+            break;
+        const node = nodeMap.get(id);
+        if (!node)
+            continue;
+        // Check for output overlap with already-selected or in-flight
+        const conflicts = node.outputFiles.some((f) => claimed.has(f));
+        if (conflicts)
+            continue;
+        // Claim this task's outputs
+        for (const f of node.outputFiles)
+            claimed.add(f);
+        selected.push(id);
+    }
+    return selected;
+}
+// ─── Graph Quality Checks ─────────────────────────────────────────────────
+/**
+ * Returns true if any incomplete task has 0 inputFiles AND 0 outputFiles.
+ *
+ * An ambiguous graph means IO annotations are too sparse to derive reliable
+ * edges — the dispatcher should fall back to sequential execution.
+ */
+export function isGraphAmbiguous(graph) {
+    return graph.some((node) => !node.done &&
+        node.inputFiles.length === 0 &&
+        node.outputFiles.length === 0);
+}
+/**
+ * Detect deadlock: no tasks are ready and none are in-flight, yet incomplete
+ * tasks remain. This indicates a circular dependency or impossible state.
+ */
+export function detectDeadlock(graph, completed, inFlight) {
+    const incomplete = graph.filter((n) => !n.done && !completed.has(n.id) && !inFlight.has(n.id));
+    if (incomplete.length === 0)
+        return false; // all done
+    if (inFlight.size > 0)
+        return false; // something is running, wait for it
+    // Nothing in flight, but incomplete tasks remain — check if any are ready
+    const ready = getReadyTasks(graph, completed, inFlight);
+    return ready.length === 0;
+}
+// ─── Graph Metrics ────────────────────────────────────────────────────────
+/** Compute summary metrics for logging. */
+export function graphMetrics(graph) {
+    const completed = new Set(graph.filter((n) => n.done).map((n) => n.id));
+    const ready = getReadyTasks(graph, completed, new Set());
+    const edgeCount = graph.reduce((sum, n) => sum + n.dependsOn.length, 0);
+    return {
+        taskCount: graph.length,
+        edgeCount,
+        readySetSize: ready.length,
+        ambiguous: isGraphAmbiguous(graph),
+    };
+}
+// ─── IO Loader (async, filesystem) ────────────────────────────────────────
+/**
+ * Load TaskIO for all tasks in a slice by reading the slice plan (for done
+ * status and task IDs) and individual task plan files (for IO sections).
+ *
+ * Returns [] when the slice plan or tasks directory doesn't exist.
+ */
+export async function loadSliceTaskIO(basePath, mid, sid) {
+    const { resolveSliceFile } = await import("./paths.js");
+    const slicePlanPath = resolveSliceFile(basePath, mid, sid, "PLAN");
+    const planContent = slicePlanPath ? await loadFile(slicePlanPath) : null;
+    if (!planContent)
+        return [];
+    const plan = parsePlan(planContent);
+    const tDir = resolveTasksDir(basePath, mid, sid);
+    if (!tDir)
+        return [];
+    const results = [];
+    for (const taskEntry of plan.tasks) {
+        const planFiles = resolveTaskFiles(tDir, "PLAN");
+        const taskFileName = planFiles.find((f) => f.toUpperCase().startsWith(taskEntry.id.toUpperCase() + "-"));
+        if (!taskFileName) {
+            // Task plan file missing — include with empty IO (will trigger ambiguous)
+            results.push({
+                id: taskEntry.id,
+                title: taskEntry.title,
+                inputFiles: [],
+                outputFiles: [],
+                done: taskEntry.done,
+            });
+            continue;
+        }
+        const taskContent = await loadFile(join(tDir, taskFileName));
+        if (!taskContent) {
+            results.push({
+                id: taskEntry.id,
+                title: taskEntry.title,
+                inputFiles: [],
+                outputFiles: [],
+                done: taskEntry.done,
+            });
+            continue;
+        }
+        const io = parseTaskPlanIO(taskContent);
+        results.push({
+            id: taskEntry.id,
+            title: taskEntry.title,
+            inputFiles: io.inputFiles,
+            outputFiles: io.outputFiles,
+            done: taskEntry.done,
+        });
+    }
+    return results;
+}
+// ─── State Persistence ────────────────────────────────────────────────────
+function reactiveStatePath(basePath, mid, sid) {
+    return join(basePath, ".gsd", "runtime", `${mid}-${sid}-reactive.json`);
+}
+function isReactiveState(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const d = data;
+    return typeof d.sliceId === "string" && Array.isArray(d.completed) && Array.isArray(d.dispatched);
+}
+/**
+ * Load persisted reactive execution state for a slice.
+ * Returns null when no state file exists or the file is invalid.
+ */
+export function loadReactiveState(basePath, mid, sid) {
+    return loadJsonFileOrNull(reactiveStatePath(basePath, mid, sid), isReactiveState);
+}
+/**
+ * Save reactive execution state to disk.
+ */
+export function saveReactiveState(basePath, mid, sid, state) {
+    saveJsonFile(reactiveStatePath(basePath, mid, sid), state);
+}
+/**
+ * Remove the reactive state file when a slice completes.
+ */
+export function clearReactiveState(basePath, mid, sid) {
+    const path = reactiveStatePath(basePath, mid, sid);
+    try {
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch {
+        // Non-fatal
+    }
+}

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';

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

@@ -42,11 +42,19 @@ estimated_files: {{estimatedFiles}}
 
 ## Inputs
 
+<!-- Every input MUST be a backtick-wrapped file path. These paths are machine-parsed to
+     derive task dependencies — vague descriptions without paths break dependency detection.
+     For the first task in a slice with no prior task outputs, list the existing source files
+     this task reads or modifies. -->
+
 - `{{filePath}}` — {{whatThisTaskNeedsFromPriorWork}}
-- {{priorTaskSummaryInsight}}
 
 ## Expected Output
 
-<!-- This task should produce a real increment toward making the slice goal/demo true. A full slice plan should not be able to mark every task complete while the claimed slice behavior still does not work at the stated proof level. -->
+<!-- Every output MUST be a backtick-wrapped file path — the specific files this task creates
+     or modifies. These paths are machine-parsed to derive task dependencies.
+     This task should produce a real increment toward making the slice goal/demo true. A full
+     slice plan should not be able to mark every task complete while the claimed slice behavior
+     still does not work at the stated proof level. -->
 
-- `{{filePath}}` — {{whatThisTaskShouldProduceOrModify}}
+- `{{filePath}}` — {{whatThisTaskCreatesOrModifies}}

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/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,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/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,12 @@
+/**
+ * GSD Welcome Screen
+ *
+ * Rendered to stderr before the TUI takes over.
+ * No box, no panels — logo with metadata alongside, dim hint below.
+ */
+export interface WelcomeScreenOptions {
+    version: string;
+    modelName?: string;
+    provider?: string;
+}
+export declare function printWelcomeScreen(opts: WelcomeScreenOptions): void;