gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.8a893322c

package/src/resources/extensions/gsd/tests/worktree-symlink-removal.test.ts

@@ -20,7 +20,7 @@ import {
   listWorktrees,
   worktreePath,
 } from "../worktree-manager.ts";
-import { describe, test } from 'node:test';
+import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
 
@@ -28,37 +28,41 @@ function run(command: string, cwd: string): string {
   return execSync(command, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
 }
 
-// Set up a test repo with .gsd/ as a symlink to an external directory,
-// mimicking the external state directory layout (~/.gsd/projects/<hash>/).
-// Resolve tmpdir to handle macOS /tmp -> /private/var/... symlink.
-const realTmp = realpathSync(tmpdir());
-const base = mkdtempSync(join(realTmp, "gsd-wt-symlink-test-"));
-const externalState = mkdtempSync(join(realTmp, "gsd-wt-symlink-ext-"));
-
-run("git init -b main", base);
-run('git config user.name "Test"', base);
-run('git config user.email "test@example.com"', base);
-
-// Create external state directory structure
-mkdirSync(join(externalState, "worktrees"), { recursive: true });
-
-// Create .gsd as a symlink to the external state directory
-symlinkSync(externalState, join(base, ".gsd"));
-
-// Verify the symlink is in place
-assert.ok(existsSync(join(base, ".gsd")), ".gsd symlink exists");
-assert.ok(
-  realpathSync(join(base, ".gsd")) === externalState,
-  ".gsd resolves to external state dir",
-);
+test('worktree-symlink-removal removes the git-registered symlink target safely', (t) => {
+  console.log("\n=== #1852: removeWorktree with symlinked .gsd/ ===");
 
-// Create initial commit so we have a valid repo
-writeFileSync(join(base, "README.md"), "# Test\n", "utf-8");
-run("git add .", base);
-run('git commit -m "init"', base);
+  // Set up a test repo with .gsd/ as a symlink to an external directory,
+  // mimicking the external state directory layout (~/.gsd/projects/<hash>/).
+  // Resolve tmpdir to handle macOS /tmp -> /private/var/... symlink.
+  const realTmp = realpathSync(tmpdir());
+  const base = mkdtempSync(join(realTmp, "gsd-wt-symlink-test-"));
+  const externalState = mkdtempSync(join(realTmp, "gsd-wt-symlink-ext-"));
+  t.after(() => {
+    rmSync(base, { recursive: true, force: true });
+    rmSync(externalState, { recursive: true, force: true });
+  });
+
+  run("git init -b main", base);
+  run('git config user.name "Test"', base);
+  run('git config user.email "test@example.com"', base);
+
+  // Create external state directory structure
+  mkdirSync(join(externalState, "worktrees"), { recursive: true });
+
+  // Create .gsd as a symlink to the external state directory
+  symlinkSync(externalState, join(base, ".gsd"));
+
+  // Verify the symlink is in place
+  assert.ok(existsSync(join(base, ".gsd")), ".gsd symlink exists");
+  assert.ok(
+    realpathSync(join(base, ".gsd")) === externalState,
+    ".gsd resolves to external state dir",
+  );
 
-describe('worktree-symlink-removal', async () => {
-  console.log("\n=== #1852: removeWorktree with symlinked .gsd/ ===");
+  // Create initial commit so we have a valid repo
+  writeFileSync(join(base, "README.md"), "# Test\n", "utf-8");
+  run("git add .", base);
+  run('git commit -m "init"', base);
 
   // Create a worktree — git will resolve the symlink and register
   // the worktree at the external path
@@ -127,7 +131,4 @@ describe('worktree-symlink-removal', async () => {
   const listed = listWorktrees(base);
   assert.deepStrictEqual(listed.length, 0, "no worktrees listed after removal");
 
-  // Cleanup
-  rmSync(base, { recursive: true, force: true });
-  rmSync(externalState, { recursive: true, force: true });
 });

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

@@ -255,6 +255,14 @@ describe('worktree', async () => {
     "returns unchanged for non-worktree path",
   );
 
+  const nestedRepoDir = join(base, "packages", "demo");
+  mkdirSync(nestedRepoDir, { recursive: true });
+  assert.deepStrictEqual(
+    normalizePath(resolveProjectRoot(nestedRepoDir)),
+    normalizePath(base),
+    "resolves normal repo subdirectories to the project root",
+  );
+
   // Without GSD_PROJECT_ROOT, direct layout with nested subdirs
   assert.deepStrictEqual(
     resolveProjectRoot("/data/.gsd/worktrees/M003/nested"),

package/src/resources/extensions/gsd/tests/write-gate-planning-unit.test.ts

@@ -9,12 +9,21 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { join, sep } from 'node:path';
 
-import { shouldBlockPlanningUnit } from '../bootstrap/write-gate.ts';
+import { ALLOWED_PLANNING_DISPATCH_AGENTS, shouldBlockPlanningUnit } from '../bootstrap/write-gate.ts';
+import { extractSubagentAgentClasses } from '../bootstrap/subagent-input.ts';
 import { isDeterministicPolicyError } from '../auto-tool-tracking.ts';
 import type { ToolsPolicy } from '../unit-context-manifest.ts';
 
 const BASE = join('/tmp', 'fake-project');
 const PLANNING: ToolsPolicy = { mode: 'planning' };
+const PLANNING_DISPATCH: ToolsPolicy = {
+  mode: 'planning-dispatch',
+  allowedSubagents: [...ALLOWED_PLANNING_DISPATCH_AGENTS],
+};
+const PLANNING_DISPATCH_REVIEW: ToolsPolicy = {
+  mode: 'planning-dispatch',
+  allowedSubagents: ['reviewer', 'security', 'tester'],
+};
 const READ_ONLY: ToolsPolicy = { mode: 'read-only' };
 const ALL: ToolsPolicy = { mode: 'all' };
 const DOCS: ToolsPolicy = {
@@ -143,6 +152,112 @@ test('planning-unit: blocks task tool (alt subagent name)', () => {
   assert.strictEqual(r.block, true);
 });
 
+test('planning-dispatch: allows subagent dispatch (delegated recon/planner during slice planning)', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, ['scout']);
+  assert.strictEqual(r.block, false);
+});
+
+test('planning-dispatch: allows task dispatch (delegated recon/planner during slice planning)', () => {
+  const r = shouldBlockPlanningUnit('task', '', BASE, 'plan-slice', PLANNING_DISPATCH, ['planner']);
+  assert.strictEqual(r.block, false);
+});
+
+test('planning-dispatch: extracts subagent classes from single, parallel, and chain inputs', () => {
+  assert.deepEqual(extractSubagentAgentClasses({ agent: ' scout ' }), ['scout']);
+  assert.deepEqual(
+    extractSubagentAgentClasses({ tasks: [{ agent: 'planner' }, { agent: ' tester ' }] }),
+    ['planner', 'tester'],
+  );
+  assert.deepEqual(
+    extractSubagentAgentClasses({ chain: [{ agent: 'reviewer' }, { agent: 'security' }] }),
+    ['reviewer', 'security'],
+  );
+});
+
+test('planning-dispatch: blocks subagent dispatch when agentClasses is undefined (stale caller shim)', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, undefined);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /stale caller/);
+  assert.match(r.reason!, /tools-policy "planning-dispatch"/);
+});
+
+test('planning-dispatch: allows explicitly empty agent classes for downstream validation', () => {
+  const emptyClasses = extractSubagentAgentClasses({});
+  assert.deepEqual(emptyClasses, []);
+  const empty = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, emptyClasses);
+  assert.strictEqual(empty.block, false);
+});
+
+test('planning-dispatch: allows all globally allowed specialists when listed by policy', () => {
+  const policy: ToolsPolicy = {
+    mode: 'planning-dispatch',
+    allowedSubagents: [...ALLOWED_PLANNING_DISPATCH_AGENTS],
+  };
+  const r = shouldBlockPlanningUnit(
+    'subagent',
+    '',
+    BASE,
+    'complete-milestone',
+    policy,
+    [...ALLOWED_PLANNING_DISPATCH_AGENTS],
+  );
+  assert.strictEqual(r.block, false);
+});
+
+test('planning-dispatch: blocks implementation-tier agent', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, ['worker']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"worker"/);
+  assert.match(r.reason!, /read-only specialists/);
+});
+
+test('planning-dispatch: blocks globally disallowed agent even if listed by policy', () => {
+  const policy: ToolsPolicy = {
+    mode: 'planning-dispatch',
+    allowedSubagents: ['refactorer'],
+  };
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'refine-slice', policy, ['refactorer']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"refactorer"/);
+  assert.match(r.reason!, /read-only specialists/);
+  assert.doesNotMatch(r.reason!, /ToolsPolicy\.allowedSubagents|permitted agents for this unit/);
+});
+
+test('planning-dispatch: blocks mixed batch containing a disallowed agent', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, ['scout', 'worker']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"worker"/);
+});
+
+test('planning-dispatch: allows review-tier agent under closeout policy', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'complete-slice', PLANNING_DISPATCH_REVIEW, ['reviewer']);
+  assert.strictEqual(r.block, false);
+});
+
+test('planning-dispatch: blocks recon agent under closeout policy', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'complete-slice', PLANNING_DISPATCH_REVIEW, ['scout']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"scout"/);
+  assert.match(r.reason!, /ToolsPolicy\.allowedSubagents|permitted agents for this unit/);
+  assert.doesNotMatch(r.reason!, /read-only specialists/);
+});
+
+test('planning-dispatch: still blocks writes to user source (write isolation preserved)', () => {
+  const r = shouldBlockPlanningUnit('write', join(BASE, 'src', 'main.ts'), BASE, 'plan-slice', PLANNING_DISPATCH);
+  assert.strictEqual(r.block, true);
+});
+
+test('planning-dispatch: still allows writes inside .gsd/', () => {
+  const r = shouldBlockPlanningUnit(
+    'write',
+    join(BASE, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'PLAN.md'),
+    BASE,
+    'plan-slice',
+    PLANNING_DISPATCH,
+  );
+  assert.strictEqual(r.block, false);
+});
+
 // ─── planning mode: pass-through tools ────────────────────────────────────
 
 test('planning-unit: allows read tool', () => {

package/src/resources/extensions/gsd/unit-context-manifest.ts

@@ -111,6 +111,12 @@ export type PreferencesPolicy = "none" | "active-only" | "full";
  *                    Task subagent dispatch denied. Catches the bug class
  *                    where a discuss-milestone turn modifies user source
  *                    files (forensics: ~/Github/test-apps/b23, #4934).
+ *   - "planning-dispatch"
+ *                  — Same read + .gsd/** write + safe-Bash surface as
+ *                    "planning", but permits controlled subagent dispatch
+ *                    only to the agents listed in the ToolsPolicy
+ *                    `allowedSubagents` field. See write-gate.ts for the
+ *                    runtime agent-class enforcement details.
  *   - "docs"       — Read tools always; writes restricted to .gsd/** AND
  *                    the explicit `allowedPathGlobs` set; Bash safe-allowlist;
  *                    no subagents. Reserved for rewrite-docs, which legitimately
@@ -125,6 +131,7 @@ export type ToolsPolicy =
   | { readonly mode: "all" }
   | { readonly mode: "read-only" }
   | { readonly mode: "planning" }
+  | { readonly mode: "planning-dispatch"; readonly allowedSubagents: readonly string[] }
   | { readonly mode: "docs"; readonly allowedPathGlobs: readonly string[] };
 
 // ─── Computed-artifact registry (#4924 v2 contract) ───────────────────────
@@ -268,6 +275,18 @@ const COMMON_BUDGET_SMALL = 250_000;    // ~65K tokens
 
 const TOOLS_ALL: ToolsPolicy = { mode: "all" };
 const TOOLS_PLANNING: ToolsPolicy = { mode: "planning" };
+// Like TOOLS_PLANNING but permits dispatch to read-only recon/planning
+// specialists. Runtime-enforced by write-gate.ts before the subagent tool runs.
+const TOOLS_PLANNING_DISPATCH_RECON: ToolsPolicy = {
+  mode: "planning-dispatch",
+  allowedSubagents: ["scout", "planner"],
+};
+// Like TOOLS_PLANNING_DISPATCH_RECON, but for closeout units that fan out
+// verification work to review-tier specialists.
+const TOOLS_PLANNING_DISPATCH_REVIEW: ToolsPolicy = {
+  mode: "planning-dispatch",
+  allowedSubagents: ["reviewer", "security", "tester"],
+};
 const TOOLS_DOCS: ToolsPolicy = {
   mode: "docs",
   // Globs are resolved relative to project basePath. The set is intentionally
@@ -376,7 +395,11 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // planning-dispatch: completion is a high-leverage place to fan out to
+    // reviewer / security / tester subagents. They read the diff and report
+    // findings; they do not write user source. Write isolation to .gsd/ is
+    // preserved.
+    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
     artifacts: {
       // #4780 landed slice-summary as excerpt for this unit; phase 2 of
       // the architecture will read this manifest as the source of truth
@@ -409,7 +432,10 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // planning-dispatch: allows subagent dispatch so the planner can fan out
+    // to scout for codebase recon and to planner/decompose-style specialists
+    // for sub-decomposition. Write-isolation to .gsd/ is preserved.
+    tools: TOOLS_PLANNING_DISPATCH_RECON,
     artifacts: {
       inline: ["roadmap", "slice-research", "dependency-summaries", "requirements", "decisions", "templates"],
       excerpt: [],
@@ -423,7 +449,10 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // See plan-slice — same rationale: dispatch to scout/planner-style
+    // specialists during refinement is materially better than re-doing recon
+    // inline.
+    tools: TOOLS_PLANNING_DISPATCH_RECON,
     artifacts: {
       inline: ["slice-plan", "slice-research", "dependency-summaries", "templates"],
       excerpt: [],
@@ -451,7 +480,10 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // See complete-milestone — same rationale: dispatch to reviewer / security /
+    // tester subagents to fan out review work without bloating this unit's
+    // context.
+    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
     artifacts: {
       // Phase 3 migration (#4782): matches today's actual
       // buildCompleteSlicePrompt inlining order. Overrides prepend +

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -39,6 +39,11 @@ import {
   nativeWorktreeRemove,
 } from "./native-git-bridge.js";
 import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
+import {
+  isGsdWorktreePath,
+  normalizeWorktreePathForCompare,
+  resolveWorktreeProjectRoot,
+} from "./worktree-root.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -75,6 +80,20 @@ function normalizePathForComparison(path: string): string {
   return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }
 
+function normalizeBasePathForWorktreeOps(basePath: string): string {
+  const resolved = resolveWorktreeProjectRoot(basePath);
+  if (
+    isGsdWorktreePath(basePath) &&
+    normalizeWorktreePathForCompare(resolved) === normalizeWorktreePathForCompare(basePath)
+  ) {
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Cannot resolve project root from worktree path: ${basePath}. Run the command from the project root or set GSD_PROJECT_ROOT.`,
+    );
+  }
+  return resolved;
+}
+
 // ─── resolveGitDir ─────────────────────────────────────────────────────────
 
 /**
@@ -106,7 +125,7 @@ export function resolveGitDir(basePath: string): string {
 }
 
 export function worktreesDir(basePath: string): string {
-  return join(basePath, ".gsd", "worktrees");
+  return join(resolveWorktreeProjectRoot(basePath), ".gsd", "worktrees");
 }
 
 export function worktreePath(basePath: string, name: string): string {
@@ -195,6 +214,8 @@ export function resolveCanonicalMilestoneRoot(
  * @param opts.branch — override the default `worktree/<name>` branch name
  */
 export function createWorktree(basePath: string, name: string, opts: { branch?: string; startPoint?: string; reuseExistingBranch?: boolean } = {}): WorktreeInfo {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   // Validate name: alphanumeric, hyphens, underscores only
   if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
     throw new GSDError(GSD_PARSE_ERROR, `Invalid worktree name "${name}". Use only letters, numbers, hyphens, and underscores.`);
@@ -297,6 +318,8 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
  * Uses native worktree list and filters to those under .gsd/worktrees/.
  */
 export function listWorktrees(basePath: string): WorktreeInfo[] {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const baseVariants = [resolve(basePath)];
   if (existsSync(basePath)) {
     baseVariants.push(realpathSync(basePath));
@@ -459,6 +482,8 @@ export function removeWorktree(
   name: string,
   opts: { deleteBranch?: boolean; force?: boolean; branch?: string } = {},
 ): void {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   let wtPath = worktreePath(basePath, name);
   const branch = opts.branch ?? worktreeBranchName(name);
   const { deleteBranch = true, force = true } = opts;
@@ -714,6 +739,8 @@ function parseDiffNameStatus(entries: { status: string; path: string }[]): Workt
  * Returns a summary of added, modified, and removed GSD artifacts.
  */
 export function diffWorktreeGSD(basePath: string, name: string): WorktreeDiffSummary {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -729,6 +756,8 @@ export function diffWorktreeGSD(basePath: string, name: string): WorktreeDiffSum
  * content, this correctly returns an empty diff.
  */
 export function diffWorktreeAll(basePath: string, name: string): WorktreeDiffSummary {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -742,6 +771,8 @@ export function diffWorktreeAll(basePath: string, name: string): WorktreeDiffSum
  * Uses direct diff (not merge-base) so the preview matches the actual merge outcome.
  */
 export function diffWorktreeNumstat(basePath: string, name: string): FileLineStat[] {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -760,6 +791,8 @@ export function diffWorktreeNumstat(basePath: string, name: string): FileLineSta
  * Returns the raw unified diff for LLM consumption.
  */
 export function getWorktreeGSDDiff(basePath: string, name: string): string {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -771,6 +804,8 @@ export function getWorktreeGSDDiff(basePath: string, name: string): string {
  * Returns the raw unified diff for LLM consumption.
  */
 export function getWorktreeCodeDiff(basePath: string, name: string): string {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -781,6 +816,8 @@ export function getWorktreeCodeDiff(basePath: string, name: string): string {
  * Get commit log for the worktree branch since it diverged from main.
  */
 export function getWorktreeLog(basePath: string, name: string): string {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
@@ -795,6 +832,8 @@ export function getWorktreeLog(basePath: string, name: string): string {
  * Returns the merge commit message.
  */
 export function mergeWorktreeToMain(basePath: string, name: string, commitMessage: string): string {
+  basePath = normalizeBasePathForWorktreeOps(basePath);
+
   const branch = worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
   const current = nativeGetCurrentBranch(basePath);

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -23,6 +23,7 @@ import { emitJournalEvent } from "./journal.js";
 import { emitWorktreeCreated, emitWorktreeMerged } from "./worktree-telemetry.js";
 import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain } from "./slice-cadence.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 // ─── Dependency Interface ──────────────────────────────────────────────────
 
@@ -84,31 +85,20 @@ export interface NotifyCtx {
 
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 
-/**
- * Worktree marker segment — present in any path produced by worktreePath().
- * Used to strip the worktree suffix and recover the project root (#3729).
- */
-const WORKTREE_MARKER = "/.gsd/worktrees/";
-
 /**
  * Resolve the project root from session path state.
  *
  * Prefers `originalBasePath` (always the project root when set), but falls
  * back to `basePath` when `originalBasePath` is falsy (e.g. fresh AutoSession
  * with default empty string). If `basePath` itself is inside a worktree
- * directory (contains `/.gsd/worktrees/`), strip that suffix to recover the
- * actual project root — preventing double-nested worktree paths (#3729).
+ * directory (including symlink-resolved ~/.gsd/projects/<hash>/worktrees
+ * paths), recover the actual project root to prevent double nesting (#3729).
  */
 export function resolveProjectRoot(
   originalBasePath: string,
   basePath: string,
 ): string {
-  let resolved = originalBasePath || basePath;
-  const markerIdx = resolved.indexOf(WORKTREE_MARKER);
-  if (markerIdx !== -1) {
-    resolved = resolved.slice(0, markerIdx);
-  }
-  return resolved;
+  return resolveWorktreeProjectRoot(basePath, originalBasePath);
 }
 
 // ─── WorktreeResolver ──────────────────────────────────────────────────────

package/src/resources/extensions/gsd/worktree-root.ts

@@ -0,0 +1,144 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export interface WorktreeSegment {
+  gsdIdx: number;
+  afterWorktrees: number;
+}
+
+export function normalizeWorktreePathForCompare(path: string): string {
+  let normalized: string;
+  try {
+    normalized = realpathSync(path);
+  } catch {
+    normalized = resolve(path);
+  }
+  const slashed = normalized.replaceAll("\\", "/");
+  const trimmed = slashed.replace(/\/+$/, "");
+  return process.platform === "win32" ? (trimmed || "/").toLowerCase() : (trimmed || "/");
+}
+
+/**
+ * Find the GSD worktree segment in both direct project layout and the
+ * symlink-resolved external-state layout used by ~/.gsd/projects/<hash>.
+ */
+export function findWorktreeSegment(normalizedPath: string): WorktreeSegment | null {
+  const directMarker = "/.gsd/worktrees/";
+  const directIdx = normalizedPath.indexOf(directMarker);
+  if (directIdx !== -1) {
+    return { gsdIdx: directIdx, afterWorktrees: directIdx + directMarker.length };
+  }
+
+  const externalRe = /\/\.gsd\/projects\/[^/]+\/worktrees\//;
+  const externalMatch = normalizedPath.match(externalRe);
+  if (externalMatch && externalMatch.index !== undefined) {
+    return {
+      gsdIdx: externalMatch.index,
+      afterWorktrees: externalMatch.index + externalMatch[0].length,
+    };
+  }
+
+  return null;
+}
+
+export function isGsdWorktreePath(path: string): boolean {
+  return findWorktreeSegment(path.replaceAll("\\", "/")) !== null;
+}
+
+/**
+ * Resolve the canonical project root for worktree operations.
+ *
+ * `originalBasePath` wins when available because session state already knows the
+ * root. `GSD_PROJECT_ROOT` is the next strongest signal for worker processes.
+ * Otherwise, derive the root from direct `.gsd/worktrees` paths, or recover it
+ * from the worktree `.git` file for symlink-resolved ~/.gsd/project paths.
+ */
+export function resolveWorktreeProjectRoot(
+  basePath: string,
+  originalBasePath?: string | null,
+): string {
+  const preferred =
+    originalBasePath?.trim() ||
+    process.env.GSD_PROJECT_ROOT?.trim() ||
+    basePath;
+
+  return resolveProjectRootFromPath(preferred);
+}
+
+function resolveProjectRootFromPath(path: string): string {
+  const normalizedPath = path.replaceAll("\\", "/");
+  const segment = findWorktreeSegment(normalizedPath);
+  if (!segment) return resolveGitWorkingTreeRoot(path) ?? path;
+
+  const sepChar = path.includes("\\") ? "\\" : "/";
+  const gsdMarker = `${sepChar}.gsd${sepChar}`;
+  const markerIdx = path.indexOf(gsdMarker);
+  const candidate = markerIdx !== -1
+    ? path.slice(0, markerIdx)
+    : path.slice(0, segment.gsdIdx);
+
+  const gsdHome = normalizeWorktreePathForCompare(process.env.GSD_HOME || join(homedir(), ".gsd"));
+  const candidateGsdPath = normalizeWorktreePathForCompare(join(candidate, ".gsd"));
+
+  if (candidateGsdPath === gsdHome || candidateGsdPath.startsWith(`${gsdHome}/`)) {
+    const realRoot = resolveProjectRootFromGitFile(path);
+    return realRoot ?? path;
+  }
+
+  return candidate;
+}
+
+function resolveGitWorkingTreeRoot(path: string): string | null {
+  try {
+    let dir = existsSync(path) && !statSync(path).isDirectory()
+      ? resolve(path, "..")
+      : path;
+
+    for (let i = 0; i < 30; i++) {
+      const gitPath = join(dir, ".git");
+      if (existsSync(gitPath)) return dir;
+
+      const parent = resolve(dir, "..");
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // Non-fatal: callers either keep the original path or fail closed.
+  }
+  return null;
+}
+
+function resolveProjectRootFromGitFile(worktreePath: string): string | null {
+  try {
+    let dir = worktreePath;
+    for (let i = 0; i < 30; i++) {
+      const gitPath = join(dir, ".git");
+      if (existsSync(gitPath)) {
+        const content = readFileSync(gitPath, "utf8").trim();
+        if (content.startsWith("gitdir: ")) {
+          const gitDir = resolve(dir, content.slice(8));
+          const dotGitDir = resolve(gitDir, "..", "..");
+          if (dotGitDir.endsWith(".git") || dotGitDir.endsWith(".git/") || dotGitDir.endsWith(".git\\")) {
+            return resolve(dotGitDir, "..");
+          }
+
+          const commonDirPath = join(gitDir, "commondir");
+          if (existsSync(commonDirPath)) {
+            const commonDir = readFileSync(commonDirPath, "utf8").trim();
+            const resolvedCommonDir = resolve(gitDir, commonDir);
+            return resolve(resolvedCommonDir, "..");
+          }
+        }
+        break;
+      }
+
+      const parent = resolve(dir, "..");
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // Non-fatal: callers either keep the original path or fail closed.
+  }
+  return null;
+}