Add worktree and branch graph views

.github/workflows/ci.yml

@@ -9,10 +9,13 @@ on:
 jobs:
   test:
     runs-on: ${{ matrix.os }}
+    # The suite runs ~30m on the ubuntu runners and slower on macos, so the
+    # per-step budget needs headroom; this job-level cap still bounds a hang.
+    timeout-minutes: 60
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
-        go-version: ['1.26']
+        go-version: ['1.27']
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
@@ -24,10 +27,10 @@ jobs:
         run: go build -o gortex ./cmd/gortex/
 
       - name: Test
-        run: go test -race -timeout=30m -coverprofile=coverage.out ./...
+        run: go test -race -timeout=45m -coverprofile=coverage.out ./...
 
       - name: Upload coverage
-        if: matrix.os == 'ubuntu-latest' && matrix.go-version == '1.26'
+        if: matrix.os == 'ubuntu-latest' && matrix.go-version == '1.27'
         uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v6
         with:
           files: coverage.out
@@ -37,8 +40,10 @@ jobs:
     # CGO build smoke-test on native Windows. tree-sitter needs a C/C++
     # compiler — the GitHub windows runner ships mingw-w64 on PATH, so no
     # extra toolchain setup is required. `go build ./...` compiles every
-    # production package; the focused agents and sidecar tests also exercise
-    # Windows-only paths without opting into the unsupported full test suite.
+    # production package; the focused test steps below exercise the paths
+    # whose behaviour actually differs here — separators, volumes, open-file
+    # semantics, %USERPROFILE%, and the git layouts the checkout catalog is
+    # built from — without opting into the unsupported full test suite.
     runs-on: windows-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -140,6 +145,37 @@ jobs:
           ./internal/mcp ./internal/resolver ./internal/persistence
           ./internal/review
 
+      # gitstate reads git's own answers and measures them against host paths.
+      # git spells a worktree root with '/' on every platform while a fixture
+      # builds one with the host separator, an absolute path needs a volume
+      # here and not on POSIX, and a repository's admin directory is reached
+      # by joining. None of those distinctions exists on the linux/macos
+      # matrix, so the whole package runs here rather than the one test that
+      # looks path-shaped. The timeout is generous because every fixture
+      # shells out to git and process spawn is the slow axis on this runner.
+      - name: Test git state inspection
+        run: go test -timeout=15m -count=1 ./internal/gitstate
+
+      # The reconcile pass turns that inventory into catalog rows: it joins
+      # admin directories, and it decides which checkout owns a path by
+      # measuring roots against each other. Both are separator-shaped, so a
+      # '/'-spelled expectation passes on POSIX whatever the code does.
+      - name: Test checkout reconciliation
+        run: go test -timeout=10m -count=1 ./internal/reconcile
+
+      # The CLI half of the same code: the checkout verbs, the view router
+      # that answers a probe from the checkout containing the probed path,
+      # and the classifier that tells a linked worktree from a main checkout
+      # by reading its `.git` file. Every one of them decides by comparing
+      # path spellings, and the git layouts they classify are built by git
+      # itself. The selector names those tests only — the rest of the package
+      # is either unrelated or needs a daemon behind an AF_UNIX socket.
+      - name: Test checkout and view path routing
+        run: >
+          go test -timeout=10m -count=1
+          -run '^(TestRepos(Families|SetPrimary|Forget|Reconcile|ExplainView)|TestUntrack(Previews|Reports)|TestController(TrackUntrack|Reload)DrivesTheCheckoutLifecycle|TestControllerAnswersTheFileCoverageVerb|TestProbeOf|TestProbeMatchesAPathSpelledThroughASymlink|TestRoutedProbe|TestUnroutedProbe|TestSearchSymbolsWithoutAPath|TestViewsStatus|TestReload_(Keeps|Untracks)|TestDispatcher_(RegisteredCheckout|UnregisteredWorktree)|TestLinkedWorktreeAt_)'
+          ./cmd/gortex
+
   build-linux-static:
     # The linux release ships a statically linked binary so it runs on any
     # distro (see .goreleaser.yml). That only holds while the code stays
@@ -202,7 +238,7 @@ jobs:
       - name: golangci-lint
         uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9
         with:
-          version: v2.11.4
+          version: v2.13.1
           args: --timeout=10m
 
       # goreleaser used to run `go mod tidy` as a release before-hook, which

.github/workflows/release.yml

@@ -240,7 +240,7 @@ jobs:
             -v "$PWD":/go/src/gortex \
             -w /go/src/gortex \
             -e GITHUB_TOKEN \
-            ghcr.io/goreleaser/goreleaser-cross:v1.26 \
+            ghcr.io/goreleaser/goreleaser-cross:v1.27 \
             release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -74,3 +74,5 @@ bench/run-linux-rest.sh
 
 # Local CPU-profiling harness (hardcoded local paths; run manually, not in CI)
 internal/indexer/bench_vscode_test.go
+docs/worktree-branch-overlays.md
+docs/specs/

.golangci.yaml

@@ -1,5 +1,5 @@
 # golangci-lint configuration (schema v2).
-# CI pins golangci-lint to v2.11.4 (.github/workflows/ci.yml).
+# CI pins golangci-lint to v2.13.1 (.github/workflows/ci.yml).
 version: "2"
 
 linters:

CONTRIBUTING.md

@@ -87,7 +87,7 @@ make lint      # golangci-lint run --timeout=5m
 ```
 
 **A green test run is not the full CI gate.** CI pins golangci-lint to
-**v2.11.4** and fails the build on any finding. Run it locally before opening a
+**v2.13.1** and fails the build on any finding. Run it locally before opening a
 PR — config lives in [`.golangci.yaml`](.golangci.yaml).
 
 ```bash

Makefile

@@ -243,7 +243,7 @@ eval-setup: build
 
 # Build linux/amd64 binary for container injection (requires podman/docker)
 eval-build-linux:
-	podman run --rm --platform linux/amd64 -v $(CURDIR):/src -w /src golang:1.26 \
+	podman run --rm --platform linux/amd64 -v $(CURDIR):/src -w /src golang:1.27 \
 		bash -c "apt-get update -qq && apt-get install -y -qq libtree-sitter-dev && go build -ldflags '$(LDFLAGS)' -o gortex-linux ./cmd/gortex/"
 	@echo "✓ Built gortex-linux (linux/amd64)"
 

cmd/gortex/canonical_paths_test.go

@@ -0,0 +1,99 @@
+package main
+
+import (
+	"io"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/spf13/cobra"
+	"github.com/zzet/gortex/internal/config"
+	"github.com/zzet/gortex/internal/pathkey"
+	"github.com/zzet/gortex/internal/testenv"
+)
+
+func TestResolveEmbeddedIndexCanonicalizesExplicitAlias(t *testing.T) {
+	base := t.TempDir()
+	realRoot := filepath.Join(base, "real")
+	if err := os.MkdirAll(realRoot, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	aliasRoot := filepath.Join(base, "alias")
+	if err := os.Symlink(realRoot, aliasRoot); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	want, err := filepath.EvalSymlinks(realRoot)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want = filepath.Clean(want)
+
+	plan := resolveEmbeddedIndex(aliasRoot, "", nil)
+	if plan.Index != want {
+		t.Fatalf("index root = %q, want canonical %q", plan.Index, want)
+	}
+	if plan.Notebook != want {
+		t.Fatalf("notebook root = %q, want canonical %q", plan.Notebook, want)
+	}
+}
+
+func TestRunTrackCanonicalizesAliasBeforePersistenceAndRegistration(t *testing.T) {
+	testenv.Sandbox(t)
+	base := t.TempDir()
+	realRoot := filepath.Join(base, "real")
+	if err := os.MkdirAll(realRoot, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	aliasRoot := filepath.Join(base, "alias")
+	if err := os.Symlink(realRoot, aliasRoot); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	want := pathkey.CanonicalExistingRoot(aliasRoot)
+
+	oldEnsure := trackEnsureDaemonReadyFn
+	oldNotify := trackNotifyDaemonTrackFn
+	oldWait, oldName, oldAsWorktree := trackWait, trackName, trackAsWorktree
+	t.Cleanup(func() {
+		trackEnsureDaemonReadyFn = oldEnsure
+		trackNotifyDaemonTrackFn = oldNotify
+		trackWait, trackName, trackAsWorktree = oldWait, oldName, oldAsWorktree
+	})
+	trackWait, trackName, trackAsWorktree = false, "", false
+	ensureSlot := reflect.ValueOf(&trackEnsureDaemonReadyFn).Elem()
+	ensureSlot.Set(reflect.MakeFunc(ensureSlot.Type(), func([]reflect.Value) []reflect.Value {
+		return []reflect.Value{reflect.ValueOf(daemonReady)}
+	}))
+	var registered []string
+	trackNotifyDaemonTrackFn = func(path string, _ time.Time) error {
+		registered = append(registered, path)
+		return nil
+	}
+
+	cmd := &cobra.Command{}
+	cmd.SetErr(io.Discard)
+	for _, root := range []string{aliasRoot, realRoot} {
+		if err := runTrack(cmd, []string{root}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if len(registered) != 2 {
+		t.Fatalf("daemon registrations = %d, want 2", len(registered))
+	}
+	for _, got := range registered {
+		if got != want {
+			t.Fatalf("daemon registration path = %q, want canonical %q", got, want)
+		}
+	}
+	global, err := config.LoadGlobal()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(global.Repos) != 1 {
+		t.Fatalf("persisted repos after alias and canonical registration = %d, want 1", len(global.Repos))
+	}
+	if got := global.Repos[0].Path; got != want {
+		t.Fatalf("persisted repo path = %q, want canonical %q", got, want)
+	}
+}

cmd/gortex/canonical_routing_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+
+	"github.com/zzet/gortex/internal/daemon"
+)
+
+func statusWithTrackedPath(t *testing.T, path string) daemon.StatusResponse {
+	t.Helper()
+	var status daemon.StatusResponse
+	tracked := reflect.ValueOf(&status).Elem().FieldByName("TrackedRepos")
+	if !tracked.IsValid() || tracked.Kind() != reflect.Slice {
+		t.Fatal("daemon.StatusResponse.TrackedRepos is not a slice")
+	}
+	repo := reflect.New(tracked.Type().Elem()).Elem()
+	pathField := repo.FieldByName("Path")
+	if !pathField.IsValid() || !pathField.CanSet() || pathField.Kind() != reflect.String {
+		t.Fatal("daemon tracked-repository status has no settable Path field")
+	}
+	pathField.SetString(path)
+	tracked.Set(reflect.Append(tracked, repo))
+	return status
+}
+
+func TestTrackedReposReachCanonicalRootAndCWDAliases(t *testing.T) {
+	base := t.TempDir()
+	realRoot := filepath.Join(base, "real")
+	realRepo := filepath.Join(realRoot, "repo")
+	realCWD := filepath.Join(realRepo, "nested")
+	if err := os.MkdirAll(realCWD, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	aliasRoot := filepath.Join(base, "alias")
+	if err := os.Symlink(realRoot, aliasRoot); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	aliasRepo := filepath.Join(aliasRoot, "repo")
+	aliasCWD := filepath.Join(aliasRepo, "nested")
+
+	for _, tc := range []struct {
+		name string
+		root string
+		cwd  string
+	}{
+		{name: "canonical root canonical cwd", root: realRepo, cwd: realCWD},
+		{name: "canonical root alias cwd", root: realRepo, cwd: aliasCWD},
+		{name: "alias root canonical cwd", root: aliasRepo, cwd: realCWD},
+		{name: "alias root alias cwd", root: aliasRepo, cwd: aliasCWD},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			status := statusWithTrackedPath(t, tc.root)
+			if !trackedRootContains(status, tc.cwd) {
+				t.Fatalf("trackedRootContains rejected cwd %q under root %q", tc.cwd, tc.root)
+			}
+			if !trackedReposReach(status, tc.cwd) {
+				t.Fatalf("trackedReposReach rejected cwd %q under root %q", tc.cwd, tc.root)
+			}
+		})
+	}
+}