gsd-pi 2.37.1 → 2.38.0-dev.4d4d14a

package/dist/resources/extensions/gsd/prompts/reactive-execute.md

@@ -0,0 +1,44 @@
+# Reactive Task Execution — Parallel Dispatch
+
+**Working directory:** `{{workingDirectory}}`
+**Milestone:** {{milestoneId}} — {{milestoneTitle}}
+**Slice:** {{sliceId}} — {{sliceTitle}}
+
+## Mission
+
+You are executing **multiple tasks in parallel** for this slice. The task graph below shows which tasks are ready for simultaneous execution based on their input/output dependencies.
+
+**Critical rule:** Use the `subagent` tool in **parallel mode** to dispatch all ready tasks simultaneously. Each subagent gets a full `execute-task` prompt and is responsible for its own implementation, verification, task summary, and checkbox updates. The parent batch agent orchestrates, verifies, and records failures only when a dispatched task failed before it could leave its own summary behind.
+
+## Task Dependency Graph
+
+{{graphContext}}
+
+## Ready Tasks for Parallel Dispatch
+
+{{readyTaskCount}} tasks are ready for parallel execution:
+
+{{readyTaskList}}
+
+## Execution Protocol
+
+1. **Dispatch all ready tasks** using `subagent` in parallel mode. Each subagent prompt is provided below.
+2. **Wait for all subagents** to complete.
+3. **Verify each dispatched task's outputs** — check that expected files were created/modified, that verification commands pass where applicable, and that each task wrote its own `T##-SUMMARY.md`.
+4. **Do not rewrite successful task summaries or duplicate checkbox edits.** Treat a subagent-written summary as authoritative for that task.
+5. **If a failed task produced no summary, write a recovery summary for that task** with `blocker_discovered: true`, clear failure details, and leave the task unchecked so replan/retry has an authoritative record.
+6. **Preserve successful sibling tasks exactly as they landed.** Do not roll back good work because another parallel task failed.
+7. **Do NOT create a batch commit.** The surrounding unit lifecycle owns commits; this parent batch agent should not invent a second commit layer.
+8. **Report the batch outcome** — which tasks succeeded, which failed, and any output collisions or dependency surprises.
+
+If any subagent fails:
+- Keep successful task summaries and checkbox updates as-is
+- Write a failure summary only when the failed task did not leave one behind
+- Do not silently discard or overwrite another task's outputs
+- The orchestrator will handle re-dispatch or replanning on the next iteration
+
+## Subagent Prompts
+
+{{subagentPrompts}}
+
+{{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/run-uat.md

@@ -18,32 +18,47 @@ If a `GSD Skill Preferences` block is present in system context, use it to decid
 
 **UAT file:** `{{uatPath}}`
 **Result file to write:** `{{uatResultPath}}`
+**Detected UAT mode:** `{{uatType}}`
 
-You are the test runner. Execute every check defined in `{{uatPath}}` directly:
+You are the UAT runner. Execute every check defined in `{{uatPath}}` as deeply as this mode truthfully allows. Do not collapse live or subjective checks into cheap artifact checks just to get a PASS.
+
+### Automation rules by mode
+
+- `artifact-driven` — verify with shell commands, scripts, file reads, and artifact structure checks.
+- `live-runtime` — exercise the real runtime path. Start or connect to the app/service if needed, use browser/runtime/network checks, and verify observable behavior.
+- `mixed` — run all automatable artifact-driven and live-runtime checks. Separate any remaining human-only checks explicitly.
+- `human-experience` — automate setup, preconditions, screenshots, logs, and objective checks, but do **not** invent subjective PASS results. Mark taste-based, experiential, or purely human-judgment checks as `NEEDS-HUMAN` and use an overall verdict of `PARTIAL` unless every required check was objective and passed.
+
+### Evidence tools
+
+Choose the lightest tool that proves the check honestly:
 
 - Run shell commands with `bash`
 - Run `grep` / `rg` checks against files
-- Run `node` / script invocations
+- Run `node` / other script invocations
 - Read files and verify their contents
 - Check that expected artifacts exist and have correct structure
+- For live/runtime/UI checks, exercise the real flow in the browser when applicable and inspect runtime/network/console state
+- When a check cannot be honestly automated, gather the best objective evidence you can and mark it `NEEDS-HUMAN`
 
 For each check, record:
 - The check description (from the UAT file)
+- The evidence mode used: `artifact`, `runtime`, or `human-follow-up`
 - The command or action taken
 - The actual result observed
-- PASS or FAIL verdict
+- `PASS`, `FAIL`, or `NEEDS-HUMAN`
 
 After running all checks, compute the **overall verdict**:
-- `PASS` — all checks passed
+- `PASS` — all required checks passed and no human-only checks remain
 - `FAIL` — one or more checks failed
-- `PARTIAL` — some checks passed, some failed or were skipped
+- `PARTIAL` — some checks passed, but one or more checks were skipped, inconclusive, or still require human judgment
 
 Write `{{uatResultPath}}` with:
 
 ```markdown
 ---
 sliceId: {{sliceId}}
-uatType: artifact-driven
+uatType: {{uatType}}
 verdict: PASS | FAIL | PARTIAL
 date: <ISO 8601 timestamp>
 ---
@@ -52,9 +67,9 @@ date: <ISO 8601 timestamp>
 
 ## Checks
 
-| Check | Result | Notes |
-|-------|--------|-------|
-| <check description> | PASS / FAIL | <observed output or reason> |
+| Check | Mode | Result | Notes |
+|-------|------|--------|-------|
+| <check description> | artifact / runtime / human-follow-up | PASS / FAIL / NEEDS-HUMAN | <observed output, evidence, or reason> |
 
 ## Overall Verdict
 
@@ -62,7 +77,7 @@ date: <ISO 8601 timestamp>
 
 ## Notes
 
-<any additional context, errors encountered, or follow-up items>
+<any additional context, errors encountered, screenshots/logs gathered, or manual follow-up still required>
 ```
 
 ---

package/dist/resources/extensions/gsd/prompts/workflow-start.md

@@ -14,7 +14,7 @@ You are executing a **{{templateName}}** workflow (template: `{{templateId}}`).
 
 ## Workflow Definition
 
-Follow the workflow defined below. Execute each phase in order, completing one before moving to the next. At each phase gate, confirm with the user before proceeding.
+Follow the workflow defined below. Execute each phase in order, completing one before moving to the next. For low and medium complexity workflows, keep moving by default — pause only at true decision gates (user must choose between materially different directions, outward-facing actions need approval, or the workflow explicitly requires a human checkpoint). For high complexity workflows, confirm at phase transitions unless the workflow explicitly marks a gate as skip-safe.
 
 {{workflowContent}}
 
@@ -24,5 +24,5 @@ Follow the workflow defined below. Execute each phase in order, completing one b
 2. **Artifact discipline.** If an artifact directory is specified, write all planning/summary documents there.
 3. **Atomic commits.** Commit working code after each meaningful change. Use conventional commit format: `<type>(<scope>): <description>`.
 4. **Verify before shipping.** Run the project's test suite and build before marking the workflow complete.
-5. **Gate between phases.** After each phase, summarize what was done and ask the user to confirm before moving to the next phase.
+5. **Decision gates, not ceremony.** After each phase, summarize what changed. For low/medium complexity, ask for confirmation only when the next phase depends on a real user choice or external approval. For high complexity, confirm before proceeding to each new phase.
 6. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.

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