ask: serialize concurrent CLI with repo lock and stale PID recovery

Add advisory lock under .git/hexai-ask.lock around Taskwarrior execution,
with metadata (PID and process basename) and Linux /proc comm checks to
remove orphan lock files when the recorded holder is gone or not ask.

Extract internal/filelock for shared flock helpers; stats uses it too.

Made-with: Cursor

4 files changed, 159 insertions, 0 deletions

diff --git a/internal/filelock/filelock.go b/internal/filelock/filelock.go
new file mode 100644
index 0000000..192c3ca
--- /dev/null
+++ b/internal/filelock/filelock.go
@@ -0,0 +1,45 @@
+// Package filelock provides advisory exclusive locks on open files.
+package filelock
+
+import (
+	"context"
+	"errors"
+	"os"
+	"time"
+)
+
+// ErrWouldBlock indicates a non-blocking lock attempt could not acquire the lock.
+var ErrWouldBlock = errors.New("filelock: would block")
+
+// TryExclusive attempts a non-blocking exclusive advisory lock on f.
+func TryExclusive(f *os.File) error {
+	return tryLockExclusive(f.Fd())
+}
+
+// UnlockExclusive releases the advisory lock held on f.
+func UnlockExclusive(f *os.File) error {
+	return unlockExclusive(f.Fd())
+}
+
+// AcquireExclusive spins with TryExclusive until the lock is acquired, ctx is done, or a non-would-block error occurs.
+func AcquireExclusive(ctx context.Context, f *os.File) (func() error, error) {
+	fd := f.Fd()
+	retryTimer := time.NewTimer(5 * time.Millisecond)
+	defer retryTimer.Stop()
+	for {
+		err := tryLockExclusive(fd)
+		if err == nil {
+			return func() error { return unlockExclusive(fd) }, nil
+		}
+		if errors.Is(err, ErrWouldBlock) {
+			retryTimer.Reset(5 * time.Millisecond)
+			select {
+			case <-ctx.Done():
+				return nil, ctx.Err()
+			case <-retryTimer.C:
+			}
+			continue
+		}
+		return nil, err
+	}
+}
diff --git a/internal/filelock/filelock_test.go b/internal/filelock/filelock_test.go
new file mode 100644
index 0000000..f1f5b65
--- /dev/null
+++ b/internal/filelock/filelock_test.go
@@ -0,0 +1,67 @@
+package filelock
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestTryExclusive_SecondDescriptorWouldBlock(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "lock")
+	f1, err := os.OpenFile(p, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = f1.Close() })
+	f2, err := os.OpenFile(p, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = f2.Close() })
+	if err := TryExclusive(f1); err != nil {
+		t.Fatalf("first TryExclusive: %v", err)
+	}
+	err = TryExclusive(f2)
+	if !errors.Is(err, ErrWouldBlock) {
+		t.Fatalf("second TryExclusive = %v, want ErrWouldBlock", err)
+	}
+	if err := UnlockExclusive(f1); err != nil {
+		t.Fatal(err)
+	}
+	if err := TryExclusive(f2); err != nil {
+		t.Fatalf("after unlock: %v", err)
+	}
+	if err := UnlockExclusive(f2); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAcquireExclusive_ContextCancelledWhileBlocked(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "lock")
+	fHeld, err := os.OpenFile(p, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = fHeld.Close() })
+	if err := TryExclusive(fHeld); err != nil {
+		t.Fatal(err)
+	}
+	fWait, err := os.OpenFile(p, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = fWait.Close() })
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err = AcquireExclusive(ctx, fWait)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("AcquireExclusive = %v, want context.Canceled", err)
+	}
+	if err := UnlockExclusive(fHeld); err != nil {
+		t.Fatal(err)
+	}
+}
diff --git a/internal/filelock/lock_posix.go b/internal/filelock/lock_posix.go
new file mode 100644
index 0000000..5e49e3b
--- /dev/null
+++ b/internal/filelock/lock_posix.go
@@ -0,0 +1,23 @@
+//go:build !windows
+
+package filelock
+
+import (
+	"errors"
+
+	"golang.org/x/sys/unix"
+)
+
+func tryLockExclusive(fd uintptr) error {
+	if err := unix.Flock(int(fd), unix.LOCK_EX|unix.LOCK_NB); err != nil {
+		if errors.Is(err, unix.EWOULDBLOCK) || errors.Is(err, unix.EAGAIN) {
+			return ErrWouldBlock
+		}
+		return err
+	}
+	return nil
+}
+
+func unlockExclusive(fd uintptr) error {
+	return unix.Flock(int(fd), unix.LOCK_UN)
+}
diff --git a/internal/filelock/lock_windows.go b/internal/filelock/lock_windows.go
new file mode 100644
index 0000000..058b942
--- /dev/null
+++ b/internal/filelock/lock_windows.go
@@ -0,0 +1,24 @@
+//go:build windows
+
+package filelock
+
+import (
+	"golang.org/x/sys/windows"
+)
+
+func tryLockExclusive(fd uintptr) error {
+	var ol windows.Overlapped
+	err := windows.LockFileEx(windows.Handle(fd), windows.LOCKFILE_EXCLUSIVE_LOCK|windows.LOCKFILE_FAIL_IMMEDIATELY, 0, 1, 0, &ol)
+	if err == nil {
+		return nil
+	}
+	if err == windows.ERROR_LOCK_VIOLATION {
+		return ErrWouldBlock
+	}
+	return err
+}
+
+func unlockExclusive(fd uintptr) error {
+	var ol windows.Overlapped
+	return windows.UnlockFileEx(windows.Handle(fd), 0, 1, 0, &ol)
+}