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

package/src/resources/extensions/gsd/tests/skill-activation.test.ts

@@ -0,0 +1,140 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { loadSkills } from "@gsd/pi-coding-agent";
+import { buildSkillActivationBlock } from "../auto-prompts.js";
+import type { GSDPreferences } from "../preferences.js";
+
+function makeTempBase(): string {
+  return mkdtempSync(join(tmpdir(), "gsd-skill-activation-"));
+}
+
+function cleanup(base: string): void {
+  rmSync(base, { recursive: true, force: true });
+}
+
+function writeSkill(base: string, name: string, description: string): void {
+  const dir = join(base, "skills", name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n`);
+}
+
+function loadOnlyTestSkills(base: string): void {
+  loadSkills({ cwd: base, includeDefaults: false, skillPaths: [join(base, "skills")] });
+}
+
+function buildBlock(
+  base: string,
+  params: Partial<Parameters<typeof buildSkillActivationBlock>[0]> = {},
+  preferences: GSDPreferences = {},
+): string {
+  return buildSkillActivationBlock({
+    base,
+    milestoneId: "M001",
+    sliceId: "S01",
+    ...params,
+    preferences,
+  });
+}
+
+test("buildSkillActivationBlock matches installed skills from task context", () => {
+  const base = makeTempBase();
+  try {
+    writeSkill(base, "react", "Use for React components, hooks, JSX, and frontend UI work.");
+    writeSkill(base, "swiftui", "Use for SwiftUI views, iOS layout, and Apple platform UI work.");
+    loadOnlyTestSkills(base);
+
+    const result = buildBlock(base, {
+      sliceTitle: "Build React dashboard",
+      taskId: "T01",
+      taskTitle: "Implement React settings panel",
+    });
+
+    assert.match(result, /<skill_activation>/);
+    assert.match(result, /Call Skill\('react'\)/);
+    assert.doesNotMatch(result, /swiftui/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("buildSkillActivationBlock includes always_use_skills from preferences using exact Skill tool format", () => {
+  const base = makeTempBase();
+  try {
+    writeSkill(base, "swift-testing", "Use for Swift Testing assertions and verification patterns.");
+    loadOnlyTestSkills(base);
+
+    const result = buildBlock(base, { taskTitle: "Unrelated task title" }, {
+      always_use_skills: ["swift-testing"],
+    });
+
+    assert.equal(result, "<skill_activation>Call Skill('swift-testing').</skill_activation>");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("buildSkillActivationBlock includes skill_rules matches and task-plan skills_used", () => {
+  const base = makeTempBase();
+  try {
+    writeSkill(base, "prisma", "Use for Prisma schema, migrations, and ORM queries.");
+    writeSkill(base, "accessibility", "Use for accessibility, aria attributes, and keyboard support.");
+    loadOnlyTestSkills(base);
+
+    const taskPlan = [
+      "---",
+      "skills_used:",
+      "  - accessibility",
+      "---",
+      "# T01: Example",
+    ].join("\n");
+
+    const result = buildBlock(base, {
+      taskTitle: "Update prisma schema",
+      taskPlanContent: taskPlan,
+    }, {
+      skill_rules: [{ when: "prisma database schema", use: ["prisma"] }],
+    });
+
+    assert.match(result, /Call Skill\('accessibility'\)/);
+    assert.match(result, /Call Skill\('prisma'\)/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("buildSkillActivationBlock honors avoid_skills", () => {
+  const base = makeTempBase();
+  try {
+    writeSkill(base, "react", "Use for React components and frontend UI work.");
+    loadOnlyTestSkills(base);
+
+    const result = buildBlock(base, {
+      taskTitle: "Implement React settings panel",
+    }, {
+      avoid_skills: ["react"],
+    });
+
+    assert.equal(result, "");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("buildSkillActivationBlock falls back cleanly when nothing matches", () => {
+  const base = makeTempBase();
+  try {
+    writeSkill(base, "swiftui", "Use for SwiftUI apps.");
+    loadOnlyTestSkills(base);
+
+    const result = buildBlock(base, {
+      taskTitle: "Plain text docs task",
+    });
+
+    assert.equal(result, "");
+  } finally {
+    cleanup(base);
+  }
+});

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

@@ -422,25 +422,25 @@ assertTrue(
   "overlay has 10 tab labels",
 );
 
-// Verify commands.ts integration
-const commandsPath = join(__dirname, "..", "commands.ts");
-const commandsSrc = readFileSync(commandsPath, "utf-8");
+// Verify commands/handlers/core.ts integration
+const coreHandlerPath = join(__dirname, "..", "commands", "handlers", "core.ts");
+const coreHandlerSrc = readFileSync(coreHandlerPath, "utf-8");
 
-console.log("\n=== commands.ts integration ===");
+console.log("\n=== commands/handlers/core.ts integration ===");
 
 assertTrue(
-  commandsSrc.includes('"visualize"'),
-  "commands.ts has visualize in subcommands array",
+  coreHandlerSrc.includes('"visualize"'),
+  "core.ts has visualize in subcommands array",
 );
 
 assertTrue(
-  commandsSrc.includes("GSDVisualizerOverlay"),
-  "commands.ts imports GSDVisualizerOverlay",
+  coreHandlerSrc.includes("GSDVisualizerOverlay"),
+  "core.ts imports GSDVisualizerOverlay",
 );
 
 assertTrue(
-  commandsSrc.includes("handleVisualize"),
-  "commands.ts has handleVisualize handler",
+  coreHandlerSrc.includes("handleVisualize"),
+  "core.ts has handleVisualize handler",
 );
 
 report();

package/src/resources/extensions/gsd/tests/worktree.test.ts

@@ -11,6 +11,7 @@ import {
   getMainBranch,
   getSliceBranchName,
   parseSliceBranch,
+  resolveProjectRoot,
   setActiveMilestoneId,
   SLICE_BRANCH_RE,
 } from "../worktree.ts";
@@ -165,6 +166,52 @@ async function main(): Promise<void> {
     rmSync(repo, { recursive: true, force: true });
   }
 
+  // ── detectWorktreeName: symlink-resolved paths ───────────────────────────
+  console.log("\n=== detectWorktreeName (symlink-resolved paths) ===");
+  assertEq(
+    detectWorktreeName("/Users/fran/.gsd/projects/89e1c9ad49bf/worktrees/M001"),
+    "M001",
+    "detects milestone in symlink-resolved path",
+  );
+  assertEq(
+    detectWorktreeName("/Users/fran/.gsd/projects/abc123/worktrees/M002/subdir"),
+    "M002",
+    "detects milestone with trailing subdir in symlink-resolved path",
+  );
+  assertEq(
+    detectWorktreeName("/Users/fran/.gsd/projects/abc123"),
+    null,
+    "returns null for project root without worktrees segment",
+  );
+  assertEq(
+    detectWorktreeName("/foo/.gsd/worktrees/M001"),
+    "M001",
+    "still detects direct layout path",
+  );
+
+  // ── resolveProjectRoot: symlink-resolved paths ──────────────────────────
+  console.log("\n=== resolveProjectRoot (symlink-resolved paths) ===");
+  assertEq(
+    resolveProjectRoot("/Users/fran/.gsd/projects/89e1c9ad49bf/worktrees/M001"),
+    "/Users/fran",
+    "resolves to user home for symlink-resolved path",
+  );
+  assertEq(
+    resolveProjectRoot("/foo/.gsd/worktrees/M001"),
+    "/foo",
+    "still resolves direct layout path",
+  );
+  assertEq(
+    resolveProjectRoot("/some/repo"),
+    "/some/repo",
+    "returns unchanged for non-worktree path",
+  );
+  assertEq(
+    resolveProjectRoot("/data/.gsd/projects/deadbeef/worktrees/M003/nested"),
+    "/data",
+    "resolves correctly with nested subdirs after worktree name",
+  );
+
   rmSync(base, { recursive: true, force: true });
   report();
 }

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

@@ -61,6 +61,16 @@ export interface TaskPlanEntry {
   verify?: string; // e.g. "run tests" — extracted from "- Verify:" subline
 }
 
+export interface TaskPlanFrontmatter {
+  estimated_steps?: number; // optional scope estimate for plan quality validator
+  estimated_files?: number; // optional file-count estimate for scope warning heuristics
+  skills_used: string[]; // installed skill slugs/names to hand off to execute-task prompts
+}
+
+export interface TaskPlanFile {
+  frontmatter: TaskPlanFrontmatter;
+}
+
 // ─── Verification Gate ─────────────────────────────────────────────────────
 
 /** Result of a single verification command execution */
@@ -423,7 +433,6 @@ export interface Requirement {
 
 // ─── Parallel Orchestration Types ────────────────────────────────────────
 
-export type CompressionStrategy = "truncate" | "compress";
 export type ContextSelectionMode = "full" | "smart";
 
 export type MergeStrategy = "per-slice" | "per-milestone";
@@ -479,3 +488,11 @@ export interface ReactiveExecutionState {
   };
   updatedAt: string;
 }
+
+export interface BrowserFlowResult {
+  url: string;
+  passed: boolean;
+  checksTotal: number;
+  checksPassed: number;
+  duration: number;
+}

package/src/resources/extensions/gsd/verification-evidence.ts

@@ -37,6 +37,21 @@ export interface AuditWarningJSON {
   fixAvailable: boolean;
 }
 
+export interface BrowserEvidenceCheckJSON {
+  description: string;
+  passed: boolean;
+  actual?: string;
+  evidence?: string;
+  error?: string;
+}
+
+export interface BrowserEvidenceJSON {
+  url: string;
+  passed: boolean;
+  checks: BrowserEvidenceCheckJSON[];
+  duration: number;
+}
+
 export interface EvidenceJSON {
   schemaVersion: 1;
   taskId: string;
@@ -49,6 +64,7 @@ export interface EvidenceJSON {
   maxRetries?: number;
   runtimeErrors?: RuntimeErrorJSON[];
   auditWarnings?: AuditWarningJSON[];
+  browser?: BrowserEvidenceJSON;
 }
 
 /**

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

@@ -1,10 +1,11 @@
 // 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,
@@ -21,6 +22,8 @@ import { loadEffectiveGSDPreferences } from './preferences.js';
 import { runProviderChecks, type ProviderCheckResult } from './doctor-providers.js';
 import { generateSkillHealthReport } from './skill-health.js';
 import { runEnvironmentChecks, type EnvironmentCheckResult } from './doctor-environment.js';
+import { computeProgressScore } from './progress-score.js';
+import { getHealthHistory } from './doctor-proactive.js';
 
 import type { Phase } from './types.js';
 import type { CaptureEntry } from './captures.js';
@@ -161,6 +164,27 @@ export interface SkillSummaryInfo {
   topIssue: string | null;
 }
 
+/** A single doctor history entry for visualizer display. */
+export interface VisualizerDoctorEntry {
+  ts: string;
+  ok: boolean;
+  errors: number;
+  warnings: number;
+  fixes: number;
+  codes: string[];
+  issues?: Array<{ severity: string; code: string; message: string; unitId: string }>;
+  fixDescriptions?: string[];
+  scope?: string;
+  summary?: string;
+}
+
+/** Current progress score snapshot for health display. */
+export interface VisualizerProgressScore {
+  level: "green" | "yellow" | "red";
+  summary: string;
+  signals: Array<{ kind: "positive" | "negative" | "neutral"; label: string }>;
+}
+
 export interface HealthInfo {
   budgetCeiling: number | undefined;
   tokenProfile: string;
@@ -174,6 +198,10 @@ export interface HealthInfo {
   providers: ProviderStatusSummary[];
   skillSummary: SkillSummaryInfo;
   environmentIssues: import("./doctor-environment.js").EnvironmentCheckResult[];
+  /** Persisted doctor run history (most recent first, up to 20 entries). */
+  doctorHistory?: VisualizerDoctorEntry[];
+  /** Current in-memory progress score (null if auto-mode not active). */
+  progressScore?: VisualizerProgressScore | null;
 }
 
 export interface VisualizerData {
@@ -608,6 +636,26 @@ function loadHealth(units: UnitMetrics[], totals: ProjectTotals | null, 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: VisualizerDoctorEntry[] = [];
+  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) as VisualizerDoctorEntry);
+    }
+  } catch { /* non-fatal */ }
+
+  // Current progress score — only meaningful when auto-mode has health data
+  let progressScore: VisualizerProgressScore | null = 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,
@@ -621,6 +669,8 @@ function loadHealth(units: UnitMetrics[], totals: ProjectTotals | null, basePath
     providers,
     skillSummary,
     environmentIssues,
+    doctorHistory,
+    progressScore,
   };
 }
 

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

@@ -1150,6 +1150,64 @@ export function renderHealthView(
     }
   }
 
+  // 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/src/resources/extensions/gsd/worktree.ts

@@ -67,40 +67,60 @@ export function captureIntegrationBranch(basePath: string, milestoneId: string,
 
 // ─── 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: string): { gsdIdx: number; afterWorktrees: number } | null {
+  // 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: string): string | null {
   const normalizedPath = basePath.replaceAll("\\", "/");
-  const marker = "/.gsd/worktrees/";
-  const idx = normalizedPath.indexOf(marker);
-  if (idx === -1) return null;
-  const afterMarker = normalizedPath.slice(idx + marker.length);
+  const seg = findWorktreeSegment(normalizedPath);
+  if (!seg) return null;
+  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: string): string {
   const normalizedPath = basePath.replaceAll("\\", "/");
-  const marker = "/.gsd/worktrees/";
-  const idx = normalizedPath.indexOf(marker);
-  if (idx === -1) return basePath;
-  // Return the original path up to the .gsd/ marker (un-normalized)
-  // Account for potential OS-specific separators
+  const seg = findWorktreeSegment(normalizedPath);
+  if (!seg) return basePath;
+  // 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);
 }
 
 /**

package/src/resources/extensions/mcp-client/index.ts

@@ -114,6 +114,22 @@ function getServerConfig(name: string): McpServerConfig | undefined {
 	return readConfigs().find((s) => s.name === name);
 }
 
+/** Resolve ${VAR} references in env values against process.env. */
+function resolveEnv(env: Record<string, string>): Record<string, string> {
+	const resolved: Record<string, string> = {};
+	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: string, signal?: AbortSignal): Promise<Client> {
 	const existing = connections.get(name);
 	if (existing) return existing.client;
@@ -128,7 +144,7 @@ async function getOrConnect(name: string, signal?: AbortSignal): Promise<Client>
 		transport = new StdioClientTransport({
 			command: config.command,
 			args: config.args,
-			env: config.env ? { ...process.env, ...config.env } as Record<string, string> : undefined,
+			env: config.env ? { ...process.env, ...resolveEnv(config.env) } as Record<string, string> : undefined,
 			cwd: config.cwd,
 			stderr: "pipe",
 		});

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

@@ -7,6 +7,10 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { readPromptRecord } from "./store.js";
 
+function getGsdHome(): string {
+  return process.env.GSD_HOME || join(homedir(), ".gsd");
+}
+
 export interface LatestPromptSummary {
   id: string;
   status: string;
@@ -14,7 +18,7 @@ export interface LatestPromptSummary {
 }
 
 export function getLatestPromptSummary(): LatestPromptSummary | null {
-  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"));
   if (files.length === 0) return null;

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

@@ -7,8 +7,12 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import type { RemotePrompt, RemotePromptRecord, RemotePromptRef, RemoteAnswer, RemotePromptStatus } from "./types.js";
 
+function getGsdHome(): string {
+  return process.env.GSD_HOME || join(homedir(), ".gsd");
+}
+
 function runtimeDir(): string {
-  return join(homedir(), ".gsd", "runtime", "remote-questions");
+  return join(getGsdHome(), "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/shared/frontmatter.ts

@@ -50,7 +50,7 @@ export function parseFrontmatterMap(lines: string[]): Record<string, unknown> {
     }
 
     // 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/src/resources/extensions/subagent/index.ts

@@ -452,7 +452,7 @@ async function runSingleAgent(
 
 async function runSingleAgentInCmuxSplit(
 	cmuxClient: CmuxClient,
-	direction: "right" | "down",
+	directionOrSurfaceId: "right" | "down" | string,
 	defaultCwd: string,
 	agents: AgentConfig[],
 	agentName: string,
@@ -503,7 +503,12 @@ async function runSingleAgentInCmuxSplit(
 		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 as "right" | "down" | "left" | "up")
+			: directionOrSurfaceId;
 		if (!cmuxSurfaceId) {
 			return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails);
 		}
@@ -806,12 +811,16 @@ export default function (pi: ExtensionAPI) {
 				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",
+							gridSurfaces[index] ?? (index % 2 === 0 ? "right" : "down"),
 							ctx.cwd,
 							agents,
 							t.agent,