fix(agentctl): demote unwatched workspace trackers to slow polling (#2113)

This commit is contained in:
João Manso
2026-08-02 14:37:50 +01:00
committed by GitHub
parent d462af8ce7
commit 46a35704ec
6 changed files with 524 additions and 25 deletions
@@ -126,6 +126,19 @@ type Manager struct {
// per-field repoTrackersMu still allows concurrent subscribe/unsubscribe
// readers while a rescan is in flight.
rescanMu sync.Mutex
// workspacePollMode is the most recent mode the gateway pushed for this
// workspace. Trackers created after that point — rescan, rebind or
// reconcile adding a repository to a workspace that is already focused —
// inherit it, because no further push arrives unless the session's own
// mode changes.
//
// Guarded by repoTrackersMu rather than a mutex of its own: the mode and
// the tracker set have to move together. A separate lock let a tracker read
// the mode, then get registered after a concurrent push had already
// snapshotted the set — adopting a stale mode with its grace timer disarmed,
// with nothing left to correct it.
workspacePollMode PollMode
workspacePollModeSet bool
// workspaceTrackersBySubpath caches per-subpath trackers for multi-repo
// task roots. Key is the cleaned subpath (relative to cfg.WorkDir). The
// root tracker lives in workspaceTracker above.
@@ -729,6 +742,41 @@ func (m *Manager) RepoSubpaths() []string {
return out
}
// newTrackerForRepo builds a per-repo tracker that inherits the workspace's
// current poll mode. Used for every tracker created after launch — rescan and
// lazy subpath creation — because the gateway only pushes on a session mode
// transition: a repository added to a workspace that is already focused would
// otherwise sit at its construction default and be demoted by the grace timer
// 60s later, while the user is looking at it.
func (m *Manager) newTrackerForRepo(path, repositoryName string) *WorkspaceTracker {
return NewWorkspaceTrackerForRepo(path, repositoryName, m.logger)
}
// applyWorkspacePollModeLocked gives newly built trackers the last mode the
// gateway pushed, if it ever pushed one. SetPollMode also disarms a tracker's
// grace demotion, which is correct: the gateway has spoken for this workspace,
// so the fallback must not override it. With no prior push the trackers keep
// their construction default and the grace timer stays in charge.
//
// Callers must hold repoTrackersMu for writing, and must call this in the same
// critical section that publishes the trackers. Reading the mode and
// registering the tracker have to be one step: otherwise a SetWorkspacePollMode
// running in between stores a new mode and fans it out to a tracker set that
// does not include this one yet, so the tracker adopts the stale mode — and
// because SetPollMode marks it as pushed and disarms the grace timer, nothing
// ever corrects it. It would poll at the wrong cadence for the life of the
// process, which is the exact failure the grace timer exists to prevent.
func (m *Manager) applyWorkspacePollModeLocked(trackers ...*WorkspaceTracker) {
if !m.workspacePollModeSet {
return
}
for _, t := range trackers {
if t != nil {
t.SetPollMode(m.workspacePollMode)
}
}
}
// SetWorkspacePollMode propagates a poll-mode change to the root tracker and
// every per-repo tracker, then forces a RefreshGitStatus on each non-paused
// tracker so a fresh snapshot reaches every subscriber. Without the refresh,
@@ -737,18 +785,50 @@ func (m *Manager) RepoSubpaths() []string {
// after a focus event, since the agent's initial pushes happen at boot and
// no replay path exists for clients that subscribe later.
func (m *Manager) SetWorkspacePollMode(ctx context.Context, mode PollMode) {
root, trackers := m.snapshotTrackers()
root.SetPollMode(mode)
// Reject before storing, not just before applying. Every tracker already
// ignores an invalid mode, so an invalid push is harmless to the trackers
// that exist — but recording it would overwrite the last valid one, and
// trackers created afterwards inherit what is stored. A single malformed
// push would leave every later tracker on its construction default, and
// applyWorkspacePollModeLocked could not tell that apart from a workspace
// the gateway has genuinely never spoken for.
if !mode.IsValid() {
m.logger.Warn("ignoring invalid workspace poll mode", zap.String("mode", string(mode)))
return
}
// Storing the mode and fanning it out happen under one write lock, the same
// one the rescan paths hold while they publish new trackers. That ordering
// is what makes the two safe against each other: a tracker is either already
// registered and gets this push, or it is registered afterwards and reads
// this mode when it does. Anything in between would leave it on a stale mode
// with its grace timer disarmed — see applyWorkspacePollModeLocked.
//
// SetPollMode is a mutex update plus a non-blocking wake-up, so holding the
// lock across the fan-out costs nothing. RefreshGitStatus is the slow part
// and stays outside, in the goroutine below.
m.repoTrackersMu.Lock()
m.workspacePollMode = mode
m.workspacePollModeSet = true
root := m.workspaceTracker
trackers := make([]*WorkspaceTracker, len(m.repoTrackers))
copy(trackers, m.repoTrackers)
if root != nil {
root.SetPollMode(mode)
}
for _, t := range trackers {
t.SetPollMode(mode)
}
m.repoTrackersMu.Unlock()
if mode == PollModePaused {
return
}
// Refresh in background — RefreshGitStatus blocks on git commands which
// can take seconds on large repos; the HTTP caller shouldn't wait.
go func() {
root.RefreshGitStatus(ctx)
if root != nil {
root.RefreshGitStatus(ctx)
}
for _, t := range trackers {
t.RefreshGitStatus(ctx)
}
@@ -0,0 +1,170 @@
package process
import (
"context"
"os"
"path/filepath"
"testing"
"github.com/kandev/kandev/internal/agentctl/server/config"
)
// placeRepo materialises a git repo as a child of taskRoot under the given name.
func placeRepo(t *testing.T, taskRoot, name string) string {
t.Helper()
repoDir, cleanup := setupTestRepo(t)
t.Cleanup(cleanup)
dest := filepath.Join(taskRoot, name)
if err := os.Rename(repoDir, dest); err != nil {
t.Fatalf("place %s: %v", name, err)
}
return dest
}
func stopManagerTrackers(t *testing.T, m *Manager) {
t.Helper()
t.Cleanup(func() {
root, trackers := m.snapshotTrackers()
if root != nil {
root.Stop()
}
for _, tr := range trackers {
tr.Stop()
}
})
}
// TestManagerRescanKeepsFocusedWorkspaceFast is the manager-level regression
// test for review feedback on #2113: the user focuses a task, a rescan then
// adds a repository, and no further gateway push follows because the session's
// own mode never changed. Without inheritance the new tracker would sit at its
// construction default and be demoted by the grace timer while the workspace
// is still being viewed.
func TestManagerRescanKeepsFocusedWorkspaceFast(t *testing.T) {
isolateTestGitEnv(t)
taskRoot := t.TempDir()
placeRepo(t, taskRoot, "frontend")
placeRepo(t, taskRoot, "backend")
mgr := NewManager(&config.InstanceConfig{WorkDir: taskRoot}, newTestLogger(t))
stopManagerTrackers(t, mgr)
// The user focuses the task: the gateway pushes fast, once.
mgr.SetWorkspacePollMode(context.Background(), PollModeFast)
// A repository appears afterwards and a rescan picks it up. The gateway
// stays silent — the session's mode did not change.
placeRepo(t, taskRoot, "worker")
if err := mgr.RescanRepositories(context.Background(), taskRoot); err != nil {
t.Fatalf("RescanRepositories: %v", err)
}
_, trackers := mgr.snapshotTrackers()
var worker *WorkspaceTracker
for _, tr := range trackers {
if tr.RepositoryName() == "worker" {
worker = tr
break
}
}
if worker == nil {
t.Fatalf("rescan did not create a tracker for the new repository; got %d trackers", len(trackers))
}
if got := worker.GetPollMode(); got != PollModeFast {
t.Errorf("rescan-created tracker = %v, want %v — it did not inherit the focused mode", got, PollModeFast)
}
// Deterministic: with the push recorded and the timer cleared, no elapsed
// time can demote it, so there is nothing to wait for.
assertGraceDisarmed(t, worker)
}
// TestManagerRescanKeepsGraceWhenNeverFocused is the other half: with no prior
// push there is nothing to inherit, so the grace demotion must still own
// rescan-created trackers.
func TestManagerRescanKeepsGraceWhenNeverFocused(t *testing.T) {
isolateTestGitEnv(t)
taskRoot := t.TempDir()
placeRepo(t, taskRoot, "frontend")
placeRepo(t, taskRoot, "backend")
mgr := NewManager(&config.InstanceConfig{WorkDir: taskRoot}, newTestLogger(t))
stopManagerTrackers(t, mgr)
placeRepo(t, taskRoot, "worker")
if err := mgr.RescanRepositories(context.Background(), taskRoot); err != nil {
t.Fatalf("RescanRepositories: %v", err)
}
_, trackers := mgr.snapshotTrackers()
for _, tr := range trackers {
if tr.RepositoryName() != "worker" {
continue
}
// Assert the fallback is still in charge rather than waiting out the
// production grace period: no push recorded and the timer armed is
// exactly the state the demotion fires from. That it does fire is
// covered by TestPollModeGrace_DemotesWhenNoPushArrives.
tr.pollModeMu.RLock()
pushed, timer := tr.pollModePushed, tr.pollModeGraceTimer
tr.pollModeMu.RUnlock()
if pushed {
t.Error("tracker recorded a push although the gateway never pushed for this workspace")
}
if timer == nil {
t.Error("grace timer not armed, so an unwatched rescan tracker would poll fast forever")
}
return
}
t.Fatal("rescan did not create a tracker for the new repository")
}
// TestManagerRescanIgnoresInvalidPollModePush covers the gap between rejecting a
// mode and recording it. Every tracker already refuses an invalid mode, so a
// malformed push is harmless to the trackers that exist — but if the Manager
// stored it anyway, trackers created afterwards would inherit the garbage and
// sit on their construction default, indistinguishable from a workspace the
// gateway never spoke for. The last valid push has to survive.
func TestManagerRescanIgnoresInvalidPollModePush(t *testing.T) {
isolateTestGitEnv(t)
taskRoot := t.TempDir()
placeRepo(t, taskRoot, "frontend")
mgr := NewManager(&config.InstanceConfig{WorkDir: taskRoot}, newTestLogger(t))
stopManagerTrackers(t, mgr)
// The gateway focuses the workspace, then sends something malformed.
mgr.SetWorkspacePollMode(context.Background(), PollModeSlow)
mgr.SetWorkspacePollMode(context.Background(), PollMode("turbo"))
mgr.repoTrackersMu.RLock()
stored, ok := mgr.workspacePollMode, mgr.workspacePollModeSet
mgr.repoTrackersMu.RUnlock()
if !ok {
t.Fatal("the invalid push cleared the record of the valid one")
}
if stored != PollModeSlow {
t.Errorf("stored mode = %v, want %v — the invalid push overwrote it", stored, PollModeSlow)
}
// A repository added afterwards must inherit the last valid mode.
placeRepo(t, taskRoot, "worker")
if err := mgr.RescanRepositories(context.Background(), taskRoot); err != nil {
t.Fatalf("RescanRepositories: %v", err)
}
_, trackers := mgr.snapshotTrackers()
var worker *WorkspaceTracker
for _, tr := range trackers {
if tr.RepositoryName() == "worker" {
worker = tr
break
}
}
if worker == nil {
t.Fatalf("rescan did not create a tracker for the new repository; got %d trackers", len(trackers))
}
if got := worker.GetPollMode(); got != PollModeSlow {
t.Errorf("new tracker poll mode = %v, want %v — it did not inherit the last valid push", got, PollModeSlow)
}
}
@@ -222,7 +222,7 @@ func (m *Manager) RebindWorkspaceWithSourceRoots(ctx context.Context, workDir st
}
subs := m.snapshotSubscribers()
children := scanRepositorySubdirs(resolved, roots)
bare := NewWorkspaceTrackerForRepo(resolved, "", m.logger)
bare := m.newTrackerForRepo(resolved, "")
bare.SetBaseBranch(lookupBaseBranch(m.getBaseBranches(), ""))
bare.SetAllowedSourceRoots(roots)
bare.Start(ctx)
@@ -231,7 +231,7 @@ func (m *Manager) RebindWorkspaceWithSourceRoots(ctx context.Context, workDir st
}
repos := make([]*WorkspaceTracker, 0, len(children))
for _, child := range children {
tracker := NewWorkspaceTrackerForRepo(child.path, child.name, m.logger)
tracker := m.newTrackerForRepo(child.path, child.name)
tracker.SetBaseBranch(lookupBaseBranch(m.getBaseBranches(), child.name))
tracker.SetAllowedSourceRoots(roots)
tracker.Start(ctx)
@@ -244,6 +244,7 @@ func (m *Manager) RebindWorkspaceWithSourceRoots(ctx context.Context, workDir st
m.repoTrackersMu.Lock()
oldBare, oldRepos := m.workspaceTracker, m.repoTrackers
m.cfg.WorkDir, m.workspaceTracker, m.repoTrackers, m.workspaceSourceRoots = resolved, bare, repos, append([]string(nil), roots...)
m.applyWorkspacePollModeLocked(append([]*WorkspaceTracker{bare}, repos...)...)
m.cfg.WorkspaceSourceRoots = append([]string(nil), roots...)
m.repoTrackersMu.Unlock()
if oldBare != nil {
@@ -270,7 +271,7 @@ func (m *Manager) transitionToMultiRepoMode(ctx context.Context, workDir string,
zap.String("work_dir", workDir),
zap.Int("children", len(children)))
bareRoot := NewWorkspaceTrackerForRepo(workDir, "", m.logger)
bareRoot := m.newTrackerForRepo(workDir, "")
bareRoot.SetBaseBranch(lookupBaseBranch(m.getBaseBranches(), ""))
bareRoot.SetAllowedSourceRoots(roots)
bareRoot.Start(ctx)
@@ -280,7 +281,7 @@ func (m *Manager) transitionToMultiRepoMode(ctx context.Context, workDir string,
newRepoTrackers := make([]*WorkspaceTracker, 0, len(children))
for _, child := range children {
tracker := NewWorkspaceTrackerForRepo(child.path, child.name, m.logger)
tracker := m.newTrackerForRepo(child.path, child.name)
tracker.SetBaseBranch(lookupBaseBranch(m.getBaseBranches(), child.name))
tracker.SetAllowedSourceRoots(roots)
tracker.Start(ctx)
@@ -294,6 +295,7 @@ func (m *Manager) transitionToMultiRepoMode(ctx context.Context, workDir string,
old := m.workspaceTracker
m.workspaceTracker = bareRoot
m.repoTrackers = append(m.repoTrackers, newRepoTrackers...)
m.applyWorkspacePollModeLocked(append([]*WorkspaceTracker{bareRoot}, newRepoTrackers...)...)
m.cfg.WorkDir = workDir
m.workspaceSourceRoots = append([]string(nil), roots...)
m.cfg.WorkspaceSourceRoots = append([]string(nil), roots...)
@@ -326,7 +328,7 @@ func (m *Manager) appendNewRepoTrackers(ctx context.Context, workDir string, chi
m.logger.Info("adding per-repo tracker after rescan",
zap.String("repository_name", child.name),
zap.String("path", child.path))
tracker := NewWorkspaceTrackerForRepo(child.path, child.name, m.logger)
tracker := m.newTrackerForRepo(child.path, child.name)
tracker.SetBaseBranch(lookupBaseBranch(m.getBaseBranches(), child.name))
tracker.SetAllowedSourceRoots(roots)
tracker.Start(ctx)
@@ -352,6 +354,7 @@ func (m *Manager) appendNewRepoTrackers(ctx context.Context, workDir string, chi
continue
}
m.repoTrackers = append(m.repoTrackers, t)
m.applyWorkspacePollModeLocked(t)
}
m.cfg.WorkDir = workDir
m.workspaceSourceRoots = append([]string(nil), roots...)
@@ -390,7 +393,7 @@ func (m *Manager) reconcileRepoTrackers(ctx context.Context, workDir string, chi
if _, needed := wanted[repositoryTrackerIdentity(child.name, child.path)]; !needed {
continue
}
tracker := NewWorkspaceTrackerForRepo(child.path, child.name, m.logger)
tracker := m.newTrackerForRepo(child.path, child.name)
tracker.SetBaseBranch(lookupBaseBranch(m.getBaseBranches(), child.name))
tracker.SetAllowedSourceRoots(roots)
tracker.Start(ctx)
@@ -402,6 +405,7 @@ func (m *Manager) reconcileRepoTrackers(ctx context.Context, workDir string, chi
m.repoTrackersMu.Lock()
retained = append(retained, newTrackers...)
m.repoTrackers = retained
m.applyWorkspacePollModeLocked(newTrackers...)
m.cfg.WorkDir = workDir
m.workspaceSourceRoots = append([]string(nil), roots...)
m.cfg.WorkspaceSourceRoots = append([]string(nil), roots...)
@@ -85,6 +85,12 @@ func (wt *WorkspaceTracker) SetPollMode(mode PollMode) {
}
wt.pollModeMu.Lock()
// Record the push and drop the fallback timer before the no-op check: a
// push that matches the current mode changes nothing about the cadence but
// still proves the gateway is managing this workspace, which is exactly
// what the grace demotion exists to detect the absence of.
wt.pollModePushed = true
wt.disarmPollModeGraceLocked()
prev := wt.pollMode
if prev == mode {
wt.pollModeMu.Unlock()
@@ -93,11 +99,35 @@ func (wt *WorkspaceTracker) SetPollMode(mode PollMode) {
wt.pollMode = mode
wt.pollModeMu.Unlock()
// Wake both polling loops. Each has its own buffered(1) channel because
// a single shared channel would let whichever loop selects first steal
// the signal, leaving the other loop blocked on its old timer interval
// (potentially 30s) before noticing the mode change. Sends are non-blocking:
// if the buffer is full, a notification is already pending which is fine.
wt.wakePollLoops()
}
// demoteUnpushedPollMode drops the tracker to slow once pollModeGracePeriod
// elapses with no explicit SetPollMode. Fires at most once — the timer is not
// rearmed — so a later push always wins.
func (wt *WorkspaceTracker) demoteUnpushedPollMode() {
wt.pollModeMu.Lock()
wt.pollModeGraceTimer = nil
if wt.pollModePushed || wt.pollMode == PollModeSlow {
wt.pollModeMu.Unlock()
return
}
wt.pollMode = PollModeSlow
wt.pollModeMu.Unlock()
wt.logger.Info("no poll mode pushed within grace period, demoting to slow",
zap.Duration("grace", wt.pollModeGrace),
zap.String("workDir", wt.workDir))
wt.wakePollLoops()
}
// wakePollLoops nudges both polling loops so they re-read the mode and reset
// their timers immediately. Each has its own buffered(1) channel because a
// single shared channel would let whichever loop selects first steal the
// signal, leaving the other blocked on its old timer interval (potentially
// 30s) before noticing the change. Sends are non-blocking: if the buffer is
// full, a notification is already pending which is fine.
func (wt *WorkspaceTracker) wakePollLoops() {
for _, ch := range []chan struct{}{wt.monitorModeChanged, wt.gitPollModeChanged} {
select {
case ch <- struct{}{}:
@@ -0,0 +1,171 @@
package process
import (
"context"
"testing"
"time"
)
// waitForPollMode polls GetPollMode until it matches want or the deadline
// passes. Used only for the demotion assertions, where the transition is
// inherently timer-driven; the "must NOT demote" cases assert on timer state
// instead so they need no sleeping at all.
func waitForPollMode(t *testing.T, wt *WorkspaceTracker, want PollMode, timeout time.Duration) {
t.Helper()
deadline := time.Now().Add(timeout)
for time.Now().Before(deadline) {
if got := wt.GetPollMode(); got == want {
return
}
time.Sleep(5 * time.Millisecond)
}
t.Fatalf("poll mode = %v after %v, want %v", wt.GetPollMode(), timeout, want)
}
// assertGraceDisarmed reports whether the fallback can still fire. Asserting on
// the timer directly is deterministic: once a push has been recorded and the
// timer cleared, no amount of elapsed time can demote the tracker, so there is
// nothing to wait for.
func assertGraceDisarmed(t *testing.T, wt *WorkspaceTracker) {
t.Helper()
wt.pollModeMu.RLock()
pushed, timer := wt.pollModePushed, wt.pollModeGraceTimer
wt.pollModeMu.RUnlock()
if !pushed {
t.Error("push was not recorded, so the grace demotion can still fire")
}
if timer != nil {
t.Error("grace timer still armed after an explicit push")
}
}
const (
// graceNeverFires is long enough that the fallback cannot run mid-test.
// Every test asserting that a push disarmed the demotion needs it: with a
// short grace the timer can fire between Start and SetPollMode on a loaded
// machine, and the test would still pass while exercising a different path
// — a slow-to-fast transition instead of the case it claims to cover.
graceNeverFires = time.Hour
// graceFiresQuickly keeps the one test that genuinely waits for a demotion short.
graceFiresQuickly = 50 * time.Millisecond
)
func newGraceTestTracker(t *testing.T, grace time.Duration) *WorkspaceTracker {
t.Helper()
isolateTestGitEnv(t)
repoDir, cleanup := setupTestRepo(t)
t.Cleanup(cleanup)
wt := NewWorkspaceTracker(repoDir, newTestLogger(t))
// Long poll intervals keep the loops from doing real git work; these tests
// assert on the mode, not on scan output.
wt.filePollInterval = 30 * time.Second
wt.gitPollInterval = 30 * time.Second
wt.pollModeGrace = grace
return wt
}
// TestPollModeGrace_DemotesWhenNoPushArrives covers the leak this mechanism
// exists to close: the gateway only pushes a mode for workspaces a client
// focuses or subscribes to, and it deliberately skips the paused push for a
// workspace it has never pushed to. Without the grace demotion such a tracker
// stays at the fast 2s/3s cadence for the life of the process.
func TestPollModeGrace_DemotesWhenNoPushArrives(t *testing.T) {
wt := newGraceTestTracker(t, graceFiresQuickly)
if got := wt.GetPollMode(); got != PollModeFast {
t.Fatalf("construction mode = %v, want %v", got, PollModeFast)
}
wt.Start(context.Background())
defer wt.Stop()
waitForPollMode(t, wt, PollModeSlow, 10*time.Second)
}
// TestPollModeGrace_ExplicitPushDisarmsDemotion verifies the gateway wins: once
// it has spoken for a workspace, the fallback must never override it. The push
// is a mode-changing one, and the grace is long enough that it cannot fire —
// so the slow mode asserted below can only have come from the push.
func TestPollModeGrace_ExplicitPushDisarmsDemotion(t *testing.T) {
wt := newGraceTestTracker(t, graceNeverFires)
wt.Start(context.Background())
defer wt.Stop()
wt.SetPollMode(PollModeSlow)
assertGraceDisarmed(t, wt)
if got := wt.GetPollMode(); got != PollModeSlow {
t.Errorf("poll mode = %v after an explicit slow push, want %v", got, PollModeSlow)
}
}
// TestPollModeGrace_NoOpPushStillDisarms pins the subtle case: pushing the mode
// the tracker is already in changes no cadence, but it does prove the gateway
// is managing this workspace — which is precisely what the grace demotion
// exists to detect the absence of. Recording the push must therefore happen
// before SetPollMode's same-mode early return.
func TestPollModeGrace_NoOpPushStillDisarms(t *testing.T) {
wt := newGraceTestTracker(t, graceNeverFires)
wt.Start(context.Background())
defer wt.Stop()
// Same mode the tracker was constructed with — a no-op for the cadence. The
// long grace is what makes it one: had the fallback been able to demote
// first, this would be a slow-to-fast transition and the test would prove
// nothing about the same-mode path.
wt.SetPollMode(PollModeFast)
assertGraceDisarmed(t, wt)
if got := wt.GetPollMode(); got != PollModeFast {
t.Errorf("poll mode = %v after a no-op push, want it left at %v", got, PollModeFast)
}
}
// TestPollModeGrace_NotArmedWhenNeverStarted guards against a tracker that is
// constructed but never started allocating a fallback timer — one nothing would
// ever disarm, since only Stop clears it.
func TestPollModeGrace_NotArmedWhenNeverStarted(t *testing.T) {
wt := newGraceTestTracker(t, graceNeverFires)
wt.pollModeMu.RLock()
armed := wt.pollModeGraceTimer != nil
wt.pollModeMu.RUnlock()
if armed {
t.Error("grace timer armed on a tracker that was never started")
}
if got := wt.GetPollMode(); got != PollModeFast {
t.Errorf("poll mode = %v on an unstarted tracker, want %v", got, PollModeFast)
}
}
// TestPollModeGrace_StopDisarmsTimer covers teardown inside the grace window:
// Stop must clear the pending timer so it cannot fire against a torn-down
// tracker and so it holds no reference past the tracker's lifetime.
func TestPollModeGrace_StopDisarmsTimer(t *testing.T) {
// The long grace is what makes this test meaningful: the timer is certain to
// still be pending when Stop runs.
wt := newGraceTestTracker(t, graceNeverFires)
wt.Start(context.Background())
wt.pollModeMu.RLock()
armed := wt.pollModeGraceTimer != nil
wt.pollModeMu.RUnlock()
if !armed {
t.Fatal("grace timer was not armed by Start")
}
wt.Stop()
wt.pollModeMu.RLock()
timer := wt.pollModeGraceTimer
wt.pollModeMu.RUnlock()
if timer != nil {
t.Error("grace timer still armed after Stop")
}
if got := wt.GetPollMode(); got != PollModeFast {
t.Errorf("Stop changed the poll mode to %v, want it left at %v", got, PollModeFast)
}
}
@@ -24,6 +24,13 @@ const DefaultGitPollInterval = 3 * time.Second
// a wedged Git process cannot retain the tracker flight indefinitely.
const workspaceGitStatusObserveTimeout = 60 * time.Second
// pollModeGracePeriod is how long a tracker stays at its fast construction
// default before demoting itself to slow when no explicit mode ever arrives.
// Long enough to cover a freshly-spawned instance being opened by the user
// (the gateway pushes within milliseconds of a focus), short enough that a
// workspace nobody watches stops scanning almost immediately.
const pollModeGracePeriod = 60 * time.Second
// fileStatus constants for FileInfo.Status values.
const (
fileStatusDeleted = "deleted"
@@ -75,11 +82,20 @@ type WorkspaceTracker struct {
gitPollInterval time.Duration
// pollMode is the current rate at which the polling loops scan git state.
// Default at construction is PollModeSlow — safe fallback before the gateway
// pushes a focus signal. Mutate via SetPollMode (never directly) so loops
// receive the wake-up notification on transitions.
// Default at construction is PollModeFast so a freshly-spawned instance has
// no blind window, then pollModeGraceTimer demotes it to slow unless the
// gateway pushes a mode first. Mutate via SetPollMode (never directly) so
// loops receive the wake-up notification on transitions.
pollMode PollMode
pollModeMu sync.RWMutex
// pollModePushed records that an explicit SetPollMode arrived, which
// disarms the grace demotion for good — from then on the gateway owns the
// mode. Guarded by pollModeMu.
pollModePushed bool
pollModeGraceTimer *time.Timer
// pollModeGrace is pollModeGracePeriod in production; tests shorten it the
// same way they shorten filePollInterval / gitPollInterval.
pollModeGrace time.Duration
// One channel per loop because we need both loops to wake up on a mode
// change. A single shared channel would let the first reader steal the
// signal so only one loop wakes.
@@ -238,15 +254,17 @@ func newWorkspaceTracker(resolvedWorkDir, repositoryName string, log *logger.Log
workspaceStreamSubscribers: make(map[types.WorkspaceStreamSubscriber]struct{}),
filePollInterval: DefaultFilePollInterval,
gitPollInterval: DefaultGitPollInterval,
// Default to fast polling — matches pre-PR behavior so newly-created
// agentctl instances don't have a startup window where changes go
// undetected for up to 30s. The gateway pushes slow/paused once it
// knows no client is actively watching this workspace; until then,
// fast is the safe default (a freshly-spawned instance was always
// about to be used by someone, historically). Retained-task CPU
// savings still apply because those instances eventually receive a
// slow or paused mode push.
// Start fast so a freshly-spawned instance — which is usually about to
// be opened by someone — has no window where changes go unnoticed.
// Start() then arms pollModeGraceTimer: the gateway only pushes a mode
// for workspaces a client focuses or subscribes to, and it deliberately
// skips the paused push for a workspace it has never pushed to
// (workspacePollAggregator.plan). Without the timer, a tracker the
// gateway never speaks about scans at 2s/3s for the life of the
// process. Trackers created after launch inherit the workspace's
// current mode instead — see Manager.configurePollMode.
pollMode: PollModeFast,
pollModeGrace: pollModeGracePeriod,
monitorModeChanged: make(chan struct{}, 1),
gitPollModeChanged: make(chan struct{}, 1),
stopCh: make(chan struct{}),
@@ -390,6 +408,28 @@ func (wt *WorkspaceTracker) Start(_ context.Context) {
// Start git polling for detecting manual git operations (commits, resets, etc.)
wt.wg.Add(1)
go wt.pollGitChanges(wt.cancelCtx)
wt.armPollModeGrace()
}
// armPollModeGrace schedules the fallback demotion to slow. Armed here rather
// than in the constructor so a tracker that is built but never started leaves
// no timer behind. A SetPollMode that lands first disarms it permanently.
func (wt *WorkspaceTracker) armPollModeGrace() {
wt.pollModeMu.Lock()
defer wt.pollModeMu.Unlock()
if wt.pollModePushed || wt.pollModeGraceTimer != nil || wt.pollModeGrace <= 0 {
return
}
wt.pollModeGraceTimer = time.AfterFunc(wt.pollModeGrace, wt.demoteUnpushedPollMode)
}
// disarmPollModeGraceLocked stops the fallback timer. Caller must hold pollModeMu.
func (wt *WorkspaceTracker) disarmPollModeGraceLocked() {
if wt.pollModeGraceTimer != nil {
wt.pollModeGraceTimer.Stop()
wt.pollModeGraceTimer = nil
}
}
// stopTimeout is the maximum time Stop() will wait for goroutines to exit.
@@ -399,6 +439,10 @@ const stopTimeout = 5 * time.Second
// up to 5 seconds for goroutines to exit before proceeding.
func (wt *WorkspaceTracker) Stop() {
wt.stopOnce.Do(func() {
wt.pollModeMu.Lock()
wt.disarmPollModeGraceLocked()
wt.pollModeMu.Unlock()
// Synchronize cancellation with shared-observation admission. Once this
// lock is released, no observation can Add to gitStatusObserveWG.
wt.gitStatusObserveMu.Lock()