Allow disabling or limiting built-in Git monitoring and background fetch

[mtklee]

Moved from #2451 at the repository's request after the issue was classified as a feature request.

Related scaling evidence: #2470 documents forge polling exhausting the machine-wide GitHub GraphQL quota in large multi-workspace setups. The original workflow, measurements, proposed controls, and acceptance criteria are preserved below for discussion.

---

Summary

Please add a supported way to disable Paseo's built-in Git integration, or independently disable its background Git features, at the daemon level.

This is intended as a reliability escape hatch for large multi-workspace setups and for Windows environments where Git child-process cleanup can interact badly with agent providers.

Motivation

I encountered repeated failed to load agent, provider refresh timeouts, and daemon liveness timeouts while using Paseo with many Git workspaces and Codex sessions on Windows.

During diagnosis, two different Git command producers were observed:

1. Paseo daemon Git reads, recognizable by commands such as:
   • git -c core.quotepath=false rev-parse ...
   • workspace status / branch / repo-root probes
2. Codex app-server repository probes, including:
   • git status --porcelain
   • git rev-parse HEAD
   • git rev-parse --git-dir
   • git remote -v
   • git config --null --get core.fsmonitor

The process accumulation was therefore not attributed solely to Paseo. However, Paseo currently has no supported escape hatch when Git polling contributes to process pressure or amplifies an upstream provider process-lifetime issue.

At peak load, many short-lived or orphaned git.exe processes accumulated, agent loading timed out, provider refresh hit a 60-second timeout, and even process/WMI inspection became slow. Archiving oversized sessions and moving active context to small handoff sessions reduced conversation-loading work but did not by itself eliminate the Git-process pressure.

Current behavior in v0.2.1

The only apparent Git-specific environment control is:

const gitConcurrency = parseInt(process.env.PASEO_GIT_CONCURRENCY ?? "8", 10) || 8;

Source: run-git-command.ts

This limits concurrency but cannot disable Git. Setting it to 0 falls back to 8 because of || 8.

The workspace Git service also has fixed background behavior, including:

• background fetch every 180 seconds;
• self-heal refresh every 60 seconds;
• a 5-second timed refresh fallback when working-tree watchers are unavailable.

Source: workspace-git-service.ts

The persisted daemon config schema has no Git enable/disable section:

Source: persisted-config.ts

Workaround and result

The following workaround substantially improved stability:

• set PASEO_GIT_CONCURRENCY=2;
• make the Codex provider resolve Git/mingw64/bin/git.exe before Git for Windows' small cmd/git.exe launcher;
• restart the Paseo daemon/provider;
• preserve large original sessions as archived sessions and use small handoff successors.

After restart, daemon health returned ok in approximately 0.4-0.6 seconds. Eight Git-process samples over 40 seconds showed 3-7 transient Git processes and zero dead-parent Git processes. Existing handoff successor agents loaded repeatedly in approximately 5-9 seconds.

This mitigation is useful, but it is not equivalent to a supported disable switch and may not protect against future provider regressions or unusually large workspace sets.

Proposed configuration

For example:

{
  "daemon": {
    "git": {
      "enabled": true,
      "workspaceWatch": true,
      "backgroundFetch": true,
      "forgePolling": true,
      "concurrency": 8
    }
  }
}

Suggested semantics:

• enabled: false
  • do not start Git watchers, self-heal timers, background fetch, forge polling, or automatic Git snapshot commands;
  • keep agent execution, terminals, file access, and non-Git workspace/session management functional;
  • present Git-derived UI as unavailable/disabled rather than repeatedly probing.
• workspaceWatch: false
  • disable watcher and timed-fallback status refresh while still allowing explicit user-requested Git actions.
• backgroundFetch: false
  • retain local status/diff support but never run automatic git fetch.
• forgePolling: false
  • disable GitHub/GitLab PR status polling independently.
• concurrency
  • expose the existing limit as documented config;
  • either accept 0 as a documented disable value or reject it explicitly instead of silently converting it to 8.

Equivalent environment variables would also be useful for daemon/headless deployments, for example:

PASEO_GIT_ENABLED=0
PASEO_GIT_BACKGROUND_FETCH=0
PASEO_GIT_WORKSPACE_WATCH=0
PASEO_GIT_FORGE_POLLING=0
PASEO_GIT_CONCURRENCY=1

Defaults could preserve today's behavior for backward compatibility.

Acceptance criteria

1. With Git integration disabled, the Paseo daemon spawns no automatic git processes for registered workspaces.
2. Existing agents and sessions can still be listed, opened, resumed, and run.
3. Terminal and file functionality remains available.
4. Git-dependent UI and mutations are clearly marked unavailable, rather than hanging or polling.
5. Disabling only background fetch leaves local status/diff behavior working without network fetches.
6. Disabling workspace monitoring prevents watcher, fallback-refresh, and self-heal timers from invoking Git.
7. The active Git mode and effective concurrency are logged once at daemon startup.
8. The configuration and environment variables are documented.

Why this matters

Git integration is valuable, but it should not be mandatory for the core agent/session experience. A kill switch would provide a safe recovery path when:

• a provider version leaks or fails to reap Git descendants;
• Git for Windows launcher behavior causes process-tree cleanup problems;
• one unusually large repository makes periodic status/diff operations expensive;
• a user primarily wants remote agent/session control and does not need Paseo's Git UI;
• daemon health must take priority over live branch/diff/PR metadata.

A granular setting would let users preserve the useful parts of Paseo while isolating Git-related operational failures.

---

Original issue: #2451

Related investigation: #2470