Files
kandev/apps/backend/internal/agentctl/server/process/manager_rescan.go
T
João Salavisa fd79d6170f feat(tasks): multi-branch tasks — N (repo, branch) pairs per task (#1226)
* feat(tasks): multi-branch tasks — N (repo, branch) pairs per task

Extends multi-repo into multi-branch so a single task can hold multiple
worktrees on the same repo (one per branch). Sibling worktrees layout at
<task>/<repo>/ + <task>/<repo>-<slug>/, dedicated PRWatch per branch,
live agentctl tracker rescan + frontend store updates so the UI splits
PRs / files / commits per branch without a session restart. MCP
add_branch_to_task_kandev tool is shielded to the worktree executor.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(web): unify multi-branch repo label as <repo> · <branch> across panels

PR Changes and Commits panels rendered repo labels differently for multi-branch
tasks — Commits showed "kandev · feature/x" while PR Changes leaked the raw
"kandev-feature-x" agentctl tracker tag. Reformat tracker-tagged repo names via
formatRepoLabel using the longest known-repo prefix so kandev-cli-* doesn't
collapse to kandev · cli-*.

* fix(tasks): address multi-branch PR review — data races, slug collisions, MCP error codes

Backend
- agentctl process.Manager: add repoTrackersMu RWMutex guarding repoTrackers
  + workspaceTracker. Reads snapshot under RLock; RescanRepositories builds
  trackers first, takes Lock for swap/append. Validates newWorkDir via
  os.Stat before publishing cfg.WorkDir.
- worktree.Manager: reject invalid explicit BranchSlug up-front; cache key
  uses sanitized wt.BranchSlug so read/write paths are symmetric.
- worktree.store: narrow isDuplicateColumnError to "duplicate column name".
- task service AddBranchToTask: slug-collision guard rejects feat/a vs feat-a.
- orchestrator resolvePushRepo: two-pass exact-name match before subdir
  prefix fallback so "backend" doesn't swallow pushes for "backend-admin".
- executor buildRepoSpecs: duplicate repos always get a non-empty BranchSlug
  (falls back to branch-N when both branch fields sanitize to empty).
- MCP handler: classifyAddBranchError maps service errors to NOT_FOUND /
  CONFLICT / VALIDATION_ERROR; add ErrorCodeConflict constant.
- MCP server: extract registerAddBranchToTaskTool, register in task mode
  only (external mode contract: config tools + create_task_kandev).
- workspace_rescan handler: reject malformed JSON with 400 instead of
  silently rescanning the current root.
- branch_materializer: split MaterializeBranch into prepare + finalize
  helpers to satisfy the 80-line cap.

Frontend
- existingPrUrl returns undefined when a task has >1 PR so per-repo View PR
  buttons take over (no silent linking to a sibling).
- formatRepoLabel checks exact known-repo match before prefix splitting so
  "kandev-cli" isn't mislabeled as "kandev · cli".
- Repo chip key now includes base_branch so siblings differing only on
  base render as distinct chips.

Docs
- multi-branch spec uniqueness wording aligned with the canonical 4-column
  key (task_id, repository_id, base_branch, checkout_branch).
- worktree.CreateRequest.BranchSlug doc describes the sibling layout
  (<repo>-<slug>) instead of the obsolete nested form.

* fix(tasks): scope slug-collision check to repo only + use errors.Is for ErrTaskNotFound

- service_branches: drop base_branch from the slug-collision check. Worktree
  path is (repo, slug); two rows on the same repo cut from different bases
  still collide on disk.
- service_branches: prepareBranchAdd wraps taskrepo.ErrTaskNotFound via
  fmt.Errorf with %w so classifiers don't have to substring-match the
  formatted task UUID.
- mcp handlers: classifyAddBranchError uses errors.Is(err, ErrTaskNotFound).

* fix(agentctl): sanitize rescan work_dir before os.Stat to clear CodeQL path-injection

CodeQL flagged the rescan endpoint as a path-injection sink (the
HTTP-supplied work_dir flowed straight into os.Stat and downstream
scanRepositorySubdirs). Add validateRescanPath which:
- requires the input to be a clean absolute path with no ".." segments
- rejects anything that isn't equal to or an ancestor of the current
  cfg.WorkDir — the only legitimate use case is the branch materializer
  promoting <task>/<repo>/ to <task>/

Defense in depth: agentctl binds to localhost, but any colocated process
could otherwise direct it at /etc or the user's home by POSTing
/api/v1/workspace/rescan.

* fix(agentctl): tighten validateRescanPath, close TOCTOU on existingTrackers, add tests

- Drop the strings.Contains(clean, "..") guard. filepath.Clean already
  resolves traversal; the substring check rejects legitimate names like
  /home/u/..hidden without adding defense (the ancestor check via
  filepath.Rel is the real boundary).
- Drop the rel == "." branch in the ancestor check — early return for
  clean == currentClean already covers identity.
- Read existingTrackers inside the write-lock section (not under RLock
  then re-Lock) so two concurrent rescans can't both see 0 trackers and
  double-bootstrap the multi-repo set.
- Add table-driven TestValidateRescanPath covering rejection paths
  (relative, descendant, sibling, traversal-cleaned, empty input),
  legitimate ancestor promotion, exact match, no-anchor first-launch,
  and a /home/u/..hidden dotted-segment case.

* fix(agentctl): break taint flow into os.Stat — derive rescan path from cfg, not HTTP body

CodeQL's go/path-injection trace still flagged manager_rescan.go after the
prior sanitizer because the user-supplied newWorkDir flowed (after
validation) into os.Stat and then into cfg.WorkDir → tracker paths →
workspace_monitor os.Stat sinks.

Replace validateRescanPath with resolveRescanPath: it returns a path
DERIVED from currentWorkDir (no-op = currentClean, promotion =
filepath.Dir(currentClean)) and uses newPath only for comparison, never
as a source for the returned string. os.Stat now receives a path whose
provenance is trusted manager config.

Functionally the legitimate caller (branch materializer promoting
<task>/<repo>/ to <task>/) is unchanged.

* test(agentctl): make TestResolveRescanPath windows-portable

The Linux Backend Tests job passed but the Backend (windows) job rejected
every "absolute" case because filepath.IsAbs("/task/repo") is false on
Windows (no volume letter).

Build inputs via filepath.Join against absRoot() (filepath.Abs of "/" /
"\\") so the same table covers POSIX (`/...`) and Windows (`C:\...`)
without per-OS branches. Keep the traversal-after-Clean case POSIX-only
since filepath.Clean is the shared primitive and that input form needs a
volume to be considered absolute on Windows anyway.

* fix(agentctl): serialize RescanRepositories + re-check trackers under write lock

Two concurrent RescanRepositories calls could both observe an empty
tracker set (between the snapshot read and the bootstrap branch) and both
enter transitionToMultiRepoMode, leaking a duplicate bare-root tracker
and duplicate per-repo trackers. Same race in appendNewRepoTrackers would
double-append the same new child across both callers.

Fix:
- Add rescanMu sync.Mutex on Manager. Acquired for the full body of
  RescanRepositories so the snapshot → branch → mutate sequence is
  serialized. repoTrackersMu still guards individual field reads from
  unrelated goroutines (subscribe/unsubscribe/poll-mode).
- appendNewRepoTrackers re-checks membership inside the write-lock
  before appending and drops already-present trackers (Stop + detach
  outside the lock). Defense in depth.
- Test: add `dotted segment is legal as promotion` case so the
  ..hidden-segment promotion path stays exercised.

---------

Co-authored-by: Kandev Agent <agent@kandev.dev>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-01 19:36:20 +01:00

254 lines
9.5 KiB
Go

package process
import (
"context"
"os"
"path/filepath"
"go.uber.org/zap"
"github.com/kandev/kandev/internal/agentctl/types"
)
// RescanRepositories re-discovers the git-worktree children under newWorkDir
// (or cfg.WorkDir when newWorkDir is empty) and reconciles the running set of
// workspace trackers against the result. It exists for the multi-branch
// add-branch flow where a sibling worktree appears on disk AFTER the agent
// has launched — without a rescan, the original tracker set is frozen at
// construct time and the new worktree's file/git events never reach the UI.
//
// Behavior:
// - When newWorkDir is non-empty and differs from cfg.WorkDir, cfg.WorkDir
// is updated. The agent's CWD is NOT touched: this controls only what
// the WORKSPACE trackers monitor, not where the child process runs.
// - When the manager is in single-repo mode (no repoTrackers, single
// workspaceTracker bound to a primary worktree) and the rescan finds
// >= 2 sibling git children, it transitions to multi-repo mode:
// the existing single-repo tracker is replaced by a bare task-root
// tracker, and a per-repo tracker is created for each child including
// the original primary (so its events get tagged with RepositoryName).
// - When the manager is already in multi-repo mode, only NEW per-repo
// trackers (children whose RepositoryName isn't currently tracked) are
// added; stale trackers (children no longer present on disk) are left
// in place — removal would race with in-flight notifications and the
// stale tracker's git index path stops emitting anyway.
// - All new trackers are Start()-ed and attached to every existing
// workspace-stream subscriber so events flow without re-subscription.
//
// Idempotent: a rescan with no on-disk changes is a no-op.
func (m *Manager) RescanRepositories(ctx context.Context, newWorkDir string) {
// Serialize the whole rescan body. Two concurrent calls could otherwise
// both observe existingTrackers == 0 between the write-lock snapshot
// and the bootstrap branch, both calling transitionToMultiRepoMode and
// leaking a duplicate bare-root tracker + duplicate per-repo trackers.
m.rescanMu.Lock()
defer m.rescanMu.Unlock()
// Resolve the candidate workDir and prove it's a readable directory
// BEFORE committing cfg.WorkDir. If newWorkDir is bogus, leaving the
// manager pointing at the existing root keeps path-based handlers
// (vscode, git, files) consistent with the trackers that never moved.
m.repoTrackersMu.RLock()
candidate := m.cfg.WorkDir
m.repoTrackersMu.RUnlock()
if newWorkDir != "" && newWorkDir != candidate {
resolved, ok := resolveRescanPath(newWorkDir, candidate)
if !ok {
m.logger.Warn("workspace rescan: ignoring invalid work_dir",
zap.String("work_dir", newWorkDir),
zap.String("current_work_dir", candidate))
return
}
// resolved is derived from currentWorkDir (trusted manager config),
// not from newWorkDir, so os.Stat here doesn't see HTTP-supplied
// input. CodeQL's path-injection trace ends at resolveRescanPath.
if info, err := os.Stat(resolved); err == nil && info.IsDir() {
candidate = resolved
} else {
m.logger.Warn("workspace rescan: ignoring invalid work_dir",
zap.String("work_dir", newWorkDir), zap.Error(err))
return
}
}
// Read existingTrackers under the same write-lock that commits the new
// cfg.WorkDir so two concurrent rescans don't both observe 0 trackers
// and double-bootstrap the multi-repo set.
m.repoTrackersMu.Lock()
m.cfg.WorkDir = candidate
workDir := m.cfg.WorkDir
existingTrackers := len(m.repoTrackers)
m.repoTrackersMu.Unlock()
children := scanRepositorySubdirs(workDir)
subs := m.snapshotSubscribers()
m.logger.Info("workspace rescan started",
zap.String("work_dir", workDir),
zap.Int("children_found", len(children)),
zap.Int("existing_repo_trackers", existingTrackers),
zap.Int("subscribers", len(subs)))
if len(children) < 2 {
// Nothing to do: a non-multi-repo workspace stays on its single
// tracker. The legacy preferGitRepoChildIfRootIsBare fallback
// covers single-repo construct-time setup.
return
}
if existingTrackers == 0 {
m.transitionToMultiRepoMode(ctx, workDir, children, subs)
return
}
m.appendNewRepoTrackers(ctx, children, subs)
}
// transitionToMultiRepoMode replaces the single-repo workspaceTracker with a
// bare task-root tracker and stands up per-repo trackers for every detected
// child. Used when the agent launched as single-repo and a sibling worktree
// was added afterwards.
func (m *Manager) transitionToMultiRepoMode(ctx context.Context, workDir string, children []repositorySubdir, subs []types.WorkspaceStreamSubscriber) {
m.logger.Info("transitioning workspace to multi-repo mode",
zap.String("work_dir", workDir),
zap.Int("children", len(children)))
bareRoot := NewWorkspaceTrackerForRepo(workDir, "", m.logger)
bareRoot.Start(ctx)
for _, sub := range subs {
bareRoot.AttachWorkspaceStreamSubscriber(sub)
}
newRepoTrackers := make([]*WorkspaceTracker, 0, len(children))
for _, child := range children {
tracker := NewWorkspaceTrackerForRepo(child.path, child.name, m.logger)
tracker.Start(ctx)
for _, sub := range subs {
tracker.AttachWorkspaceStreamSubscriber(sub)
}
newRepoTrackers = append(newRepoTrackers, tracker)
}
m.repoTrackersMu.Lock()
old := m.workspaceTracker
m.workspaceTracker = bareRoot
m.repoTrackers = append(m.repoTrackers, newRepoTrackers...)
m.repoTrackersMu.Unlock()
if old != nil {
for _, sub := range subs {
old.DetachWorkspaceStreamSubscriber(sub)
}
old.Stop()
}
}
// appendNewRepoTrackers adds trackers for child subdirs that don't already
// have one. Existing trackers (matched by RepositoryName) are left running
// so their cached git state and subscriber wiring stay intact.
func (m *Manager) appendNewRepoTrackers(ctx context.Context, children []repositorySubdir, subs []types.WorkspaceStreamSubscriber) {
m.repoTrackersMu.RLock()
existing := make(map[string]bool, len(m.repoTrackers))
for _, t := range m.repoTrackers {
existing[t.RepositoryName()] = true
}
m.repoTrackersMu.RUnlock()
var newTrackers []*WorkspaceTracker
for _, child := range children {
if existing[child.name] {
continue
}
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.Start(ctx)
for _, sub := range subs {
tracker.AttachWorkspaceStreamSubscriber(sub)
}
newTrackers = append(newTrackers, tracker)
}
if len(newTrackers) == 0 {
return
}
// Re-check membership inside the write-lock as a defense-in-depth
// guard. rescanMu already serializes RescanRepositories callers, but
// the explicit check here makes the invariant local: any tracker
// already in the slice by name is dropped before append, so even if
// the invariant moved, duplicates would still be rejected.
m.repoTrackersMu.Lock()
stillExisting := make(map[string]bool, len(m.repoTrackers))
for _, t := range m.repoTrackers {
stillExisting[t.RepositoryName()] = true
}
var dropped []*WorkspaceTracker
for _, t := range newTrackers {
if stillExisting[t.RepositoryName()] {
dropped = append(dropped, t)
continue
}
m.repoTrackers = append(m.repoTrackers, t)
}
m.repoTrackersMu.Unlock()
// Stop + detach any dropped trackers outside the lock so we don't block
// readers on potentially-slow Stop() teardown.
for _, t := range dropped {
for _, sub := range subs {
t.DetachWorkspaceStreamSubscriber(sub)
}
t.Stop()
}
}
// resolveRescanPath maps an externally-supplied workspace path to a known-good
// path derived from the manager's existing cfg.WorkDir, breaking the taint
// flow from the HTTP body into os.Stat / downstream tracker paths. The only
// legitimate caller (kandev backend's branch materializer) promotes the
// workdir up exactly one level — from <task>/<repo>/ to <task>/ — so the
// allowed transitions are:
// - newPath equals currentWorkDir → no-op (return current)
// - newPath equals parent of current → return derived parent
//
// Critically, the returned path is ALWAYS derived from currentWorkDir
// (which originates in trusted manager config), never from newPath itself.
// CodeQL's go/path-injection taint analysis cleared once the sink stopped
// receiving the HTTP-supplied string directly.
//
// Returns ("", false) for any other input — first-launch case (currentWorkDir
// empty) is handled by the caller falling back to the existing workdir.
func resolveRescanPath(newPath, currentWorkDir string) (string, bool) {
if newPath == "" || currentWorkDir == "" {
return "", false
}
clean := filepath.Clean(newPath)
if !filepath.IsAbs(clean) {
return "", false
}
currentClean := filepath.Clean(currentWorkDir)
if clean == currentClean {
return currentClean, true
}
parent := filepath.Dir(currentClean)
if parent == currentClean {
// currentWorkDir is already filesystem root; no promotion possible.
return "", false
}
if clean == parent {
return parent, true
}
return "", false
}
// snapshotSubscribers returns a copy of the current workspace-stream
// subscribers so rescan callers can attach new trackers without holding the
// subscriber lock during git-status replays.
func (m *Manager) snapshotSubscribers() []types.WorkspaceStreamSubscriber {
m.streamSubscribersMu.Lock()
defer m.streamSubscribersMu.Unlock()
out := make([]types.WorkspaceStreamSubscriber, 0, len(m.streamSubscribers))
for s := range m.streamSubscribers {
out = append(out, s)
}
return out
}