[fix] Bound git status queries with a per-item timeout (#288) (#302)

* [refactor] Thread context.Context through parallel.Collect (#288)

Extend the Collect signature to accept a ctx and fn(ctx, i) so callers
can enforce per-item deadlines without reaching into captured variables.
All 7 production callers and the test suite updated; the two long-running
sites (deps install, mcp sync) pass ctx through without a deadline.

* [fix] Add git.WithItemTimeout to bound per-item git queries (#288)

Introduces a 10s per-item deadline helper that callers can apply to each
fan-out slot so a stalled worktree (e.g. NFS mount) cannot occupy a
parallel.Collect worker slot indefinitely.

* [fix] Add Unknown sentinel to WorktreeStatus for timed-out git queries (#288)

A worktree whose git queries time out (or fail due to a stalled NFS mount)
previously rendered as clean (✓) — indistinguishable from a healthy worktree.
Now CollectWorktreeStatus sets Unknown=true on any error, FormatStatus returns
"unknown", and colorStatus renders it gray. AheadBehind is updated to propagate
context.Canceled/DeadlineExceeded instead of silently swallowing it.

* [fix] Make fsutil.DirSize cancellable via context (#288)

DirSize now accepts a context.Context and runs the WalkDir in a goroutine
so a stalled syscall (NFS mount) cannot block past the deadline. Callers
in status_dashboard.go updated to thread ctx through; all existing tests
updated for the new signature, plus a cancellation path test.

* [fix] Apply per-item 10s timeout to all git status fan-out queries (#288)

Five parallel.Collect sites that query git per worktree now derive a bounded
context via git.WithItemTimeout before any git call. A stalled worktree
(NFS mount, hung git process) times out in ≤10s and renders as "unknown"
instead of hanging the fan-out indefinitely.

The two long-running sites (deps install, mcp sync) pass ctx through
unchanged — they must not get a 10s cap.

* [fix] Set context.Background() on test cobra commands (#288)

git.WithItemTimeout panics when passed a nil parent context. Test commands
created by newTestCmd() had no context set, so cmd.Context() returned nil.

* [fix] Address review feedback: clarify queryPRInfo ctx + test MCP unknown (#288)

Add comment explaining that queryPRInfo receives outer ctx (not itemCtx) because
it is a gh network call with its own prQueryTimeout, not a git query.

Add TestStatusToolUnknownWorktree to verify that a stalled NFS mount (all
runInDir calls failing) results in Unknown=true in the MCP status response
and is not miscounted as Dirty or Behind.

* [chore] Simplify and fix code comments from review feedback

- dirsize.go: clarify goroutine continues until OS returns (not cancelled)
- branch.go: condense AheadBehind context-propagation note to one line
- timeout.go: shorten itemQueryTimeout and WithItemTimeout comments
- status.go: shorten CollectWorktreeStatus doc to one line
- list_worktrees.go: condense queryPRInfo ctx comment to one line

* [fix] Address review feedback: ctx-aware semaphore, errors.Is, mcp filterDirty timeout

- parallel: make semaphore acquire ctx-aware (select on sem/ctx.Done) so
  goroutines waiting on a full semaphore exit on cancellation rather than
  blocking forever; add TestCollectCancelledContextDoesNotHang
- git/branch: switch AheadBehind ctx check to errors.Is(err, Deadline/Canceled)
  so wrapped context errors are correctly propagated
- mcp/tool_exec: migrate filterDirty to parallel.Collect + git.WithItemTimeout,
  closing the sixth unguarded parallel git fan-out site (#288)

* [fix] Address follow-up feedback: Unknown pass-through + Collect doc contract

- FilterDetailsByStatus: keep Unknown-status rows regardless of --dirty/--behind
  filter flags so stalled worktrees are never silently excluded from list output;
  add TestFilterDetailsByStatusUnknownPassthrough
- parallel.Collect: document that goroutines cancelled at the semaphore leave
  the zero value of T at their result index

* [fix] Use ctx.Err() for timeout detection in AheadBehind (#288)

errors.Is(err, context.DeadlineExceeded/Canceled) never fires when
exec.CommandContext kills the process: CombinedOutput returns *exec.ExitError
(signal killed), not the context sentinel. Check ctx.Err() directly instead.

Also fix TestDirSizeCancelledContext (racy select assertion) and add omitempty
to Dirty/Ahead/Behind for consistent WorktreeStatus JSON schema.

Author: lugassawan

cmd/colors.go

@@ -30,6 +30,10 @@ func typeColor(t string) termcolor.Color {
 
 // colorStatus applies colors to each component of a formatted status string.
 func colorStatus(p *termcolor.Painter, s resolver.WorktreeStatus) string {
+	if s.Unknown {
+		return p.Paint("unknown", termcolor.Gray)
+	}
+
 	formatted := resolver.FormatStatus(s)
 
 	if !s.Dirty && s.Ahead == 0 && s.Behind == 0 {

cmd/colors_test.go

@@ -65,6 +65,11 @@ func TestColorStatus(t *testing.T) {
 			status: resolver.WorktreeStatus{Dirty: true, Ahead: 2, Behind: 1},
 			want:   "[dirty] ↑2 ↓1",
 		},
+		{
+			name:   "unknown",
+			status: resolver.WorktreeStatus{Unknown: true},
+			want:   "unknown",
+		},
 	}
 
 	for _, tt := range tests {

cmd/exec.go

@@ -266,9 +266,11 @@ func filterDirtyWorktrees(ctx context.Context, cmd *cobra.Command, r git.Runner,
 	n := len(worktrees)
 	var done atomic.Int32
 
-	results := parallel.Collect[dirtyResult](n, 8, func(i int) dirtyResult {
+	results := parallel.Collect[dirtyResult](ctx, n, 8, func(ctx context.Context, i int) dirtyResult {
+		itemCtx, cancel := git.WithItemTimeout(ctx)
+		defer cancel()
 		path := worktrees[i].Path
-		dirty, err := git.IsDirty(ctx, r, path)
+		dirty, err := git.IsDirty(itemCtx, r, path)
 		count := done.Add(1)
 		s.Update(fmt.Sprintf("Checking dirty status... (%d/%d)", count, n))
 		if err != nil {

cmd/log.go

@@ -125,12 +125,14 @@ func init() {
 func collectLogEntries(ctx context.Context, r git.Runner, candidates []git.WorktreeEntry, s *spinner.Spinner) []logEntry {
 	prefixes := resolver.AllPrefixes()
 	s.Update("Collecting commit info...")
-	results := parallel.Collect(len(candidates), 8, func(i int) logEntry {
+	results := parallel.Collect(ctx, len(candidates), 8, func(ctx context.Context, i int) logEntry {
+		itemCtx, cancel := git.WithItemTimeout(ctx)
+		defer cancel()
 		e := candidates[i]
 		svc, task, matchedPrefix := resolver.ServiceFromBranch(e.Branch, prefixes)
 		typeName := strings.TrimSuffix(matchedPrefix, "/")
 
-		ct, subject, err := git.LastCommitInfo(ctx, r, e.Branch)
+		ct, subject, err := git.LastCommitInfo(itemCtx, r, e.Branch)
 		if err != nil {
 			return logEntry{branch: e.Branch, task: task, service: svc, typeName: typeName, path: e.Path}
 		}

cmd/mock_runner_test.go

@@ -108,6 +108,7 @@ func newTestCmd() (*cobra.Command, *bytes.Buffer) {
 	cmd.Flags().Bool(flagJSON, false, "")
 	cmd.SetOut(buf)
 	cmd.SetErr(buf)
+	cmd.SetContext(context.Background())
 	return cmd, buf
 }
 

internal/deps/manager.go

@@ -105,7 +105,8 @@ func (m *Manager) install(ctx context.Context, worktreePath, sourceWT string, mo
 	var done atomic.Int32
 	total := len(hashed)
 
-	results = parallel.Collect(total, concurrency, func(i int) InstallResult {
+	// No per-item timeout here — dependency installation is long-running by design.
+	results = parallel.Collect(ctx, total, concurrency, func(ctx context.Context, i int) InstallResult {
 		res := m.installModule(ctx, worktreePath, hashed[i], existingPaths)
 		completed := done.Add(1)
 		progress.Notifyf(onProgress, "%d/%d complete", completed, total)

internal/fsutil/dirsize.go

@@ -2,14 +2,37 @@
 package fsutil
 
 import (
+	"context"
 	"io/fs"
 	"path/filepath"
 )
 
+type dirSizeResult struct {
+	size int64
+	err  error
+}
+
 // DirSize returns the total size of regular files under path.
-// Symlinks are not followed. On partial failure (permission denied,
-// races) it returns the best-effort total and the first error seen.
-func DirSize(path string) (int64, error) {
+// Symlinks are not followed; partial failures return a best-effort total.
+//
+// Returns (0, ctx.Err()) immediately on cancellation. The WalkDir goroutine
+// continues until the OS returns — it cannot be interrupted mid-syscall.
+func DirSize(ctx context.Context, path string) (int64, error) {
+	ch := make(chan dirSizeResult, 1)
+	go func() {
+		size, err := walkDirSize(path)
+		ch <- dirSizeResult{size: size, err: err}
+	}()
+
+	select {
+	case <-ctx.Done():
+		return 0, ctx.Err()
+	case r := <-ch:
+		return r.size, r.err
+	}
+}
+
+func walkDirSize(path string) (int64, error) {
 	var total int64
 	var firstErr error
 

internal/fsutil/dirsize_test.go

@@ -1,6 +1,7 @@
 package fsutil_test
 
 import (
+	"context"
 	"os"
 	"path/filepath"
 	"runtime"
@@ -16,7 +17,7 @@ func TestDirSizeSumsRegularFiles(t *testing.T) {
 	writeFile(t, filepath.Join(root, "nested", "b.txt"), 250)
 	writeFile(t, filepath.Join(root, "nested", "deeper", "c.txt"), 50)
 
-	got, err := fsutil.DirSize(root)
+	got, err := fsutil.DirSize(context.Background(), root)
 	if err != nil {
 		t.Fatalf("DirSize returned error: %v", err)
 	}
@@ -39,7 +40,7 @@ func TestDirSizeDoesNotFollowSymlinks(t *testing.T) {
 		t.Fatalf("symlink: %v", err)
 	}
 
-	got, err := fsutil.DirSize(root)
+	got, err := fsutil.DirSize(context.Background(), root)
 	if err != nil {
 		t.Fatalf("DirSize returned error: %v", err)
 	}
@@ -53,7 +54,7 @@ func TestDirSizeDoesNotFollowSymlinks(t *testing.T) {
 
 func TestDirSizeEmptyDir(t *testing.T) {
 	root := t.TempDir()
-	got, err := fsutil.DirSize(root)
+	got, err := fsutil.DirSize(context.Background(), root)
 	if err != nil {
 		t.Fatalf("DirSize returned error: %v", err)
 	}
@@ -63,7 +64,7 @@ func TestDirSizeEmptyDir(t *testing.T) {
 }
 
 func TestDirSizeMissingPath(t *testing.T) {
-	_, err := fsutil.DirSize(filepath.Join(t.TempDir(), "does-not-exist"))
+	_, err := fsutil.DirSize(context.Background(), filepath.Join(t.TempDir(), "does-not-exist"))
 	if err == nil {
 		t.Fatal("DirSize on missing path returned nil error, want non-nil")
 	}
@@ -90,7 +91,7 @@ func TestDirSizeBestEffortOnPartialError(t *testing.T) {
 	}
 	t.Cleanup(func() { _ = os.Chmod(denied, 0o755) })
 
-	got, err := fsutil.DirSize(root)
+	got, err := fsutil.DirSize(context.Background(), root)
 	if err == nil {
 		t.Fatal("DirSize returned nil error despite permission-denied subdir")
 	}
@@ -102,6 +103,21 @@ func TestDirSizeBestEffortOnPartialError(t *testing.T) {
 	}
 }
 
+func TestDirSizeCancelledContext(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, filepath.Join(root, "a.txt"), 100)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // pre-cancel
+
+	// When both ctx.Done() and the walk goroutine are ready simultaneously,
+	// Go's select picks randomly — assert err != nil rather than a specific sentinel.
+	_, err := fsutil.DirSize(ctx, root)
+	if err == nil {
+		t.Error("expected non-nil error on pre-cancelled context, got nil")
+	}
+}
+
 func writeFile(t *testing.T, path string, size int) {
 	t.Helper()
 	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {

internal/git/branch.go

@@ -69,10 +69,17 @@ func IsDirty(ctx context.Context, r Runner, dir string) (bool, error) {
 
 // AheadBehind returns the ahead/behind counts of the current branch vs its upstream.
 // Returns (0, 0, nil) if there's no upstream configured.
+// Returns ctx.Err() on context cancellation so callers can distinguish a
+// timed-out query from a branch with no upstream.
 func AheadBehind(ctx context.Context, r Runner, dir string) (ahead, behind int, _ error) {
 	out, err := r.RunInDir(ctx, dir, "rev-list", "--left-right", "--count", "@{upstream}...HEAD")
 	if err != nil {
-		// No upstream or other error — treat as 0/0
+		// exec.CommandContext kills via SIGKILL; CombinedOutput returns *exec.ExitError,
+		// not the context sentinel — check ctx.Err() directly.
+		if ctx.Err() != nil {
+			return 0, 0, ctx.Err()
+		}
+		// No upstream configured or other non-fatal error — treat as 0/0.
 		return 0, 0, nil //nolint:nilerr // intentional: missing upstream is not an error
 	}
 

internal/git/timeout.go

@@ -0,0 +1,14 @@
+package git
+
+import (
+	"context"
+	"time"
+)
+
+// itemQueryTimeout bounds a single git query; prevents a stalled worktree from blocking the fan-out.
+const itemQueryTimeout = 10 * time.Second
+
+// WithItemTimeout returns a child context bounded by itemQueryTimeout. Caller must defer cancel().
+func WithItemTimeout(ctx context.Context) (context.Context, context.CancelFunc) {
+	return context.WithTimeout(ctx, itemQueryTimeout)
+}