Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
---
phase: quick-260712-roaming
reviewed: 2026-07-12T00:00:00Z
depth: standard
files_reviewed: 9
files_reviewed_list:
- internal/activity/domain/planner.go
- internal/activity/domain/planner_test.go
- internal/activity/domain/activity.go
- internal/activity/domain/activity_test.go
- internal/activity/port/pointer.go
- internal/activity/service/keeper_service.go
- internal/activity/service/keeper_service_test.go
- internal/activity/adapter/cgpointer.go
- internal/activity/adapter/cgpointer_test.go
- cmd/sysmon/main.go
findings:
critical: 0
warning: 0
info: 2
total: 2
status: issues_found
---

# Roaming Feature Review — Pass #2 (post review #1 fixes)

**Reviewed:** 2026-07-12
**Depth:** standard
**Files Reviewed:** 10
**Status:** issues_found (info-only; no blockers, no warnings)

## Summary

All five review #1 findings were verified fixed, correctly, with no regressions:

- **CR-01 (clamp out-of-bounds start)** — fixed correctly. `Plan` now clamps
`curX`/`curY` via a new `clamp(v, size)` helper (`planner.go:73-74,84-92`)
before calling `interpolate`. Verified numerically for both directions
(`curX=-500` -> `0`, `curX=5000` with `width=1920` -> `1919`) and confirmed
that clamping both endpoints of a linear interpolation to `[0,size)` makes
every intermediate point provably in-bounds (lerp between two in-bounds
integers cannot overshoot either endpoint). Covered by the new
`TestPlanner_Plan_ClampsOutOfBoundsStart` test, which asserts every path
point stays in `[0,w) x [0,h)` starting from `(-500, 5000)` against a
`1920x1080` bound. `go test -race` passes.
- **WR-01 (reuse one timer instead of `time.After` per step)** — fixed
correctly. `drive()` now allocates a single `time.NewTimer(stepPause)`
before the loop, calls `timer.Reset(stepPause)` after each `MoveTo`, and
`defer timer.Stop()` on function exit (`keeper_service.go:107-126`).
Verified this is correct under Go 1.26's timer semantics (this project's
`go.mod` requires `go 1.26.5`, well past the Go 1.23 timer-channel
redesign): `Reset` on an already-drained-by-select timer needs no manual
drain, and `Reset` on a timer that hasn/t fired yet (the first-iteration
case, since the timer is constructed already running) is likewise safe.
Traced a live (non-synctest) 40-iteration run of the identical loop shape
and confirmed no stale-fire drift (elapsed time tracked expected duration).
All `synctest`-based service tests (`TestKeeperService_MidGlideCancelStopsPromptly`
et al.) pass under `-race`, including the ctx-cancel-mid-glide path that
exercises the timer/ctx.Done() select race. No goroutine or timer leak: the
`defer timer.Stop()` runs on every return path (MoveTo error, ctx cancel,
natural path completion).
- **WR-02 (rounding comment clarity)** — fixed; `roundingScale` doc comment
now spells out the round-half-up algebra (`planner.go:12-16`). Nit-level,
addressed as suggested.
- **IN-01 (bounds re-read per roam)** — addressed with an explanatory comment
(`keeper_service.go:88-89`) noting this is intentional (picks up
resolution/monitor changes). No behavior change requested or made; correct.
- **IN-02 (adapter `Bounds()` always-nil contract)** — addressed with an
expanded doc comment (`cgpointer.go:96-100`) documenting the containment
relationship with `domain.Planner`'s `ErrInvalidBounds` guard. Correct and
matches the actual code path.

`go build ./...`, `go vet ./...`, `golangci-lint run ./...` (strict config,
0 issues), and `go test -race -count=1 ./...` all pass. `GOOS=linux go build`
succeeds for `domain`, `port`, and `service`. `gofmt -l` reports no files.
Layering remains correct: domain has no cgo/os import, service imports only
domain+port, cgo is confined to the adapter behind `//go:build darwin`, every
`CGEventCreate*` is still paired with `CFRelease`.

No new Critical or Warning-tier defects were introduced by the fix commit.
Two Info-level nits found, one of which is a genuine (if harmless) doc-comment
placement bug introduced by the fix itself.

## Info

### IN-01: Misplaced/orphaned doc comment left behind by the CR-01 test insertion

**File:** `internal/activity/domain/planner_test.go:166-170, 191`
**Issue:** The new `TestPlanner_Plan_ClampsOutOfBoundsStart` test (and its own
correct doc comment) was inserted *before* `TestPlanner_Plan_EdgeCase_OnePixelScreen`
in the file, but the original doc comment that belonged to
`TestPlanner_Plan_EdgeCase_OnePixelScreen` (lines 166-167: "TestPlanner_Plan_EdgeCase_OnePixelScreen
covers a 1x1 screen: the only valid point is (0, 0), so every path point must
be (0, 0).") was left in place above the new test instead of being moved down
with it. The result:
- Lines 166-170 now read as one merged, incorrect comment block: two lines
that describe `TestPlanner_Plan_EdgeCase_OnePixelScreen` immediately
followed by two lines that describe `TestPlanner_Plan_ClampsOutOfBoundsStart`
-- all sitting directly above `func TestPlanner_Plan_ClampsOutOfBoundsStart`.
- `TestPlanner_Plan_EdgeCase_OnePixelScreen` itself (line 191) now has no doc
comment at all.

This is purely cosmetic (does not affect test correctness, `go vet`, or
`golangci-lint`'s `godot` linter, which only checks comment punctuation, not
semantic placement) but it is a genuine, real defect: a reader of this file
will misread lines 166-167 as describing the function immediately below them.
**Fix:** Move the orphaned comment down to sit above its correct function:
```go
}

// TestPlanner_Plan_ClampsOutOfBoundsStart verifies that a starting position
// outside the display bounds -- as Position() can report on a multi-monitor
// setup -- is clamped, so no glide step lands off the main display.
func TestPlanner_Plan_ClampsOutOfBoundsStart(t *testing.T) {
...
}

// TestPlanner_Plan_EdgeCase_OnePixelScreen covers a 1x1 screen: the only
// valid point is (0, 0), so every path point must be (0, 0).
func TestPlanner_Plan_EdgeCase_OnePixelScreen(t *testing.T) {
...
}
```

### IN-02: No test exercises the exact upper-boundary clamp value (`curX == width`)

**File:** `internal/activity/domain/planner_test.go:171-189`
**Issue:** `TestPlanner_Plan_ClampsOutOfBoundsStart` covers a comfortably
out-of-bounds start (`curX=-500`, `curY=5000` against `w=1920,h=1080`), which
exercises both the `v < 0` and `v > size-1` branches of `clamp`, but not the
exact boundary value `v == size` (e.g. `curX = 1920` for `width = 1920`),
which is the smallest input that should still clamp to `size-1` via the
`v > size-1` branch rather than passing through unclamped. The current
implementation is correct at this boundary (verified numerically:
`clamp(1920, 1920) == 1919`), so this is a coverage gap, not a bug.
**Fix:** Add one boundary-value assertion, e.g. extend
`TestPlanner_Plan_ClampsOutOfBoundsStart` (or a small table test) with
`curX = width` and `curY = height` and assert the resulting path's first
point has `X < width` and `Y < height`.

---

_Reviewed: 2026-07-12_
_Reviewer: Claude (gsd-code-reviewer)_
_Depth: standard_
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
---
phase: quick-260712-roaming
reviewed: 2026-07-12T00:00:00Z
depth: standard
files_reviewed: 9
files_reviewed_list:
- internal/activity/domain/planner.go
- internal/activity/domain/planner_test.go
- internal/activity/domain/activity.go
- internal/activity/domain/activity_test.go
- internal/activity/port/pointer.go
- internal/activity/service/keeper_service.go
- internal/activity/service/keeper_service_test.go
- internal/activity/adapter/cgpointer.go
- internal/activity/adapter/cgpointer_test.go
- cmd/sysmon/main.go
findings:
critical: 1
warning: 2
info: 2
total: 5
status: issues_found
---

# Roaming Feature Review — Pass #1

**Reviewed:** 2026-07-12
**Depth:** standard
**Files Reviewed:** 9 (+ cmd/sysmon/main_test.go read for context)
**Status:** issues_found

## Summary

This is a well-built, small, hexagonally-clean feature. `go build ./...`,
`golangci-lint run ./...` (0 issues), and `go test -race ./...` all pass;
domain/port/service build under `GOOS=linux`. The `RandomSource` seam is
minimal and correctly injected; planner tests are genuinely deterministic
(verified `TestPlanner_Plan_DeterministicGivenSameSource`); the interpolation
math was traced numerically (monotonic, bounded step, exact final-target
arrival, no drift, correct for both positive and negative deltas via
`floorDiv`) and is sound. cgo memory management in the adapter is correct:
every `CGEventCreate*` is paired with `CFRelease`, `CGDisplayBounds`/
`CGMainDisplayID` create no CF object (nothing to release), no `CFRelease(NULL)`
path exists, `//go:build darwin` is present, and `*CGPointer` still satisfies
`port.Pointer`. Layering is correct: domain has no cgo/os imports and builds
under `GOOS=linux`; service imports only `domain` + `port`, never `adapter`.
Ctx cancellation is checked between every `MoveTo` in `drive()`, and the
mid-glide-cancel test proves no further `MoveTo` calls happen after cancel.

One real correctness gap found against the acceptance criteria: the planner
never clamps or validates the *current* position it interpolates from, only
the random *target*. On a real multi-monitor Mac, `Position()` can legitimately
return coordinates outside the main display's `[0,width)x[0,height)` (e.g. a
secondary monitor placed to the left has negative global x). The domain layer
silently interpolates from that out-of-bounds start, so the first several
glide steps of a roam can be off the main display — directly contradicting the
"never off-screen" acceptance criterion in a realistic, not contrived,
scenario. See CR-01.

## Critical Issues

### CR-01: Glide path is not bounds-clamped when the current position is outside the main display

**File:** `internal/activity/domain/planner.go:62-71`
**Issue:** `Plan` validates `width`/`height` and draws a target uniformly in
`[0,width) x [0,height)`, but `curX`/`curY` (the position `interpolate` glides
*from*) are used as-is, with no clamping and no test coverage for the case
where they fall outside `[0,width)x[0,height)`. On a real Mac with a
secondary display, `CGEventGetLocation` (via `adapter.CGPointer.Position()`)
returns coordinates in the *global* desktop coordinate space, not the main
display's local space — a monitor placed to the left of the main display
produces negative x, a monitor placed above produces negative y, and a
monitor placed to the right/below produces x/y beyond the main display's
width/height. Since `interpolate` linearly walks from `(curX, curY)` to the
clamped target, the earliest steps of the glide remain off the main display
(and can even be at negative coordinates) until the interpolation catches up.
This is a direct violation of the spec's "whole screen, bounded... never
off-screen" acceptance criterion (`docs/TASK-roaming.md:28-30`) and of
`PLAN.md`'s truth "The cursor never leaves the main display bounds ... no
cumulative drift". Verified numerically: `Plan`-equivalent interpolation from
`curX=-500` to a target of `960` inside a `1920`-wide main display yields
intermediate steps of `-463`, `-317`, ... — genuinely off-display coordinates
posted via `MoveTo`.
**Fix:** Clamp `curX`/`curY` into `[0,width) x [0,height)` before calling
`interpolate`, so the glide always starts and stays inside the main display's
bounds even if the OS-reported current position is elsewhere:
```go
func (p *Planner) Plan(curX, curY, width, height int) ([]Point, error) {
if width <= 0 || height <= 0 {
return nil, ErrInvalidBounds
}

curX = clamp(curX, width)
curY = clamp(curY, height)

targetX := p.rnd.IntN(width)
targetY := p.rnd.IntN(height)

return interpolate(curX, curY, targetX, targetY), nil
}

// clamp confines v to [0, n).
func clamp(v, n int) int {
if v < 0 {
return 0
}
if v >= n {
return n - 1
}
return v
}
```
Add a planner test with `curX`/`curY` outside `[0,width)x[0,height)` (both
negative and >= bound) asserting every path point, including the first,
stays within `[0,width)x[0,height)`.

## Warnings

### WR-01: `time.After` allocates a new timer every glide step instead of reusing one

**File:** `internal/activity/service/keeper_service.go:112-116`
**Issue:** `drive` calls `time.After(stepPause)` inside the per-point loop.
Each call allocates a new `time.Timer` that is not eligible for reuse and,
if `ctx.Done()` fires first, is never explicitly stopped (it is left to be
GC'd once it fires ~8ms later). With `stepCount = 40`, a single roam
allocates up to 40 timers. This is not a leak in the classic sense (they do
get GC'd), but it is unidiomatic Go for a hot loop and is exactly the pattern
`time.After`'s own godoc warns against reusing in tight loops. Given this
project's stated efficiency goals (near-zero idle CPU / lightweight
footprint), a single reused timer is the more correct pattern.
**Fix:** Use one `time.NewTimer`, `Reset` it each iteration, and `Stop` it on
early exit:
```go
func (k *KeeperService) drive(ctx context.Context, path []domain.Point) {
timer := time.NewTimer(stepPause)
defer timer.Stop()

for _, pt := range path {
if err := k.pointer.MoveTo(pt.X, pt.Y); err != nil {
k.logger.Error("move failed", "err", err)
return
}

select {
case <-timer.C:
timer.Reset(stepPause)
case <-ctx.Done():
return
}
}
}
```

### WR-02: `roundingScale` name/doc slightly obscures the actual purpose (round-half-up bias, not "doubling the denominator" as an end in itself)

**File:** `internal/activity/domain/planner.go:13-15, 103-110`
**Issue:** The comment says "roundingScale doubles the interpolation
denominator so integer division can round to the nearest pixel instead of
truncating toward zero" — accurate, but the name `roundingScale` combined
with the `lerpAxis` comment ("Round-to-nearest via adding half the
denominator before truncating division") requires the reader to reconstruct
that `roundingScale = 2` exists purely to let `+ total` represent "add half
of `total*roundingScale`" without needing a fractional `total/2`. This is a
classic round-half-up-via-integer-arithmetic trick; it works (verified
numerically, monotonic and drift-free for a wide sweep of positive/negative
deltas), but a reader unfamiliar with the trick has to work harder than
necessary. Not a correctness issue — purely a readability nit.
**Fix:** Consider renaming to `roundHalfScale` or adding one more line to the
`lerpAxis` doc comment spelling out the algebra
(`numerator/ (total*2) == round(delta*step/total)`), or extracting the
`+ total` term into a named `halfStep := total * roundingScale / 2` — wait,
that reintroduces truncation; simplest is just a slightly more explicit
comment. Optional; low priority.

## Info

### IN-01: `Bounds()` is re-queried every tick even though the main display's dimensions essentially never change mid-session

**File:** `internal/activity/service/keeper_service.go:88-92`
**Issue:** Every `roam()` call re-reads `Bounds()` via cgo. This is not a
performance defect in the sense that's in scope for this review (a single
cgo call per 10s tick is trivially cheap), but it is worth noting for anyone
later trying to reduce cgo call surface — genuinely out of v1 scope per the
review lens, included here only as a nit.
**Fix:** None required; no action needed unless display-bounds caching
becomes desirable for other reasons (e.g. detecting external-display
attach/detach mid-run, which is arguably a *feature*, not a bug).

### IN-02: `getBounds`'s "always succeeds" comment is not fully defensive against a 0x0 or negative bounds return

**File:** `internal/activity/adapter/cgpointer.go:27-34, 96-101`
**Issue:** `Bounds()` trusts `CGDisplayBounds(CGMainDisplayID())` and never
returns an error — reasonable per Apple's API contract (a running macOS
session always has a main display with positive dimensions), but if this
ever returned a degenerate rect (e.g. transient state during
display-configuration change / sleep-wake), `int(w)`/`int(h)` could yield 0,
and the resulting `Bounds()` values would flow straight into
`domain.Planner.Plan`, which already returns `ErrInvalidBounds` for
`width<=0 || height<=0` and is handled/logged by `roam()` without crashing.
So the failure mode is already contained by the domain+service boundary;
this is purely a note that the containment is implicit (relies on Plan's
guard) rather than validated at the adapter boundary itself. No fix required
given the existing containment; flagging for awareness only.

---

_Reviewed: 2026-07-12_
_Reviewer: Claude (gsd-code-reviewer)_
_Depth: standard_
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
status: complete
---

# Quick task: realistic random cursor roaming

Replaced the invisible 1px nudge with realistic random roaming. Each `-interval`
tick, the cursor glides over ~40 small steps to a fresh uniform-random point
within the main display bounds, honoring ctx cancellation between steps. Old
`Nudge`/`Offset` code removed; `Interval` kept.

- **domain**: pure `Planner` with an injected `RandomSource` seam (satisfied by
`*math/rand/v2.Rand`); clamped targets; deterministic tests (bounds,
continuity, ends-at-target, corner / 1x1 / target==current).
- **port**: `Pointer` reshaped to `Position()` / `Bounds()` / `MoveTo(x,y)`;
mock regenerated via mockgen.
- **service**: `KeeperService` roams once per tick, driving the path through
`MoveTo`; synctest + mock tests.
- **adapter**: `CGPointer` implements Position/Bounds/MoveTo via CoreGraphics
(`//go:build darwin`), releasing every CoreFoundation object.
- **cmd**: runtime-seeded `*rand.Rand` + planner injected; `-interval`/`-quiet`/
signal-exit-0 and the accessibility preflight unchanged.

Runtime binary stays stdlib-only; test deps testify + go.uber.org/mock only.
Gates green: `go build ./...`, `golangci-lint run ./...` (0 issues),
`go test -race ./...`, and `GOOS=linux` build of domain/port/service.

Branch: `feat/random-roaming` (commits 043c51a..5bc019b).
Loading
Loading