diff --git a/bin/cli.js b/bin/cli.js
index 0d36b99..ec1c572 100755
--- a/bin/cli.js
+++ b/bin/cli.js
@@ -16,7 +16,31 @@ if (process.argv[1] && process.argv[1].includes('codedash') && !process.argv[1].
 }
 
 const { loadSessions, searchFullText, getSessionPreview, computeSessionCost } = require('../src/data');
-const { startServer } = require('../src/server');
+const { startServer, getKnownGitRoots } = require('../src/server');
+const { repoRefreshManager } = require('../src/repo-refresh');
+
+function bootRepoRefresh() {
+  // Wire the known-roots gate so initOnStartup can't fetch arbitrary paths
+  // injected into the settings file by another process.
+  let gateWired = false;
+  try {
+    repoRefreshManager.setKnownGitRootsProvider(getKnownGitRoots);
+    gateWired = true;
+  } catch (err) {
+    console.error('[repo-refresh] failed to wire known-roots provider:', err.message);
+  }
+  // If the gate is not wired we MUST NOT run initOnStartup — it would fetch
+  // arbitrary paths from the settings file without validation.
+  if (!gateWired) {
+    console.error('[repo-refresh] skipping initOnStartup because gate is not wired');
+    return;
+  }
+  // Fire-and-forget — initOnStartup never blocks; errors land in per-repo state.
+  process.nextTick(() => {
+    try { repoRefreshManager.initOnStartup(); }
+    catch (err) { console.error('[repo-refresh] init failed:', err.message); }
+  });
+}
 const { exportArchive, importArchive } = require('../src/migrate');
 const { convertSession } = require('../src/convert');
 const { generateHandoff, quickHandoff } = require('../src/handoff');
@@ -66,6 +90,7 @@ switch (command) {
     const host = hostArg ? hostArg.split('=')[1] : (process.env.CODEDASH_HOST || DEFAULT_HOST);
     const noBrowser = args.includes('--no-browser');
     startServer(host, port, !noBrowser);
+    bootRepoRefresh();
     break;
   }
 
@@ -321,6 +346,7 @@ switch (command) {
       console.log('  Starting...\n');
       const noBrowser = args.includes('--no-browser');
       startServer(host, port, !noBrowser);
+      bootRepoRefresh();
     }, 500);
     break;
   }
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 1d70008..30d14d2 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -360,6 +360,113 @@ GET  /api/changelog             Changelog entries
 GET  /api/terminals             Available terminal apps
 ```
 
+### Repo Auto-Refresh
+```
+GET  /api/repo-refresh/state              Per-repo state + current settings
+POST /api/repo-refresh/trigger            Start `git fetch --all --prune` for one repo
+POST /api/repo-refresh/wait               Long-poll until a fetch finishes (or timeoutMs, default 2000, max 10000)
+GET  /api/repo-refresh/settings           Read settings
+POST /api/repo-refresh/settings           Update settings (partial; merged + atomically persisted)
+```
+
+---
+
+## Repo Auto-Refresh
+
+Keeps local clones of connected repositories in sync with their remote so the
+LLM in a fresh session sees current `origin/<branch>` and doesn't drift into
+branch divergence. The work runs in the background, never touches the working
+tree, and never blocks the HTTP server.
+
+### Triggers (v1)
+
+1. **Manual** — click the `↻` button on a project card.
+2. **New chat** — when a project has its "Auto-refresh on new chat" toggle on,
+   `launchNewProjectSession` / `resumeLastProjectSession` issue a fetch and
+   wait up to 2 s before opening the terminal session.
+3. **Service start** — when the global "Refresh on startup" toggle is on,
+   `bin/cli.js` calls `repoRefreshManager.initOnStartup()` after the HTTP
+   server has bound.
+
+Deferred to a future PR: periodic scheduler (5/10/15/30/60 min), page-refresh
+trigger, and "behind by N commits" indicators.
+
+### Per-repo state machine
+
+```
+       ┌───────────┐
+       │   idle    │  (lastSuccessAt: null | epoch)
+       └─────┬─────┘
+             │ trigger()
+             ▼
+       ┌───────────┐
+       │ fetching  │  (startedAt: epoch; single-flight per gitRoot)
+       └─┬───────┬─┘
+   ok    │       │   error / 60 s timeout
+         ▼       ▼
+       ┌───────┐ ┌────────┐
+       │ idle  │ │ error  │ (lastError truncated to ≤200 chars)
+       └───────┘ └────────┘
+```
+
+### Backend (`src/repo-refresh.js`)
+
+- Singleton manager built via `createRepoRefreshManager(opts)` — opts allow
+  test-time DI of `execFile`, timers, `atomicWriteJson`, `resolveGitRoot`,
+  `existsSync`, and `logger`.
+- **Single-flight** per `gitRoot` through an `inflight` Map — concurrent
+  triggers return the existing promise; no second child process is spawned.
+- **Concurrency cap** = 4 parallel `git fetch` processes; the 5th waits in a
+  FIFO queue. Sync fast path when capacity is available so the child process
+  starts before `triggerRefresh()` returns.
+- **Timeout** = 60 s. On expiry the manager sends `SIGTERM`, waits a 2 s
+  grace, then sends `SIGKILL`. State transitions to `error` with
+  `lastError = "timeout after 60000ms"`.
+- **Settings** live at `~/.codedash/refresh-settings.json`. Loaded on
+  construction; saved through `atomicWriteJson` with a 500 ms debounce so
+  rapid toggle clicks coalesce into one disk write.
+- **Orphan GC** — on every `initOnStartup`, perProject keys with
+  `!existsSync(gitRoot) || resolveGitRoot(gitRoot) === ''` are dropped and the
+  cleaned settings are persisted.
+
+### HTTP routes (`src/repo-refresh-routes.js`)
+
+Pure dispatcher function `handleRepoRefreshRoute(req, res, deps)` that returns
+`true` if it handled the request — mounted in `src/server.js` before the
+Sessions API. Validation rejects:
+
+- `POST /trigger` / `POST /settings` referencing a `gitRoot` not in the known
+  set (`loadProjects()` ∪ `loadSessions().git_root`, cached 5 s) → 404 / 400.
+- `POST /settings` body with the wrong shape → 400 `invalid_payload`.
+- `POST /trigger` body > 1 MiB → 400 `invalid_payload`.
+- `POST /wait timeoutMs` clamped to `[0, 10000]`.
+
+### Frontend (`src/frontend/app.js`)
+
+- Module-level `repoRefreshState` mirrors what the backend serves.
+- `loadRepoRefreshState()` runs once at init and after manual triggers; a
+  `setInterval(2000)` polls only while at least one visible repo is in
+  `fetching` and the user is on the Projects view.
+- Project card markup uses `data-rr-badge="<gitRoot>"` and
+  `data-rr-toggle="<gitRoot>"` attributes so `refreshRepoRefreshUI()` can
+  update badges and toggles in place without re-rendering the whole view
+  (preserves scroll position and group collapse state).
+- Toggle clicks are **optimistic**: the visual flips immediately, the POST
+  fires, and a failure rolls the visual back with a toast.
+- `maybeRefreshBeforeLaunch(gitRoot)` issues `/trigger` + `/wait` (timeoutMs:
+  2000) before invoking `/api/launch`. If the wait times out the session
+  opens with whatever refs are currently on disk; if the fetch errors the
+  user sees a toast but the launch proceeds.
+
+### Atomic JSON writes (`src/atomic.js`)
+
+`atomicWriteJson(filePath, obj)` is the canonical write helper for every
+codbash JSON cache. Steps: ensure parent dir, write to `<path>.tmp`, fsync,
+rename. On rename failure the temp file is unlinked and the original target
+is left untouched. The legacy disk caches (`_saveParsedDiskCache`,
+`_saveGitRootDiskCache`, `_saveCostDiskCache`, `_saveDailyStatsDiskCache` in
+`src/data.js`) all flow through this helper.
+
 ---
 
 ## Contributing
diff --git a/docs/design/repo-auto-refresh.md b/docs/design/repo-auto-refresh.md
new file mode 100644
index 0000000..7bbdb20
--- /dev/null
+++ b/docs/design/repo-auto-refresh.md
@@ -0,0 +1,308 @@
+# Repo Auto-Refresh (v1)
+
+## Goal
+
+Keep local clones of connected repositories in sync with their remotes so that when a session starts, the LLM works against current history and doesn't drift into branch divergence. Done in the background, without blocking the UI, without touching the working tree.
+
+## Context
+
+Codbash shows "projects" = git roots bound to a remote. Sessions are created by Claude/Codex/etc. inside these repos. When the remote moves forward (PR merged on GitHub), the local clone doesn't know until the user runs `git fetch` manually. The result:
+- A new session sees a stale `git log` / `origin/main`.
+- Branches created from `origin/main` start from an outdated base.
+- Continuing an old session can produce commits on top of stale state.
+
+## In scope (v1 — minimum useful core)
+
+1. **Per-project toggle** "Auto-refresh on new chat" in the Projects view.
+2. **Manual "Refresh" button** on the project card — fetch now.
+3. **Global toggle** "Refresh enabled repos on service start" (default off).
+4. Background worker on the backend running `git fetch --all --prune`.
+5. **Triggers**:
+   - Manual refresh button click → fetch this repo.
+   - New-chat click on a project with the toggle on → fetch + wait up to 2s before opening the session.
+   - Service start → fetch all enabled repos if the global toggle is on.
+6. **Status indicator** on the card: idle / fetching (spinner) / error (red dot + tooltip) / last-success timestamp.
+
+## Out of scope (deferred to v2)
+
+- Periodic scheduler (5/10/15/30/60 min).
+- Page-refresh trigger from the browser.
+- Full settings modal with extended options.
+- Notifications when `origin/<tracking>` has moved ahead.
+- Discovery of repos that have no existing sessions — a project shows up only after the first session in it.
+
+## Never in scope
+
+- `git pull`, `merge`, `rebase` — fetch only. Working tree is never touched.
+- `push` to the remote.
+- Branch management.
+- Authentication — private repos via SSH agent already work; we don't add new credential flows.
+
+## Decisions
+
+| # | Decision | Why |
+|---|----------|-----|
+| D1 | `git fetch --all --prune` | Safe — doesn't touch the working tree. User decides when to merge. |
+| D2 | Persistence: backend file `~/.codedash/refresh-settings.json` only (atomic write). Frontend reads via API on every load. | Single source of truth, no sync logic. Cost: one extra API call on page load. |
+| D3 | New-chat trigger: wait for fetch up to 2 s (with UI indicator), then open the session | Half of the value is the LLM seeing fresh refs in its first turn. 2 s balances "fresh" vs "responsive". |
+| D4 | Subtle inline spinner instead of modal-style warning banner | Fetch can't diverge the working copy (see R3). A banner would frighten the user without cause. |
+| D5 | Max concurrency = 4 parallel fetches | Doesn't hammer the system, doesn't block the event loop. |
+| D6 | Single-flight per gitRoot | A second trigger while a fetch is running returns the existing promise. Simple semantics. |
+| D7 | Per-fetch timeout = 60 s | Covers slow remotes/networks. Kill subprocess on timeout → state=error. |
+| D8 | Frontend polling = 2 s, only while at least one visible repo is `fetching` | Zero-dep, acceptable latency. Otherwise 0 requests. |
+| D9 | `atomicWriteJson(path, obj)` shared helper. Used for new settings **and** retrofitted into existing disk caches (`codedash-gitroot-cache-v2.json` and other `_save*DiskCache` callers) | Closes the deferred MEDIUM from PR #212. Adds ~15 LoC to scope, saves a separate PR. |
+
+## Architecture
+
+### Backend
+
+#### New module `src/repo-refresh.js`
+
+```
+RepoRefreshManager (singleton)
+  state: Map<gitRoot, RepoState>
+  settings: RefreshSettings
+  inflight: Map<gitRoot, Promise<RepoState>>
+  semaphore: { running, queue, max: 4 }
+
+  triggerRefresh(gitRoot): Promise<RepoState>
+  triggerAllEnabled(): Promise<void>
+  waitForRefreshOrTimeout(gitRoot, timeoutMs): Promise<RepoState>
+  getState(): { repos, settings }
+  updateSettings(partial): RefreshSettings
+  loadSettings(): void
+  initOnStartup(): void
+```
+
+#### Per-repo state machine
+
+```
+       ┌───────────┐
+       │   idle    │ (lastSuccessAt: null | epoch)
+       └─────┬─────┘
+             │ trigger()
+             ▼
+       ┌───────────┐
+       │ fetching  │ (startedAt: epoch; single-flight)
+       └─┬───────┬─┘
+  ok     │       │   error / timeout
+         ▼       ▼
+       ┌───────┐ ┌────────┐
+       │ idle  │ │ error  │ (lastError, lastErrorAt)
+       └───────┘ └────────┘
+```
+
+#### Concurrency
+
+- `child_process.execFile` (async) with `timeout: 60_000`.
+- Semaphore: max 4 in flight. The 5th call queues.
+- Single-flight: if `inflight.has(gitRoot)`, return the existing promise.
+- The main thread is never blocked — fetches run in a child process via libuv.
+
+#### Shared helper in `src/atomic.js` (new)
+
+```
+atomicWriteJson(filePath, obj): void
+  // Write to <path>.tmp, fsync, rename to <path>. Throws on failure.
+```
+
+Used by `_saveGitRootDiskCache`, any other `_save*DiskCache` callers, and the new `RepoRefreshManager.saveSettings`.
+
+### Frontend (`src/frontend/app.js` + `styles.css`)
+
+- On each project card:
+  - Inline spinner badge when `status === 'fetching'`.
+  - Red dot + tooltip when `status === 'error'`.
+  - Subtle check-mark + relative time when `lastSuccessAt` is set.
+  - "↻ Refresh" button (visible on hover, focusable).
+  - Per-project toggle "Auto-refresh on new chat".
+- In the Projects view header: global toggle "Refresh on startup".
+- Polling: `setInterval(2000)` while any visible repo is `fetching`. Cleared otherwise.
+- New-chat click handler:
+  ```
+  if (project.autoRefresh) {
+    showInlineSpinner(project)
+    await fetch('/api/repo-refresh/trigger', { gitRoot })
+    await waitForIdleOrTimeout(gitRoot, 2000)
+    hideInlineSpinner(project)
+  }
+  openSession(...)
+  ```
+
+### Persistence
+
+`~/.codedash/refresh-settings.json`:
+
+```json
+{
+  "version": 1,
+  "refreshOnStartup": false,
+  "perProject": {
+    "/Users/pavelnovak/code/codbash": { "autoRefreshOnNewChat": true },
+    "/Users/pavelnovak/code/Flow-Universe": { "autoRefreshOnNewChat": false }
+  }
+}
+```
+
+- Corrupt JSON → warning log, defaults (everything off).
+- Writes go through `atomicWriteJson` (tmp + fsync + rename).
+- Debounced 500 ms — settings change frequently when the user clicks toggles.
+
+## API contract
+
+### GET /api/repo-refresh/state
+
+```typescript
+interface RepoState {
+  status: 'idle' | 'fetching' | 'error';
+  startedAt: number | null;        // epoch ms
+  lastSuccessAt: number | null;
+  lastError: string | null;        // truncated message
+  lastErrorAt: number | null;
+}
+
+interface StateResponse {
+  repos: Record<string /* gitRoot */, RepoState>;
+  settings: RefreshSettings;
+}
+```
+
+### POST /api/repo-refresh/trigger
+
+```typescript
+// request
+{ gitRoot: string }
+
+// response (immediate)
+{ status: 'fetching' | 'idle' | 'error', state: RepoState }
+```
+
+Unknown `gitRoot` → 404. Already `fetching` → returns the current state without starting a second process.
+
+### POST /api/repo-refresh/wait
+
+```typescript
+// request
+{ gitRoot: string, timeoutMs?: number /* default 2000 */ }
+
+// response (returns when fetch finishes or timeout)
+{ state: RepoState, timedOut: boolean }
+```
+
+Long-poll style. Convenient for the new-chat handler on the frontend.
+
+### GET /api/repo-refresh/settings, POST /api/repo-refresh/settings
+
+```typescript
+interface RefreshSettings {
+  refreshOnStartup: boolean;
+  perProject: Record<string /* gitRoot */, { autoRefreshOnNewChat: boolean }>;
+}
+```
+
+POST accepts a partial, merges, validates (every gitRoot must resolve via `resolveGitRoot`), saves.
+
+### Error format
+
+```typescript
+{ error: string, code?: 'not_found' | 'invalid_payload' | 'git_unavailable' }
+```
+
+## Component map
+
+| File | Change |
+|------|--------|
+| `src/repo-refresh.js` | **new** — manager + fetch worker + settings I/O |
+| `src/atomic.js` | **new** — `atomicWriteJson` helper |
+| `src/data.js` | replace direct `writeFileSync` in `_saveGitRootDiskCache` (and any other `_save*DiskCache`) with `atomicWriteJson` |
+| `src/server.js` | +4 routes under `/api/repo-refresh/*` |
+| `bin/cli.js` | call `RepoRefreshManager.initOnStartup()` after the server boots |
+| `src/frontend/app.js` | UI: toggle, spinner, refresh button, polling, new-chat hook |
+| `src/frontend/styles.css` | status styles |
+| `docs/ARCHITECTURE.md` | new section "Repo Auto-Refresh" |
+
+## Touchpoints with existing code
+
+- `resolveGitRoot(projectPath)` (from PR #212) → Map key.
+- `getProjectGitInfo` → remote URL for the UI.
+- New-chat button — wrap `POST /api/launch` in a helper `maybeRefreshBeforeLaunch(gitRoot)`.
+
+## Risks
+
+| # | Risk | Mitigation |
+|---|------|------------|
+| R1 | Slow fetch (slow remote, large repo) | 60 s timeout, max-concurrency 4, fire-and-forget in UI with a 2 s wait for new-chat |
+| R2 | SSH agent not running | state=error, badge with tooltip, user sees what's wrong |
+| R3 | Divergence during active fetch + concurrent user work | `fetch` doesn't touch the working tree → impossible. Divergence only happens on a subsequent `merge`/`rebase` — that's the user's responsibility. |
+| R4 | Memory leak in `inflight` Map | `try/finally` always clears the entry |
+| R5 | `atomicWriteJson` breaks existing cache files during retrofit | Tests on rename semantics + smoke test that the cache is readable after write/restart |
+| R6 | 2 s wait on new-chat feels slow | Spinner + "Updating…" text gives visible feedback. If fetch completes in <100 ms, the session opens immediately. |
+
+## UX & Accessibility
+
+**Target WCAG level**: AA.
+
+**Affected surfaces**:
+1. Projects view — project card with status indicator, refresh button, per-project toggle.
+2. Projects view header — global "Refresh on startup" toggle.
+
+### Required UI states (per project card)
+
+- [x] **Loading** — until the first `GET /state` returns: toggle disabled+dim, refresh button hidden.
+- [x] **Empty** — N/A (a card appears only when a git root + sessions exist).
+- [x] **Error** — `status === 'error'`. Red dot badge, tooltip `Last fetch failed: <error>`. "Retry" button (= same `/trigger` endpoint).
+- [x] **Success/Confirmation** — `lastSuccessAt` set, `status === 'idle'`. Subtle check-mark with relative time `Updated 2 min ago`. No toast — we don't distract.
+- [x] **Disabled** — toggle off. No status badges, clean card.
+- [x] **Partial/Stale** — N/A in v1 (no scheduler → no "expected interval" concept).
+- [x] **Optimistic/Pending** — clicking a toggle flips the visual immediately; rollback if POST fails + toast "Failed to save setting".
+
+### Inline spinner while fetching
+
+- `role="status"` + `aria-live="polite"` — screen reader announces `Fetching <project name>` → `Updated`.
+- Visible spinner + "Updating…" text near the name.
+- Doesn't block card clicks; the session can still be opened.
+
+### Keyboard
+
+- Per-project toggle: Tab → focus → Space toggles. `aria-checked`.
+- Refresh button: Tab → focus → Enter triggers. `aria-label="Refresh <project name>"`.
+- Visible focus ring on every control (never strip `outline:none` without a replacement).
+- Header global toggle — same behavior.
+
+### Screen reader
+
+- Toggle: `<input type="checkbox">` paired with a `<label>` reading `Auto-refresh on new chat for <project>`.
+- Status badge: `role="status"`, `aria-live="polite"`. Announces transitions `idle → fetching → idle/error`.
+- Error tooltip: `aria-describedby` from the badge icon.
+
+### Touch targets
+
+- Toggle and refresh button: hit area at least 44×44 even when the visual is smaller.
+
+### Responsive
+
+- Mobile (<640 px): refresh button always visible (no hover state), status badge more compact.
+- Toggle moves below the project name.
+
+### Performance budget
+
+- `POST /trigger` responds in <100 ms (enqueue only).
+- `GET /state` <50 ms (in-memory read).
+- `POST /wait` responds when the fetch finishes or after `timeoutMs` — the client knows what to expect.
+- Polling overhead: 1 req/2 s while a visible fetch is running, otherwise 0.
+
+## Acceptance criteria
+
+- [ ] Per-project toggle survives browser sessions and service restarts.
+- [ ] When the service starts with `refreshOnStartup: true`, every enabled repo begins fetching within 1 s.
+- [ ] Clicking the "Refresh" button starts a fetch; status flips to `fetching`.
+- [ ] Clicking "new chat" on a project with the toggle on: spinner shows → fetch (or 2 s timeout) → session opens.
+- [ ] `curl /api/sessions` during an active fetch responds in <100 ms (event loop is not blocked).
+- [ ] Max 4 parallel fetches.
+- [ ] Fetch timeout 60 s; on timeout the subprocess is killed and state=error.
+- [ ] Corrupt settings file → start with defaults + warning log.
+- [ ] Settings are written atomically via `atomicWriteJson` (tmp + rename).
+- [ ] Existing cache files are migrated to `atomicWriteJson`.
+- [ ] Every UI state in the checklist is implemented.
+- [ ] Keyboard navigation works for every control.
+- [ ] Screen reader correctly announces state transitions.
diff --git a/specs/repo-auto-refresh.feature b/specs/repo-auto-refresh.feature
new file mode 100644
index 0000000..ed8cff7
--- /dev/null
+++ b/specs/repo-auto-refresh.feature
@@ -0,0 +1,216 @@
+Feature: Repo Auto-Refresh
+  As a codbash user with many connected repositories
+  I want background `git fetch` for selected repos before I start working
+  So that my AI sessions see current `origin/<branch>` and I don't drift into divergence
+
+  Background:
+    Given codbash is running with at least one connected project at "/repos/myproj"
+    And "/repos/myproj" has a working `origin` remote
+    And the refresh-settings file is fresh (defaults: refreshOnStartup=false, no per-project entries)
+
+  # ─────────────────────────────────────────────────────────────────────
+  # 1. HAPPY PATH
+  # ─────────────────────────────────────────────────────────────────────
+
+  Scenario: User clicks the Refresh button on a project card
+    Given the project card for "/repos/myproj" is rendered with status "idle"
+    When the user clicks the "↻ Refresh" button on that card
+    Then the backend receives POST /api/repo-refresh/trigger with gitRoot="/repos/myproj"
+    And the response returns immediately with status="fetching"
+    And the card shows the inline spinner with text "Updating…"
+    And `git fetch --all --prune` is launched as a child process for "/repos/myproj"
+    And when the fetch completes the card shows "Updated just now"
+    And subsequent GET /state returns status="idle" with lastSuccessAt set
+
+  Scenario: New-chat click on a project with auto-refresh toggle on, fetch completes within 2s
+    Given the project at "/repos/myproj" has perProject.autoRefreshOnNewChat=true
+    And the next `git fetch` will complete in ~500 ms
+    When the user clicks "New chat" on that project card
+    Then the inline spinner shows on the card
+    And POST /api/repo-refresh/trigger fires with gitRoot="/repos/myproj"
+    And the frontend calls POST /api/repo-refresh/wait with timeoutMs=2000
+    And when fetch completes (~500 ms later) /wait returns { timedOut: false }
+    And the session is launched after fetch finishes
+    And the spinner is hidden before the session window opens
+
+  Scenario: Service start with refreshOnStartup=true triggers all enabled repos
+    Given settings has refreshOnStartup=true
+    And perProject has autoRefreshOnNewChat=true for "/repos/a" and "/repos/b"
+    And perProject has autoRefreshOnNewChat=false for "/repos/c"
+    When the codbash service is started
+    Then within 1 second `git fetch` is launched for "/repos/a" and "/repos/b"
+    And `git fetch` is NOT launched for "/repos/c"
+    And the HTTP server is accepting connections during these background fetches
+
+  # ─────────────────────────────────────────────────────────────────────
+  # 2. EMPTY STATE
+  # ─────────────────────────────────────────────────────────────────────
+
+  Scenario: First-ever launch — no projects discovered yet
+    Given codbash is launched on a clean machine with no AI sessions ever recorded
+    When the user opens the Projects view
+    Then the view shows the existing empty-state explanation
+    And no repo-refresh UI is rendered (no toggles, no spinners, no refresh button)
+    And GET /api/repo-refresh/state returns { repos: {}, settings: <defaults> }
+
+  Scenario: Project exists but has no remote configured
+    Given a project at "/repos/local-only" with `.git` but no `origin` remote
+    When the user clicks the "↻ Refresh" button for it
+    Then `git fetch --all --prune` runs and exits cleanly (no remotes to fetch from)
+    And status returns to "idle"
+    And no error is shown — fetching with zero remotes is not an error
+
+  # ─────────────────────────────────────────────────────────────────────
+  # 3. LOADING STATE
+  # ─────────────────────────────────────────────────────────────────────
+
+  Scenario: First page load — frontend renders before /state responds
+    Given the user opens the dashboard for the first time this session
+    When the page is rendering and GET /api/repo-refresh/state has not yet returned
+    Then per-project toggles are disabled and dim
+    And the "↻ Refresh" button is hidden
+    And no spinner is shown (we don't know fetch state yet)
+    And once /state returns within 200 ms the controls become interactive
+
+  Scenario: Slow fetch shows persistent spinner without blocking other UI
+    Given the user clicked Refresh on "/repos/myproj"
+    And `git fetch` is taking ~10 seconds (slow remote)
+    Then the card spinner stays visible for the full duration
+    And the user can scroll, click other cards, and open unrelated sessions
+    And GET /api/sessions during this fetch responds in under 100 ms
+    And POST /api/repo-refresh/trigger for a different repo is accepted in parallel
+
+  # ─────────────────────────────────────────────────────────────────────
+  # 4. ERROR STATE
+  # ─────────────────────────────────────────────────────────────────────
+
+  Scenario: Fetch fails because SSH agent is not running
+    Given the project at "/repos/private-repo" requires SSH auth
+    And no SSH agent is available in the codbash process environment
+    When the user clicks Refresh
+    Then `git fetch` exits with a non-zero status
+    And the backend stores status="error" with lastError containing "Permission denied" (truncated to ~200 chars)
+    And the card shows a red dot badge with a tooltip showing the error
+    And the card shows a "Retry" affordance (re-triggers the same endpoint)
+    And clicking Retry transitions status back to "fetching"
+
+  Scenario: Fetch exceeds the 60-second timeout
+    Given `git fetch` for "/repos/myproj" is hanging (unreachable remote)
+    When 60 seconds elapse since the fetch started
+    Then the child process is terminated (SIGTERM, then SIGKILL after 2s grace)
+    And status becomes "error" with lastError mentioning "timeout"
+    And the inflight Map no longer contains "/repos/myproj"
+    And a subsequent trigger starts a fresh fetch (not stuck)
+
+  Scenario: Corrupt settings file on startup falls back to defaults
+    Given ~/.codedash/refresh-settings.json contains invalid JSON ("{ not json")
+    When the codbash service is started
+    Then a warning is logged ("Failed to parse refresh settings, using defaults")
+    And the service starts successfully with settings = defaults (refreshOnStartup=false, perProject={})
+    And no startup fetches are triggered
+    And the file is left untouched (we don't auto-overwrite — user may want to recover)
+
+  Scenario: Saving settings fails (disk full, permission error)
+    Given the user toggles autoRefreshOnNewChat for "/repos/myproj"
+    And the atomic write fails (e.g., EACCES on the tmp file)
+    Then POST /api/repo-refresh/settings returns 500 with { error: "...", code: "..." }
+    And the frontend shows a toast "Failed to save setting"
+    And the toggle visual reverts to its previous state (optimistic rollback)
+
+  # ─────────────────────────────────────────────────────────────────────
+  # 5. KEYBOARD-ONLY NAVIGATION
+  # ─────────────────────────────────────────────────────────────────────
+
+  Scenario: Toggling auto-refresh with keyboard only
+    Given the Projects view is open
+    When the user presses Tab repeatedly until focus lands on the auto-refresh toggle for "/repos/myproj"
+    Then the toggle has a visible focus ring
+    And the toggle announces "Auto-refresh on new chat for myproj, not checked" to screen readers
+    When the user presses Space
+    Then the toggle flips to checked
+    And aria-checked becomes "true"
+    And POST /api/repo-refresh/settings is sent with the updated value
+
+  Scenario: Triggering Refresh with keyboard only
+    Given focus is on the project card for "/repos/myproj"
+    When the user presses Tab to reach the "↻ Refresh" button
+    Then the button has aria-label="Refresh myproj" and a visible focus ring
+    When the user presses Enter
+    Then the trigger fires (same flow as a mouse click)
+    And focus stays on the button (does not jump)
+
+  Scenario: Screen reader announces state transitions
+    Given the user has focus on the project card for "/repos/myproj"
+    When a fetch transitions from idle to fetching
+    Then the status badge (role="status", aria-live="polite") announces "Fetching myproj"
+    When the fetch completes successfully
+    Then it announces "Updated"
+    When the fetch fails
+    Then it announces "Refresh failed: <error message>"
+
+  # ─────────────────────────────────────────────────────────────────────
+  # 6. EDGE DATA / CONCURRENCY
+  # ─────────────────────────────────────────────────────────────────────
+
+  Scenario: Repeated trigger while a fetch is in flight is single-flight
+    Given a fetch for "/repos/myproj" is in progress (state="fetching")
+    When the user clicks Refresh again
+    Then no new child process is spawned
+    And POST /trigger returns the existing { status: "fetching", state: <same startedAt> }
+    And the same applies to a concurrent new-chat trigger for the same repo
+
+  Scenario: Five simultaneous triggers respect the max-concurrency of 4
+    Given there are 5 enabled repos with no active fetches
+    When the service starts with refreshOnStartup=true
+    Then exactly 4 `git fetch` processes are running concurrently
+    And the 5th is queued and starts when any of the first 4 finishes
+    And the inflight Map at any moment contains at most 4 entries actively executing
+
+  Scenario: Project with a very long name renders the card without overflow
+    Given a project gitRoot with a 200-character path and a 100-character basename
+    When the card is rendered
+    Then the project name truncates with ellipsis at the card width
+    And the refresh button, status badge, and toggle remain reachable and clickable
+    And the tooltip on the truncated name shows the full path
+
+  Scenario: gitRoot path with spaces or special characters in settings file
+    Given a project at "/repos/My Project (legacy)" with auto-refresh enabled
+    When POST /api/repo-refresh/settings persists this entry
+    Then the JSON file contains the exact string "/repos/My Project (legacy)" (not URL-encoded, not escaped beyond JSON rules)
+    And on next service start the entry round-trips correctly
+    And `git fetch -C "/repos/My Project (legacy)" --all --prune` is invoked as a single argv element (no shell-splitting)
+
+  Scenario: New-chat trigger times out at 2s, session opens with stale refs
+    Given the project at "/repos/myproj" has autoRefreshOnNewChat=true
+    And the next `git fetch` will take ~5 seconds (slow remote)
+    When the user clicks "New chat"
+    Then the spinner shows for 2 seconds
+    And POST /wait returns { timedOut: true } at 2s
+    And the session opens with whatever refs are currently on disk
+    And the fetch continues in the background — when it finishes the card updates to "Updated just now"
+
+  Scenario: Bare repo skipped without error
+    Given a project gitRoot resolved earlier that happens to be a bare repo "/repos/origin.git"
+    When refresh is triggered for it
+    # Note: resolveGitRoot already returns "" for bare repos (PR #212) — so the gitRoot
+    # never appears in the projects list. This scenario is here to lock that invariant.
+    Then no /trigger request is ever sent for "/repos/origin.git" from a normal UI flow
+
+  # ─────────────────────────────────────────────────────────────────────
+  # CROSS-CUTTING — ATOMIC SETTINGS WRITE (D9 retrofit)
+  # ─────────────────────────────────────────────────────────────────────
+
+  Scenario: Settings write is atomic — crash mid-write leaves the file consistent
+    Given the user is rapidly toggling auto-refresh on multiple projects
+    And the process is killed (SIGKILL) during a debounced settings save
+    When the service starts again
+    Then refresh-settings.json is either fully the previous version or fully the new version
+    And it never contains partial JSON
+    And ~/.codedash/refresh-settings.json.tmp is cleaned up or ignored
+
+  Scenario: Existing git-root cache file uses the same atomic write helper
+    Given a fresh service start with no cache file
+    When `resolveGitRoot` populates and saves the on-disk cache
+    Then the write goes through atomicWriteJson (tmp + rename)
+    And the file is valid JSON after every persisted write
+    And the prior bug (truncated file on crash) cannot occur
diff --git a/src/atomic.js b/src/atomic.js
new file mode 100644
index 0000000..417ce97
--- /dev/null
+++ b/src/atomic.js
@@ -0,0 +1,36 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function atomicWriteJson(filePath, obj, opts) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const tmp = filePath + '.tmp';
+  const data = JSON.stringify(obj);
+  if (data === undefined) {
+    throw new TypeError('atomicWriteJson: value is not JSON-serializable');
+  }
+  // Default 0o644 preserves the existing cache-file behaviour. Settings files
+  // that may contain a user's project map pass { mode: 0o600 } so other users
+  // on a shared machine can't read the toggle state.
+  const mode = (opts && typeof opts.mode === 'number') ? opts.mode : 0o644;
+
+  const fd = fs.openSync(tmp, 'w', mode);
+  try {
+    fs.writeSync(fd, data);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  try {
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+module.exports = { atomicWriteJson };
diff --git a/src/data.js b/src/data.js
index 4c42f6c..51681c7 100644
--- a/src/data.js
+++ b/src/data.js
@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { execSync, execFileSync } = require('child_process');
+const { atomicWriteJson } = require('./atomic');
 
 // ── Constants ──────────────────────────────────────────────
 
@@ -326,7 +327,7 @@ function _loadParsedDiskCache() {
 function _saveParsedDiskCache() {
   if (!_parsedDiskCacheDirty || !_parsedDiskCache) return;
   try {
-    fs.writeFileSync(PARSED_CACHE_FILE, JSON.stringify(_parsedDiskCache));
+    atomicWriteJson(PARSED_CACHE_FILE, _parsedDiskCache);
     _parsedDiskCacheDirty = false;
   } catch {}
 }
@@ -2401,7 +2402,7 @@ function _loadGitRootDiskCache() {
 
 function _saveGitRootDiskCache() {
   try {
-    fs.writeFileSync(GIT_ROOT_CACHE_FILE, JSON.stringify(_gitRootCache));
+    atomicWriteJson(GIT_ROOT_CACHE_FILE, _gitRootCache);
   } catch {}
 }
 
@@ -4275,7 +4276,7 @@ function _loadCostDiskCache() {
 function _saveCostDiskCache() {
   if (!_costDiskCache) return;
   try {
-    fs.writeFileSync(COST_CACHE_FILE, JSON.stringify(_costDiskCache));
+    atomicWriteJson(COST_CACHE_FILE, _costDiskCache);
   } catch {}
 }
 
@@ -5136,7 +5137,7 @@ function _loadDailyStatsDiskCache() {
 function _saveDailyStatsDiskCache() {
   if (!_dailyStatsDiskCache) return;
   try {
-    fs.writeFileSync(DAILY_STATS_CACHE_FILE, JSON.stringify(_dailyStatsDiskCache));
+    atomicWriteJson(DAILY_STATS_CACHE_FILE, _dailyStatsDiskCache);
   } catch {}
 }
 
diff --git a/src/frontend/app.js b/src/frontend/app.js
index 850c2f9..2a6fe68 100644
--- a/src/frontend/app.js
+++ b/src/frontend/app.js
@@ -49,6 +49,352 @@ let sessionTitles = JSON.parse(localStorage.getItem('codedash-titles') || '{}');
 let showAITitles = localStorage.getItem('codedash-ai-titles') !== 'false';
 let showAllSessionsListBadges = localStorage.getItem('codedash-all-sessions-list-badges') !== 'false';
 
+// ── Repo Auto-Refresh state ────────────────────────────────────
+
+let repoRefreshState = {
+  repos: {},
+  settings: { version: 1, refreshOnStartup: false, perProject: {} },
+};
+let repoRefreshLoaded = false;
+let repoRefreshPollTimer = null;
+let repoRefreshTimeTimer = null;          // re-renders relative timestamps every 30s
+const REPO_REFRESH_POLL_MS = 2000;
+const REPO_REFRESH_TIME_TICK_MS = 30000;
+const _recentToasts = {};                 // de-dupe toast spam: msg → ts
+
+function repoRefreshToast(msg) {
+  const now = Date.now();
+  if (_recentToasts[msg] && (now - _recentToasts[msg]) < 3000) return;
+  _recentToasts[msg] = now;
+  // Evict the dedup key after the window so long sessions don't accumulate
+  // every distinct error message ever seen.
+  setTimeout(function() { delete _recentToasts[msg]; }, 3100);
+  showToast(msg);
+}
+
+// Shallow-immutable updaters — per ~/.claude/rules/common/coding-style.md
+// (Immutability CRITICAL) we never mutate the state object in place.
+function setRepoState(gitRoot, partial) {
+  const prev = repoRefreshState.repos[gitRoot] || null;
+  repoRefreshState = {
+    ...repoRefreshState,
+    repos: { ...repoRefreshState.repos, [gitRoot]: prev ? { ...prev, ...partial } : { ...partial } },
+  };
+}
+function setPerProjectSetting(gitRoot, value) {
+  // Spread the previous per-project config so future fields (e.g. lastUserAcked)
+  // survive an optimistic toggle of a single field.
+  const prev = repoRefreshState.settings.perProject[gitRoot] || {};
+  repoRefreshState = {
+    ...repoRefreshState,
+    settings: {
+      ...repoRefreshState.settings,
+      perProject: { ...repoRefreshState.settings.perProject, [gitRoot]: { ...prev, ...value } },
+    },
+  };
+}
+function setGlobalRefreshOnStartup(value) {
+  repoRefreshState = {
+    ...repoRefreshState,
+    settings: { ...repoRefreshState.settings, refreshOnStartup: !!value },
+  };
+}
+
+async function loadRepoRefreshState() {
+  try {
+    const res = await fetch('/api/repo-refresh/state');
+    if (!res.ok) return;
+    const data = await res.json();
+    repoRefreshState = data;
+    repoRefreshLoaded = true;
+    refreshRepoRefreshUI();
+  } catch (e) {
+    // Network errors during polling are silent — would otherwise spam the console.
+  }
+}
+
+function refreshRepoRefreshUI() {
+  document.querySelectorAll('[data-rr-badge]').forEach(function(el) {
+    // Skip the innerHTML swap if focus is inside this slot — replacing the
+    // DOM would steal keyboard focus and silently send the user to <body>.
+    // The next un-focused tick will pick it up.
+    if (el.contains(document.activeElement)) return;
+    const root = el.getAttribute('data-rr-badge');
+    el.innerHTML = renderRepoRefreshBadgeInner(root);
+  });
+  document.querySelectorAll('[data-rr-toggle]').forEach(function(el) {
+    const root = el.getAttribute('data-rr-toggle');
+    const enabled = !!(repoRefreshState.settings.perProject[root] && repoRefreshState.settings.perProject[root].autoRefreshOnNewChat);
+    el.checked = enabled;
+    el.setAttribute('aria-checked', enabled ? 'true' : 'false');
+    if (!repoRefreshLoaded) el.disabled = true;
+    else if (!el.dataset.rrInflight) el.disabled = false;
+  });
+  const globalToggle = document.getElementById('repoRefreshGlobalToggle');
+  if (globalToggle) {
+    const v = !!repoRefreshState.settings.refreshOnStartup;
+    globalToggle.checked = v;
+    globalToggle.setAttribute('aria-checked', v ? 'true' : 'false');
+    if (!repoRefreshLoaded) globalToggle.disabled = true;
+    else if (!globalToggle.dataset.rrInflight) globalToggle.disabled = false;
+  }
+  startRepoRefreshPollingIfNeeded();
+  startRepoRefreshTimeTickerIfNeeded();
+}
+
+function startRepoRefreshPollingIfNeeded() {
+  const anyFetching = Object.values(repoRefreshState.repos).some(function(r) { return r && r.status === 'fetching'; });
+  if (!anyFetching || currentView !== 'projects') {
+    if (repoRefreshPollTimer) { clearInterval(repoRefreshPollTimer); repoRefreshPollTimer = null; }
+    return;
+  }
+  if (repoRefreshPollTimer) return;
+  repoRefreshPollTimer = setInterval(loadRepoRefreshState, REPO_REFRESH_POLL_MS);
+}
+
+// Re-render badges every 30s so "Updated 2 min ago" doesn't get stuck.
+function startRepoRefreshTimeTickerIfNeeded() {
+  const anyOk = Object.values(repoRefreshState.repos).some(function(r) { return r && r.lastSuccessAt; });
+  if (!anyOk || currentView !== 'projects') {
+    if (repoRefreshTimeTimer) { clearInterval(repoRefreshTimeTimer); repoRefreshTimeTimer = null; }
+    return;
+  }
+  if (repoRefreshTimeTimer) return;
+  repoRefreshTimeTimer = setInterval(function() {
+    document.querySelectorAll('[data-rr-badge]').forEach(function(el) {
+      if (el.contains(document.activeElement)) return; // same focus guard as above
+      const root = el.getAttribute('data-rr-badge');
+      el.innerHTML = renderRepoRefreshBadgeInner(root);
+    });
+  }, REPO_REFRESH_TIME_TICK_MS);
+}
+
+function repoRelativeTime(ts) {
+  if (!ts) return '';
+  const secs = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+  if (secs < 5) return 'just now';
+  if (secs < 60) return secs + 's ago';
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return mins + ' min ago';
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return hours + 'h ago';
+  return Math.floor(hours / 24) + 'd ago';
+}
+
+function _fmtTime(ts) {
+  if (!ts) return '';
+  try { return new Date(ts).toLocaleString(undefined, { dateStyle: 'medium', timeStyle: 'short' }); }
+  catch { return new Date(ts).toString(); }
+}
+
+// Renders the badge inner HTML. The outer <span data-rr-badge> wrapper carries
+// role="status" + aria-live="polite" so transitions are announced without
+// destroying the live region on innerHTML replacement.
+function renderRepoRefreshBadgeInner(gitRoot) {
+  const st = repoRefreshState.repos[gitRoot];
+  if (!st) return '';
+  if (st.status === 'fetching') {
+    return '<span class="repo-refresh-badge fetching" title="Running git fetch for origin">'
+      + '<span class="repo-refresh-spinner" aria-hidden="true"></span>'
+      + '<span class="repo-refresh-badge-text">Fetching…</span></span>';
+  }
+  if (st.status === 'error') {
+    const err = st.lastError || 'fetch failed';
+    const at = st.lastErrorAt ? ' (at ' + _fmtTime(st.lastErrorAt) + ')' : '';
+    // Trim at the nearest word boundary so visible truncation doesn't slice
+    // mid-word. Reserve "…" for truncation; ASCII ellipsis is fine here.
+    let visible = err.slice(0, 60);
+    if (err.length > 60) {
+      const cut = visible.replace(/\s\S*$/, '');
+      visible = (cut.length > 20 ? cut : visible) + '…';
+    }
+    // aria-describedby points at a visually-hidden full message so SR and
+    // keyboard users get the complete error, not just the title tooltip.
+    const descId = 'rr-err-desc-' + Math.random().toString(36).slice(2, 9);
+    return '<span class="repo-refresh-badge error" tabindex="0" '
+      + 'aria-describedby="' + descId + '" title="' + escHtml(err + at) + '">'
+      + '<span class="repo-refresh-dot" aria-hidden="true"></span>'
+      + '<span class="repo-refresh-badge-text">Refresh failed: ' + escHtml(visible) + '</span>'
+      + '<span id="' + descId + '" class="visually-hidden">' + escHtml(err + at) + '</span></span>';
+  }
+  if (st.lastSuccessAt) {
+    return '<span class="repo-refresh-badge ok" title="Last fetched ' + escHtml(_fmtTime(st.lastSuccessAt)) + '">'
+      + '<span aria-hidden="true">✓</span>'
+      + '<span class="repo-refresh-badge-text">Updated ' + escHtml(repoRelativeTime(st.lastSuccessAt)) + '</span></span>';
+  }
+  return '';
+}
+
+function renderRepoRefreshControls(gitRoot, projName) {
+  if (!gitRoot || gitRoot === 'unknown') {
+    // Surface the reason controls are missing so users aren't confused.
+    return '<span class="repo-refresh-controls disabled" onclick="event.stopPropagation()" title="Not a git repository — no remote to fetch from">'
+      + '<span class="repo-refresh-toggle-label">Not a git repo</span></span>';
+  }
+  const escRoot = escHtml(gitRoot);
+  const escName = escHtml(projName);
+  const enabled = !!(repoRefreshState.settings.perProject[gitRoot] && repoRefreshState.settings.perProject[gitRoot].autoRefreshOnNewChat);
+  // Group the controls so SR users hear them as one cluster, scoped to the project.
+  // stopPropagation: this span is nested under .git-project-header whose onclick
+  // toggles "collapsed". Clicks on refresh/toggle must NOT bubble there.
+  let html = '<span class="repo-refresh-controls" role="group" aria-label="Auto-refresh controls for ' + escName + '" onclick="event.stopPropagation()">';
+  // Outer wrapper carries the live region so badge innerHTML replacements
+  // don't tear down the announcer on each update.
+  html += '<span data-rr-badge="' + escRoot + '" role="status" aria-live="polite" class="repo-refresh-badge-slot">'
+    + renderRepoRefreshBadgeInner(gitRoot) + '</span>';
+  const isFetching = !!(repoRefreshState.repos[gitRoot] && repoRefreshState.repos[gitRoot].status === 'fetching');
+  html += '<button type="button" class="repo-refresh-btn" data-rr-root="' + escRoot + '" '
+    + 'aria-label="Fetch ' + escName + ' from origin" title="git fetch ' + escName + '" '
+    + (isFetching ? 'aria-busy="true" ' : '')
+    + 'onclick="onClickRepoRefresh(this.dataset.rrRoot)"><span aria-hidden="true">↻</span></button>';
+  // Native checkbox (no role="switch") keeps reliable aria-checked semantics
+  // across screen readers — see ARIA APG `switch` caveats.
+  html += '<label class="repo-refresh-toggle" title="Run git fetch automatically before opening a new chat in this project">';
+  html += '<input type="checkbox" data-rr-toggle="' + escRoot + '" '
+    + 'aria-checked="' + (enabled ? 'true' : 'false') + '" '
+    + (enabled ? 'checked ' : '') + (repoRefreshLoaded ? '' : 'disabled ')
+    + 'aria-label="Auto-fetch on new chat for ' + escName + '" '
+    + 'onchange="onToggleRepoRefreshProject(this.dataset.rrToggle, this.checked)">';
+  html += '<span class="repo-refresh-toggle-label">Auto-fetch</span></label>';
+  html += '</span>';
+  return html;
+}
+
+function renderRepoRefreshGlobalToggle() {
+  return '<label class="repo-refresh-global-toggle" title="When codbash starts, run git fetch for every repo whose Auto-fetch toggle is on">'
+    + '<input type="checkbox" id="repoRefreshGlobalToggle" '
+    + 'aria-checked="' + (repoRefreshState.settings.refreshOnStartup ? 'true' : 'false') + '" '
+    + (repoRefreshState.settings.refreshOnStartup ? 'checked ' : '')
+    + (repoRefreshLoaded ? '' : 'disabled ')
+    + 'aria-label="Fetch all enabled repos on codbash start" '
+    + 'onchange="onToggleRepoRefreshGlobal(this.checked)">'
+    + '<span>Fetch all on codbash start</span></label>';
+}
+
+async function onClickRepoRefresh(gitRoot) {
+  if (!gitRoot) return;
+  try {
+    const res = await fetch('/api/repo-refresh/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ gitRoot: gitRoot }),
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      repoRefreshToast('Refresh failed: ' + (data && data.error || res.status));
+      return;
+    }
+    setRepoState(gitRoot, data.state || { status: 'fetching', startedAt: Date.now() });
+    refreshRepoRefreshUI();
+    setTimeout(loadRepoRefreshState, 500);
+  } catch (e) {
+    repoRefreshToast('Refresh failed: ' + e.message);
+  }
+}
+
+async function onToggleRepoRefreshProject(gitRoot, checked) {
+  if (!gitRoot) return;
+  const inputEl = document.querySelector('[data-rr-toggle="' + (window.CSS && CSS.escape ? CSS.escape(gitRoot) : gitRoot) + '"]');
+  // Disable input for the duration of the POST so a rapid second click can't
+  // race the rollback (plan risk I5).
+  if (inputEl) { inputEl.disabled = true; inputEl.dataset.rrInflight = '1'; }
+  const prev = !!(repoRefreshState.settings.perProject[gitRoot] && repoRefreshState.settings.perProject[gitRoot].autoRefreshOnNewChat);
+  setPerProjectSetting(gitRoot, { autoRefreshOnNewChat: !!checked });
+  refreshRepoRefreshUI();
+  try {
+    const body = { perProject: {} };
+    body.perProject[gitRoot] = { autoRefreshOnNewChat: !!checked };
+    const res = await fetch('/api/repo-refresh/settings', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error((await res.json()).error || 'save failed');
+  } catch (e) {
+    setPerProjectSetting(gitRoot, { autoRefreshOnNewChat: prev });
+    refreshRepoRefreshUI();
+    repoRefreshToast('Failed to save Auto-fetch setting');
+  } finally {
+    if (inputEl) { delete inputEl.dataset.rrInflight; inputEl.disabled = !repoRefreshLoaded; }
+  }
+}
+
+async function onToggleRepoRefreshGlobal(checked) {
+  const inputEl = document.getElementById('repoRefreshGlobalToggle');
+  if (inputEl) { inputEl.disabled = true; inputEl.dataset.rrInflight = '1'; }
+  const prev = !!repoRefreshState.settings.refreshOnStartup;
+  setGlobalRefreshOnStartup(!!checked);
+  refreshRepoRefreshUI();
+  try {
+    const res = await fetch('/api/repo-refresh/settings', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshOnStartup: !!checked }),
+    });
+    if (!res.ok) throw new Error((await res.json()).error || 'save failed');
+  } catch (e) {
+    setGlobalRefreshOnStartup(prev);
+    refreshRepoRefreshUI();
+    repoRefreshToast('Failed to save startup setting');
+  } finally {
+    if (inputEl) { delete inputEl.dataset.rrInflight; inputEl.disabled = !repoRefreshLoaded; }
+  }
+}
+
+async function maybeRefreshBeforeLaunch(projectPath, launchBtn) {
+  if (!projectPath) return;
+  const cfg = repoRefreshState.settings.perProject[projectPath];
+  if (!cfg || !cfg.autoRefreshOnNewChat) return;
+  // Visible feedback on the actual button — silent 2s wait is a UX foot-gun.
+  // Re-entrancy guard: a second click while we're mid-fetch would capture our
+  // own "Fetching…" markup as the "previous" text and the button would end up
+  // permanently stuck. dataset.rrLaunchInflight short-circuits the duplicate.
+  let restoreBtn = null;
+  if (launchBtn) {
+    if (launchBtn.dataset.rrLaunchInflight) return;
+    launchBtn.dataset.rrLaunchInflight = '1';
+    const prevDisabled = launchBtn.disabled;
+    const prevText = launchBtn.innerHTML;
+    launchBtn.disabled = true;
+    launchBtn.setAttribute('aria-busy', 'true');
+    launchBtn.innerHTML = '<span class="repo-refresh-spinner" aria-hidden="true"></span>&nbsp;Fetching…';
+    restoreBtn = function() {
+      launchBtn.disabled = prevDisabled;
+      launchBtn.removeAttribute('aria-busy');
+      launchBtn.innerHTML = prevText;
+      delete launchBtn.dataset.rrLaunchInflight;
+    };
+  }
+  try {
+    await fetch('/api/repo-refresh/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ gitRoot: projectPath }),
+    });
+    setRepoState(projectPath, { status: 'fetching', startedAt: Date.now() });
+    refreshRepoRefreshUI();
+    const waitRes = await fetch('/api/repo-refresh/wait', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ gitRoot: projectPath, timeoutMs: 2000 }),
+    });
+    if (waitRes.ok) {
+      const data = await waitRes.json();
+      if (data && data.state) {
+        setRepoState(projectPath, data.state);
+        refreshRepoRefreshUI();
+        if (data.state.status === 'error') {
+          repoRefreshToast('Fetch failed (session opens anyway): ' + (data.state.lastError || 'unknown'));
+        }
+      }
+    }
+  } catch (e) {
+    repoRefreshToast('Pre-launch fetch failed: ' + e.message);
+  } finally {
+    if (restoreBtn) restoreBtn();
+  }
+}
+
 // ── Color palette for projects ─────────────────────────────────
 
 const PROJECT_COLORS = [
@@ -1622,9 +1968,11 @@ function renderProjectsHistory(container, sessions) {
       '<button class="toolbar-btn" onclick="clearHistoryProjectFilter()" aria-label="Clear project filter">&times; Clear filter</button>' +
       '</div>';
   }
-  html += '<div style="display:flex;gap:8px;margin-bottom:12px;align-items:center">';
+  html += '<div style="display:flex;gap:8px;margin-bottom:12px;align-items:center;flex-wrap:wrap">';
+  html += '<button class="toolbar-btn" onclick="openAddProject()" title="Register a local folder or clone from GitHub" style="background:#3b82f6;color:#fff;border-color:#3b82f6">+ Add Project</button>';
   html += '<button class="toolbar-btn" onclick="document.querySelectorAll(\'.git-project-group\').forEach(function(g){g.classList.add(\'collapsed\')})">Collapse All</button>';
   html += '<button class="toolbar-btn" onclick="document.querySelectorAll(\'.git-project-group\').forEach(function(g){g.classList.remove(\'collapsed\')})">Expand All</button>';
+  if (sorted.length > 0) html += renderRepoRefreshGlobalToggle();
   html += '</div>';
 
   if (sorted.length === 0) {
@@ -1668,11 +2016,11 @@ function renderProjectsHistory(container, sessions) {
       // Prefer the tool the user actually worked with in this project; default
       // to claude for brand-new entries with no sessions yet.
       var preferredTool = lastSession && lastSession.tool ? lastSession.tool : 'claude';
-      html += '<button class="git-project-launch-btn primary" data-proj-path="' + escHtml(projPath) + '" data-tool="' + escHtml(preferredTool) + '" onclick="event.stopPropagation();launchNewProjectSession(this.dataset.projPath, this.dataset.tool)" title="Start a new ' + escHtml(preferredTool) + ' session in this folder">&#9654; New</button>';
+      html += '<button class="git-project-launch-btn primary" data-proj-path="' + escHtml(projPath) + '" data-tool="' + escHtml(preferredTool) + '" onclick="event.stopPropagation();launchNewProjectSession(this.dataset.projPath, this.dataset.tool, this)" title="Start a new ' + escHtml(preferredTool) + ' session in this folder">&#9654; New</button>';
       if (lastSession) {
         var lastId = lastSession.id || '';
         var lastTool = lastSession.tool || 'claude';
-        html += '<button class="git-project-launch-btn" data-sess-id="' + escHtml(lastId) + '" data-sess-tool="' + escHtml(lastTool) + '" data-proj-path="' + escHtml(projPath) + '" onclick="event.stopPropagation();resumeLastProjectSession(this.dataset.sessId,this.dataset.sessTool,this.dataset.projPath)" title="Resume last session (' + escHtml(lastId.slice(0,8)) + ')">&#x21bb; Last</button>';
+        html += '<button class="git-project-launch-btn" data-sess-id="' + escHtml(lastId) + '" data-sess-tool="' + escHtml(lastTool) + '" data-proj-path="' + escHtml(projPath) + '" onclick="event.stopPropagation();resumeLastProjectSession(this.dataset.sessId,this.dataset.sessTool,this.dataset.projPath, this)" title="Resume last session (' + escHtml(lastId.slice(0,8)) + ')">&#x21bb; Last</button>';
       }
     }
 
@@ -1681,6 +2029,7 @@ function renderProjectsHistory(container, sessions) {
     }
 
     html += '<button class="git-project-open-btn" data-proj-key="' + escHtml(projKey) + '" data-proj-name="' + escHtml(projName) + '" onclick="event.stopPropagation();drillIntoGitProject(this.dataset.projKey,this.dataset.projName)" title="Show only this project\'s sessions">Open &rsaquo;</button>';
+    html += renderRepoRefreshControls(projPath, projName);
     html += '<span class="group-chevron">&#9660;</span>';
     html += '</div>';
     html += '<div class="qa-list">';
@@ -2536,7 +2885,7 @@ function _currentTerminalId() {
   return localStorage.getItem('codedash-terminal') || '';
 }
 
-async function launchNewProjectSession(projectPath, tool) {
+async function launchNewProjectSession(projectPath, tool, btn) {
   if (!projectPath) { showToast('No project path'); return; }
   var installed = (window.installedAgents || []).map(function(a) { return a.id; });
   if (installed.length === 0) {
@@ -2549,6 +2898,7 @@ async function launchNewProjectSession(projectPath, tool) {
   var t = tool && installed.indexOf(tool) >= 0 ? tool : null;
   if (!t) t = pickPreferredTool(projectPath, null);
   if (!t) { showToast('No agent installed'); return; }
+  await maybeRefreshBeforeLaunch(projectPath, btn);
   try {
     var resp = await fetch('/api/launch', {
       method: 'POST',
@@ -2869,8 +3219,9 @@ async function refreshAgentsDetection() {
   }
 }
 
-async function resumeLastProjectSession(sessionId, tool, projectPath) {
+async function resumeLastProjectSession(sessionId, tool, projectPath, btn) {
   if (!sessionId) { showToast('No previous session to resume'); return; }
+  await maybeRefreshBeforeLaunch(projectPath, btn);
   try {
     var resp = await fetch('/api/launch', {
       method: 'POST',
@@ -3331,6 +3682,7 @@ function _onProjectsHashChange() {
   loadManualProjects();
   loadAgentsAndSettings();
   window.addEventListener('hashchange', _onProjectsHashChange);
+  loadRepoRefreshState();
   checkForUpdates();
   setInterval(checkForUpdates, 10000); // check every 10s
   setInterval(loadSessions, 60000);    // refresh sessions + invalidate analytics cache every 60s
diff --git a/src/frontend/styles.css b/src/frontend/styles.css
index 74b0d2d..ad00800 100644
--- a/src/frontend/styles.css
+++ b/src/frontend/styles.css
@@ -822,6 +822,12 @@ body {
 .git-project-launch-btn:hover { background: var(--bg-card-hover); }
 .git-project-launch-btn.primary { background: #3b82f6; color: #fff; border-color: #3b82f6; }
 .git-project-launch-btn.primary:hover { opacity: 0.9; }
+.git-project-launch-btn:disabled,
+.git-project-launch-btn[aria-busy="true"] {
+    opacity: 0.6;
+    cursor: not-allowed;
+    pointer-events: none;
+}
 
 .git-project-source-tag {
     display: inline-block;
@@ -3356,7 +3362,6 @@ body {
     gap: 2px;
 }
 
-
 /* ── Projects tab restructure ──────────────────────────────
  * Uses the actual codbash theme variables (--bg-card, --bg-input,
  * --text-primary, --text-secondary, --text-muted, --accent-blue, --border)
@@ -3723,3 +3728,244 @@ body {
     color: var(--text-muted);
     font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
 }
+
+/* ── Repo Auto-Refresh ─────────────────────────────────────── */
+
+.repo-refresh-controls {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    margin-left: 12px;
+    padding-left: 12px;
+    border-left: 1px solid var(--border, rgba(255,255,255,0.08));
+    font-size: 12px;
+    color: var(--text-secondary, #94a3b8);
+    flex-wrap: nowrap;
+}
+
+.repo-refresh-controls.disabled {
+    opacity: 0.6;
+    /* No italic — italic conveys emphasis, not state. */
+}
+
+/* Screen-reader-only — visible to AT, hidden visually. Used for full error
+   detail behind aria-describedby on the error badge. */
+.visually-hidden {
+    position: absolute !important;
+    width: 1px !important;
+    height: 1px !important;
+    padding: 0 !important;
+    margin: -1px !important;
+    overflow: hidden !important;
+    clip: rect(0, 0, 0, 0) !important;
+    white-space: nowrap !important;
+    border: 0 !important;
+}
+
+/* 28px visual / 44px hit area — meets WCAG 2.5.5 target size via the ::after
+   pseudo-element without enlarging the icon itself. */
+.repo-refresh-btn {
+    background: transparent;
+    border: 1px solid var(--border, #334155);
+    color: var(--text-secondary, #94a3b8);
+    width: 28px;
+    height: 28px;
+    min-width: 28px;
+    padding: 0;
+    border-radius: 4px;
+    cursor: pointer;
+    font-size: 14px;
+    line-height: 1;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    position: relative;
+}
+
+.repo-refresh-btn::after {
+    content: "";
+    position: absolute;
+    inset: -8px;
+}
+
+.repo-refresh-btn:hover {
+    background: var(--bg-hover, rgba(255,255,255,0.05));
+    color: var(--text-primary, #e2e8f0);
+}
+
+.repo-refresh-btn:focus-visible {
+    outline: 2px solid #60a5fa;
+    outline-offset: 2px;
+}
+
+.repo-refresh-toggle {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    cursor: pointer;
+    padding: 6px 8px;
+    min-height: 36px;
+    border-radius: 4px;
+}
+
+.repo-refresh-toggle:focus-within {
+    outline: 2px solid #60a5fa;
+    outline-offset: 2px;
+}
+
+.repo-refresh-toggle input[type="checkbox"] {
+    cursor: pointer;
+    margin: 0;
+    width: 16px;
+    height: 16px;
+}
+
+.repo-refresh-toggle input[type="checkbox"]:disabled {
+    cursor: not-allowed;
+    opacity: 0.4;
+}
+
+/* Inner input outline removed; the outer label has :focus-within. */
+.repo-refresh-toggle input[type="checkbox"]:focus { outline: none; }
+
+.repo-refresh-toggle-label {
+    font-size: 12px;
+    color: var(--text-secondary, #94a3b8);
+    user-select: none;
+}
+
+.repo-refresh-badge-slot {
+    display: inline-flex;
+    align-items: center;
+    /* Reserve width so transitions between badge states don't shift
+       surrounding layout (WIG: no CLS). */
+    min-width: 160px;
+    min-height: 24px;
+}
+
+.repo-refresh-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 3px 8px;
+    border-radius: 4px;
+    font-size: 12px;
+    font-weight: 500;
+    line-height: 1.4;
+    max-width: 280px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.repo-refresh-badge-text { display: inline; }
+
+.repo-refresh-badge.fetching {
+    background: rgba(59, 130, 246, 0.18);
+    color: #93c5fd;
+}
+
+.repo-refresh-badge.error {
+    background: rgba(239, 68, 68, 0.22);
+    color: #fecaca;
+    cursor: help;
+}
+.repo-refresh-badge.error:focus-visible {
+    outline: 2px solid #60a5fa;
+    outline-offset: 2px;
+}
+
+.repo-refresh-badge.ok {
+    background: rgba(34, 197, 94, 0.16);
+    color: #bbf7d0;
+}
+
+.repo-refresh-spinner {
+    display: inline-block;
+    width: 10px;
+    height: 10px;
+    border: 2px solid currentColor;
+    border-top-color: transparent;
+    border-radius: 50%;
+    animation: repo-refresh-spin 0.8s linear infinite;
+    flex-shrink: 0;
+}
+
+.repo-refresh-dot {
+    display: inline-block;
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: currentColor;
+    flex-shrink: 0;
+}
+
+@keyframes repo-refresh-spin {
+    to { transform: rotate(360deg); }
+}
+
+/* WCAG 2.3.3 + Apple HIG / Material reduced-motion: spinner becomes a
+   static dim circle for users who opted out of motion. */
+@media (prefers-reduced-motion: reduce) {
+    .repo-refresh-spinner {
+        animation: none;
+        border-top-color: currentColor;
+        opacity: 0.6;
+    }
+}
+
+.repo-refresh-global-toggle {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    margin-left: auto;
+    cursor: pointer;
+    font-size: 13px;
+    color: var(--text-secondary, #94a3b8);
+    padding: 6px 10px;
+    min-height: 36px;
+    border-radius: 4px;
+}
+
+.repo-refresh-global-toggle:focus-within {
+    outline: 2px solid #60a5fa;
+    outline-offset: 2px;
+}
+
+.repo-refresh-global-toggle input[type="checkbox"] {
+    cursor: pointer;
+    margin: 0;
+    width: 16px;
+    height: 16px;
+}
+.repo-refresh-global-toggle input[type="checkbox"]:focus { outline: none; }
+
+/* Light theme — bumped contrasts for AA on all three badge variants and
+   the toggle/label text. */
+[data-theme="light"] .repo-refresh-badge.fetching { background: rgba(59,130,246,0.14); color: #1e40af; }
+[data-theme="light"] .repo-refresh-badge.error    { background: rgba(239,68,68,0.14); color: #991b1b; }
+[data-theme="light"] .repo-refresh-badge.ok       { background: rgba(34,197,94,0.14); color: #166534; }
+[data-theme="light"] .repo-refresh-controls       { color: #475569; }
+[data-theme="light"] .repo-refresh-toggle-label   { color: #475569; }
+[data-theme="light"] .repo-refresh-global-toggle  { color: #475569; }
+
+/* Mid-size mobile / tablet — keep controls reachable. */
+@media (max-width: 768px) {
+    .repo-refresh-badge { max-width: 200px; }
+}
+
+/* Mobile — controls onto their own row, full-width, refresh button visible. */
+@media (max-width: 640px) {
+    .repo-refresh-controls {
+        flex-basis: 100%;
+        margin-left: 0;
+        padding-left: 0;
+        border-left: none;
+        margin-top: 6px;
+        order: 99;
+        flex-wrap: wrap;
+    }
+    .repo-refresh-badge-slot { min-width: 0; }
+    .repo-refresh-badge { max-width: 100%; }
+    .repo-refresh-global-toggle { margin-left: 0; }
+}
diff --git a/src/repo-refresh-routes.js b/src/repo-refresh-routes.js
new file mode 100644
index 0000000..cc9cff4
--- /dev/null
+++ b/src/repo-refresh-routes.js
@@ -0,0 +1,174 @@
+'use strict';
+
+// HTTP routes for repo-refresh under /api/repo-refresh/*.
+//
+// Exposes a single dispatcher: handleRepoRefreshRoute(req, res, { manager, getKnownGitRoots })
+//   returns true if the request matched a known route (and was responded to),
+//   false otherwise so the caller can fall through to other routes.
+
+const MAX_WAIT_MS = 10_000;
+const MAX_BODY_BYTES = 1 << 20; // 1 MiB — settings payloads are tiny; reject anything larger
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+function readJsonBody(req, cb) {
+  let buf = '';
+  let aborted = false;
+  function safeCb(err, val) {
+    if (aborted) return;
+    aborted = true; // exactly-once
+    cb(err, val);
+  }
+  req.on('data', (chunk) => {
+    if (aborted) return;
+    buf += chunk;
+    if (buf.length > MAX_BODY_BYTES) {
+      try { req.destroy(); } catch {}
+      safeCb(new Error('payload_too_large'));
+    }
+  });
+  req.on('end', () => {
+    if (aborted) return;
+    if (!buf) return safeCb(null, {});
+    try { safeCb(null, JSON.parse(buf)); }
+    catch { safeCb(new Error('invalid_payload')); }
+  });
+  req.on('error', (err) => safeCb(err));
+}
+
+// Wrap an async handler so any throw lands in a 500 response instead of an
+// unhandled-rejection log line. Returns a non-async function suitable for the
+// `readJsonBody` callback contract.
+function asyncHandler(res, handler) {
+  return (err, body) => {
+    Promise.resolve()
+      .then(() => handler(err, body))
+      .catch((e) => {
+        try {
+          // eslint-disable-next-line no-console
+          console.error('[repo-refresh] handler threw:', e && e.stack || e);
+        } catch {}
+        // If we already responded, the socket is closed — don't double-send.
+        if (!res.writableEnded) {
+          try { sendJson(res, 500, { error: 'internal_error', code: 'internal_error' }); } catch {}
+        }
+      });
+  };
+}
+
+function validateSettingsInput(input, knownGitRoots) {
+  if (!input || typeof input !== 'object') return 'invalid_payload';
+  if ('refreshOnStartup' in input && typeof input.refreshOnStartup !== 'boolean') {
+    return 'invalid_payload';
+  }
+  if ('perProject' in input) {
+    if (!input.perProject || typeof input.perProject !== 'object') return 'invalid_payload';
+    for (const [k, v] of Object.entries(input.perProject)) {
+      if (!knownGitRoots.has(k)) return 'invalid_payload';
+      if (!v || typeof v !== 'object' || typeof v.autoRefreshOnNewChat !== 'boolean') {
+        return 'invalid_payload';
+      }
+    }
+  }
+  return null;
+}
+
+function handleRepoRefreshRoute(req, res, deps) {
+  if (!req.url) return false;
+  // Strip query string for simple prefix matching.
+  const queryIdx = req.url.indexOf('?');
+  const pathname = queryIdx === -1 ? req.url : req.url.slice(0, queryIdx);
+  if (!pathname.startsWith('/api/repo-refresh/')) return false;
+
+  const { manager, getKnownGitRoots } = deps;
+
+  // ── GET /state ────────────────────────────────
+  if (req.method === 'GET' && pathname === '/api/repo-refresh/state') {
+    sendJson(res, 200, manager.getState());
+    return true;
+  }
+
+  // ── GET /settings ─────────────────────────────
+  if (req.method === 'GET' && pathname === '/api/repo-refresh/settings') {
+    sendJson(res, 200, manager.getState().settings);
+    return true;
+  }
+
+  // ── POST /trigger ─────────────────────────────
+  if (req.method === 'POST' && pathname === '/api/repo-refresh/trigger') {
+    readJsonBody(req, asyncHandler(res, (err, body) => {
+      if (err) return sendJson(res, 400, { error: err.message, code: 'invalid_payload' });
+      const gitRoot = body && body.gitRoot;
+      if (typeof gitRoot !== 'string' || !gitRoot) {
+        return sendJson(res, 400, { error: 'gitRoot is required', code: 'invalid_payload' });
+      }
+      const known = getKnownGitRoots();
+      if (!known.has(gitRoot)) {
+        return sendJson(res, 404, { error: 'unknown gitRoot', code: 'not_found' });
+      }
+      // Fire and forget on the backend — return immediately with current state.
+      manager.triggerRefresh(gitRoot).catch(() => {});
+      const state = manager.getState().repos[gitRoot];
+      sendJson(res, 200, { status: state ? state.status : 'fetching', state });
+    }));
+    return true;
+  }
+
+  // ── POST /wait ────────────────────────────────
+  if (req.method === 'POST' && pathname === '/api/repo-refresh/wait') {
+    readJsonBody(req, asyncHandler(res, async (err, body) => {
+      if (err) return sendJson(res, 400, { error: err.message, code: 'invalid_payload' });
+      const gitRoot = body && body.gitRoot;
+      if (typeof gitRoot !== 'string' || !gitRoot) {
+        return sendJson(res, 400, { error: 'gitRoot is required', code: 'invalid_payload' });
+      }
+      // Same known-roots gate as /trigger: prevents timing-side-channel
+      // enumeration of unknown paths and refuses to long-poll on arbitrary
+      // strings.
+      const known = getKnownGitRoots();
+      if (!known.has(gitRoot)) {
+        return sendJson(res, 404, { error: 'unknown gitRoot', code: 'not_found' });
+      }
+      const requested = Number(body && body.timeoutMs);
+      const timeoutMs = Number.isFinite(requested) && requested > 0
+        ? Math.min(requested, MAX_WAIT_MS)
+        : 2000;
+      try {
+        const result = await manager.waitForRefreshOrTimeout(gitRoot, timeoutMs);
+        sendJson(res, 200, result);
+      } catch (e) {
+        sendJson(res, 500, { error: e.message || 'wait_failed' });
+      }
+    }));
+    return true;
+  }
+
+  // ── POST /settings ────────────────────────────
+  if (req.method === 'POST' && pathname === '/api/repo-refresh/settings') {
+    readJsonBody(req, asyncHandler(res, (err, body) => {
+      if (err) return sendJson(res, 400, { error: err.message, code: 'invalid_payload' });
+      const knownGitRoots = getKnownGitRoots();
+      const validationError = validateSettingsInput(body, knownGitRoots);
+      if (validationError) {
+        return sendJson(res, 400, { error: 'invalid settings payload', code: validationError });
+      }
+      try {
+        const merged = manager.updateSettings(body);
+        sendJson(res, 200, merged);
+      } catch (e) {
+        sendJson(res, 500, { error: e.message || 'write_failed', code: 'write_failed' });
+      }
+    }));
+    return true;
+  }
+
+  // Matched the prefix but no specific route — return 404 so the caller
+  // doesn't blindly send the request elsewhere.
+  sendJson(res, 404, { error: 'unknown repo-refresh route', code: 'not_found' });
+  return true;
+}
+
+module.exports = { handleRepoRefreshRoute };
diff --git a/src/repo-refresh.js b/src/repo-refresh.js
new file mode 100644
index 0000000..b75716d
--- /dev/null
+++ b/src/repo-refresh.js
@@ -0,0 +1,376 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEFAULT_SETTINGS_PATH = path.join(os.homedir(), '.codedash', 'refresh-settings.json');
+
+const DEFAULT_SETTINGS = {
+  version: 1,
+  refreshOnStartup: false,
+  perProject: {},
+};
+
+function defaultRepoState() {
+  return {
+    status: 'idle',
+    startedAt: null,
+    lastSuccessAt: null,
+    lastError: null,
+    lastErrorAt: null,
+  };
+}
+
+function defaultLogger() {
+  return {
+    warn: (msg) => { try { console.warn('[repo-refresh]', msg); } catch {} },
+    error: (msg) => { try { console.error('[repo-refresh]', msg); } catch {} },
+  };
+}
+
+function createRepoRefreshManager(opts = {}) {
+  const execFile = opts.execFile || require('child_process').execFile;
+  const atomicWriteJson = opts.atomicWriteJson || require('./atomic').atomicWriteJson;
+  const settingsPath = opts.settingsPath || DEFAULT_SETTINGS_PATH;
+  const maxConcurrency = opts.maxConcurrency ?? 4;
+  const fetchTimeoutMs = opts.fetchTimeoutMs ?? 60_000;
+  const sigkillGraceMs = opts.sigkillGraceMs ?? 2_000;
+  const debounceMs = opts.debounceMs ?? 500;
+  const resolveGitRoot = opts.resolveGitRoot || ((p) => p);
+  const existsSync = opts.existsSync || fs.existsSync;
+  const logger = opts.logger || defaultLogger();
+  // Optional: when set, initOnStartup only fires for gitRoots also present in
+  // the known set — so a settings-file injection cannot make codbash fetch
+  // arbitrary user paths on next launch. Callable from outside via
+  // `setKnownGitRootsProvider` so the host can wire it after construction.
+  let getKnownGitRoots = opts.getKnownGitRoots || null;
+  function setKnownGitRootsProvider(fn) { getKnownGitRoots = typeof fn === 'function' ? fn : null; }
+
+  const state = new Map();       // gitRoot -> RepoState
+  const inflight = new Map();    // gitRoot -> Promise<RepoState>
+  const waiters = new Map();     // gitRoot -> Set<(state)=>void> for waitForRefreshOrTimeout
+  let settings = { ...DEFAULT_SETTINGS };
+  let saveTimer = null;
+
+  // ── Semaphore ────────────────────────────────────────────
+  // Synchronous when capacity is available so triggerRefresh can spawn the
+  // child process before returning (tests rely on this).
+  const sem = { running: 0, queue: [] };
+  function tryAcquireSync() {
+    if (sem.running < maxConcurrency) { sem.running++; return true; }
+    return false;
+  }
+  function acquireAsync() {
+    return new Promise(resolve => {
+      sem.queue.push(() => { sem.running++; resolve(); });
+    });
+  }
+  function release() {
+    sem.running--;
+    const next = sem.queue.shift();
+    if (next) next();
+  }
+
+  // ── State management ─────────────────────────────────────
+  function setState(gitRoot, partial) {
+    const prev = state.get(gitRoot) || defaultRepoState();
+    const next = { ...prev, ...partial };
+    state.set(gitRoot, next);
+    return next;
+  }
+
+  // Strip credentials from URLs of the form https://user:token@host so that
+  // git's "Authentication failed for 'https://USER:TOKEN@host'" stderr never
+  // ends up in /api/repo-refresh/state (which the browser polls).
+  function redactCredentials(msg) {
+    if (!msg) return '';
+    return String(msg).replace(/(https?:\/\/)[^/\s:@]+:[^/\s@]+@/gi, '$1<redacted>@');
+  }
+
+  function truncateErr(msg) {
+    if (!msg) return '';
+    const s = redactCredentials(msg).trim();
+    return s.length > 200 ? s.slice(0, 200) : s;
+  }
+
+  // ── Fetch runner ─────────────────────────────────────────
+  function runFetch(gitRoot) {
+    return new Promise((resolve) => {
+      let timeoutFired = false;
+      let killTimer = null;
+      let timeoutTimer = null;
+      let settled = false;
+
+      const finalize = (next) => {
+        if (settled) return;
+        settled = true;
+        if (timeoutTimer) clearTimeout(timeoutTimer);
+        if (killTimer) clearTimeout(killTimer);
+        resolve(next);
+      };
+
+      const child = execFile('git', ['-C', gitRoot, 'fetch', '--all', '--prune'], {
+        timeout: 0, // we manage timeout manually for SIGTERM → SIGKILL escalation
+        windowsHide: true,
+      }, (err, stdout, stderr) => {
+        if (timeoutFired) {
+          finalize(setState(gitRoot, {
+            status: 'error',
+            startedAt: null,
+            lastError: truncateErr('timeout after ' + fetchTimeoutMs + 'ms'),
+            lastErrorAt: Date.now(),
+          }));
+          return;
+        }
+        if (err) {
+          const errStderr = err.stderr || stderr || '';
+          const msg = errStderr || err.message || 'git fetch failed';
+          finalize(setState(gitRoot, {
+            status: 'error',
+            startedAt: null,
+            lastError: truncateErr(msg),
+            lastErrorAt: Date.now(),
+          }));
+          return;
+        }
+        finalize(setState(gitRoot, {
+          status: 'idle',
+          startedAt: null,
+          lastSuccessAt: Date.now(),
+          lastError: null,
+          lastErrorAt: null,
+        }));
+      });
+
+      timeoutTimer = setTimeout(() => {
+        timeoutFired = true;
+        try { child.kill('SIGTERM'); } catch {}
+        killTimer = setTimeout(() => {
+          try { child.kill('SIGKILL'); } catch {}
+        }, sigkillGraceMs);
+        if (killTimer && killTimer.unref) killTimer.unref();
+      }, fetchTimeoutMs);
+      if (timeoutTimer && timeoutTimer.unref) timeoutTimer.unref();
+    });
+  }
+
+  // ── Public API ───────────────────────────────────────────
+  function triggerRefresh(gitRoot) {
+    const existing = inflight.get(gitRoot);
+    if (existing) return existing;
+
+    setState(gitRoot, { status: 'fetching', startedAt: Date.now(), lastError: null, lastErrorAt: null });
+
+    const startFetch = () => runFetch(gitRoot).then((finalState) => {
+      release();
+      return finalState;
+    }, (err) => {
+      release();
+      throw err;
+    });
+
+    const promise = tryAcquireSync()
+      ? startFetch()
+      : acquireAsync().then(startFetch);
+
+    inflight.set(gitRoot, promise);
+    promise.then((finalState) => {
+      if (inflight.get(gitRoot) === promise) inflight.delete(gitRoot);
+      const ws = waiters.get(gitRoot);
+      if (ws) {
+        for (const w of ws) w(finalState);
+        waiters.delete(gitRoot);
+      }
+    }, () => {
+      // runFetch never rejects, but guard anyway.
+      if (inflight.get(gitRoot) === promise) inflight.delete(gitRoot);
+    });
+
+    return promise;
+  }
+
+  function triggerAllEnabled() {
+    const promises = [];
+    for (const [gitRoot, cfg] of Object.entries(settings.perProject)) {
+      if (cfg && cfg.autoRefreshOnNewChat) {
+        promises.push(triggerRefresh(gitRoot));
+      }
+    }
+    return Promise.all(promises).then(() => {});
+  }
+
+  function waitForRefreshOrTimeout(gitRoot, timeoutMs) {
+    return new Promise((resolve) => {
+      const current = inflight.get(gitRoot);
+      if (!current) {
+        resolve({ state: state.get(gitRoot) || defaultRepoState(), timedOut: false });
+        return;
+      }
+
+      let settled = false;
+      let to = null;
+
+      const onDone = (finalState) => {
+        if (settled) return;
+        settled = true;
+        if (to) clearTimeout(to);
+        resolve({ state: finalState, timedOut: false });
+      };
+
+      let bucket = waiters.get(gitRoot);
+      if (!bucket) { bucket = new Set(); waiters.set(gitRoot, bucket); }
+      bucket.add(onDone);
+
+      to = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        bucket.delete(onDone);
+        if (bucket.size === 0) waiters.delete(gitRoot);
+        resolve({ state: state.get(gitRoot) || defaultRepoState(), timedOut: true });
+      }, timeoutMs);
+      if (to && to.unref) to.unref();
+    });
+  }
+
+  function getState() {
+    const repos = {};
+    for (const [k, v] of state) repos[k] = v;
+    return { repos, settings };
+  }
+
+  // ── Settings ─────────────────────────────────────────────
+  // Note: we read the settings file via fs.readFileSync directly (not the
+  // injected existsSync) — `existsSync` is reserved for orphan-cleanup of
+  // perProject keys, where a test may scope it to specific gitRoots.
+  function loadSettings() {
+    let raw;
+    try {
+      raw = fs.readFileSync(settingsPath, 'utf8');
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        settings = { ...DEFAULT_SETTINGS };
+        return;
+      }
+      logger.warn('Failed to read refresh settings, using defaults: ' + err.message);
+      settings = { ...DEFAULT_SETTINGS };
+      return;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      settings = {
+        ...DEFAULT_SETTINGS,
+        ...parsed,
+        perProject: (parsed && parsed.perProject && typeof parsed.perProject === 'object') ? parsed.perProject : {},
+      };
+    } catch (err) {
+      logger.warn('Failed to parse refresh settings, using defaults: ' + err.message);
+      settings = { ...DEFAULT_SETTINGS };
+    }
+  }
+
+  function scheduleSave() {
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+      saveTimer = null;
+      try {
+        // 0o600 — settings include the user's project list; keep them
+        // readable only by the owner on shared machines.
+        atomicWriteJson(settingsPath, settings, { mode: 0o600 });
+      } catch (err) {
+        logger.error('Failed to save refresh settings: ' + err.message);
+      }
+    }, debounceMs);
+    if (saveTimer && saveTimer.unref) saveTimer.unref();
+  }
+
+  function updateSettings(partial) {
+    const next = { ...settings };
+    if (Object.prototype.hasOwnProperty.call(partial, 'refreshOnStartup')) {
+      next.refreshOnStartup = !!partial.refreshOnStartup;
+    }
+    if (partial.perProject && typeof partial.perProject === 'object') {
+      next.perProject = { ...settings.perProject, ...partial.perProject };
+    }
+    settings = next;
+    scheduleSave();
+    return settings;
+  }
+
+  function gcOrphans() {
+    const cleaned = {};
+    let changed = false;
+    for (const [key, value] of Object.entries(settings.perProject)) {
+      let alive = false;
+      try {
+        // existsSync is the cheap, reliable check. resolveGitRoot may throw
+        // for transient reasons (timeout, EAGAIN) — treat a thrown
+        // resolveGitRoot as "still alive" so we don't nuke valid settings.
+        if (existsSync(key)) {
+          try {
+            alive = resolveGitRoot(key) !== '';
+          } catch (e) {
+            logger.warn('gcOrphans: resolveGitRoot threw for ' + key + ': ' + e.message + ' (keeping entry)');
+            alive = true;
+          }
+        }
+      } catch (e) {
+        logger.warn('gcOrphans: existsSync threw for ' + key + ': ' + e.message + ' (keeping entry)');
+        alive = true;
+      }
+      if (alive) cleaned[key] = value;
+      else changed = true;
+    }
+    if (changed) {
+      settings = { ...settings, perProject: cleaned };
+      scheduleSave();
+    }
+  }
+
+  function initOnStartup() {
+    gcOrphans();
+    if (!settings.refreshOnStartup) return;
+    // If the host wired a known-roots resolver, require every entry to be
+    // present there before firing. Defense against settings-file injection.
+    let known = null;
+    if (getKnownGitRoots) {
+      try { known = getKnownGitRoots(); } catch { known = null; }
+    }
+    for (const [gitRoot, cfg] of Object.entries(settings.perProject)) {
+      if (!cfg || !cfg.autoRefreshOnNewChat) continue;
+      // When `known` is null the gate isn't wired — open mode for backward
+      // compatibility. When `known` is a Set (even empty) we're in gated mode:
+      // empty means "no paths are trusted", NOT "all paths are trusted".
+      if (known !== null && !known.has(gitRoot)) {
+        logger.warn('initOnStartup: skipping ' + path.basename(gitRoot) + ' (not in known projects)');
+        continue;
+      }
+      // Fire and forget — errors land in per-repo state, not as unhandled rejection.
+      triggerRefresh(gitRoot).catch(() => {});
+    }
+  }
+
+  // Load settings synchronously on construction.
+  loadSettings();
+
+  return {
+    triggerRefresh,
+    waitForRefreshOrTimeout,
+    getState,
+    updateSettings,
+    initOnStartup,
+    setKnownGitRootsProvider,
+    // Exposed for tests only — production callers should never invoke these
+    // directly (loadSettings can drop in-flight debounced changes;
+    // triggerAllEnabled duplicates initOnStartup minus the known-roots gate).
+    __test: { loadSettings, triggerAllEnabled },
+  };
+}
+
+const repoRefreshManager = createRepoRefreshManager();
+
+module.exports = {
+  createRepoRefreshManager,
+  repoRefreshManager,
+  DEFAULT_SETTINGS_PATH,
+};
diff --git a/src/server.js b/src/server.js
index 4fc0de6..00683f9 100644
--- a/src/server.js
+++ b/src/server.js
@@ -18,6 +18,8 @@ const agentsDetect = require('./agents-detect');
 const os = require('os');
 const fs = require('fs');
 const pathLib = require('path');
+const { repoRefreshManager } = require('./repo-refresh');
+const { handleRepoRefreshRoute } = require('./repo-refresh-routes');
 
 // ── Logging ──────────────────────────────────
 const LOG_VERBOSE = process.env.CODEDASH_LOG !== '0';
@@ -111,6 +113,14 @@ function startServer(host, port, openBrowser = true) {
       res.end(svg);
     }
 
+    // ── Repo Auto-Refresh API ───────────────
+    else if (pathname.startsWith('/api/repo-refresh/') && handleRepoRefreshRoute(req, res, {
+      manager: repoRefreshManager,
+      getKnownGitRoots: getKnownGitRoots,
+    })) {
+      // handled
+    }
+
     // ── Sessions API ────────────────────────
     else if (req.method === 'GET' && pathname === '/api/sessions') {
       const sessions = loadSessions();
@@ -1198,6 +1208,34 @@ function readBody(req, cb) {
   req.on('end', () => { if (!aborted) cb(body); });
 }
 
+// Cache so the repo-refresh routes don't pay the loadSessions cost on every hit.
+let _knownGitRootsCache = null;
+let _knownGitRootsCacheAt = 0;
+const KNOWN_GIT_ROOTS_TTL_MS = 5_000;
+
+function getKnownGitRoots() {
+  const now = Date.now();
+  if (_knownGitRootsCache && (now - _knownGitRootsCacheAt) < KNOWN_GIT_ROOTS_TTL_MS) {
+    return _knownGitRootsCache;
+  }
+  const set = new Set();
+  try {
+    for (const p of projectsApi.loadProjects()) {
+      if (p && p.path) set.add(p.path);
+    }
+  } catch {}
+  try {
+    const sessions = loadSessions();
+    const list = Array.isArray(sessions) ? sessions : (sessions && sessions.sessions) || [];
+    for (const s of list) {
+      if (s && s.git_root) set.add(s.git_root);
+    }
+  } catch {}
+  _knownGitRootsCache = set;
+  _knownGitRootsCacheAt = now;
+  return set;
+}
+
 function getBrowserUrl(host, port) {
   const browserHost = getBrowserHost(host);
   const wrappedHost = browserHost.includes(':') && !browserHost.startsWith('[')
@@ -1655,4 +1693,4 @@ ${conversation}`;
   });
 }
 
-module.exports = { startServer };
+module.exports = { startServer, getKnownGitRoots };
diff --git a/tasks/2026-05-12-repo-auto-refresh/plan.md b/tasks/2026-05-12-repo-auto-refresh/plan.md
new file mode 100644
index 0000000..db267fe
--- /dev/null
+++ b/tasks/2026-05-12-repo-auto-refresh/plan.md
@@ -0,0 +1,403 @@
+# Implementation Plan — Repo Auto-Refresh (v1)
+
+> Branch: `feat/repo-auto-refresh`
+> SDD: `/Users/pavelnovak/code/codbash/docs/design/repo-auto-refresh.md`
+> BDD: `/Users/pavelnovak/code/codbash/specs/repo-auto-refresh.feature`
+
+## Goal
+
+Ship per-project background `git fetch --all --prune` driven by a manual button, a per-project "auto-refresh on new chat" toggle, and a global "refresh on startup" toggle — with atomic settings persistence and the existing disk caches retrofitted onto the same atomic helper.
+
+---
+
+## File-by-file change list
+
+| File | New / Mod | One-line summary |
+|------|-----------|------------------|
+| `src/atomic.js` | new | `atomicWriteJson(filePath, obj)` — tmp + fsync + rename helper, stdlib only. |
+| `src/repo-refresh.js` | new | `RepoRefreshManager` singleton: state map, single-flight, semaphore (max 4), settings I/O, fetch worker. |
+| `src/data.js` | mod | Replace `fs.writeFileSync(...)` in `_saveParsedDiskCache`, `_saveGitRootDiskCache`, `_saveCostDiskCache`, `_saveDailyStatsDiskCache` with `atomicWriteJson`. |
+| `src/server.js` | mod | +4 routes under `/api/repo-refresh/*` (state, trigger, wait, settings GET/POST). |
+| `bin/cli.js` | mod | After `startServer(...)` call `RepoRefreshManager.initOnStartup()` (non-blocking). |
+| `src/frontend/app.js` | mod | Project-card toggle + refresh button + spinner/badge + 2s polling + new-chat hook + header global toggle. |
+| `src/frontend/styles.css` | mod | `.repo-refresh-spinner`, `.repo-refresh-badge-error`, `.repo-refresh-badge-ok`, focus ring, mobile collapse. |
+| `docs/ARCHITECTURE.md` | mod | New "Repo Auto-Refresh" section (state machine + endpoints). |
+| `test/atomic.test.js` | new | Atomic write semantics: rename, partial-write protection, EACCES propagation. |
+| `test/repo-refresh.test.js` | new | Manager: single-flight, semaphore=4, timeout=60s, error mapping, settings round-trip, corrupt-file fallback. |
+| `test/repo-refresh-api.test.js` | new | Server routes: `/state`, `/trigger`, `/wait` (with `timedOut`), `/settings` GET+POST validation. |
+
+No new dependencies. Stdlib only (`child_process`, `fs`, `path`, `os`, `crypto`).
+
+---
+
+## Phase 1 — `atomic.js` helper + tests + retrofit existing caches
+
+**Type:** implementation + test + wiring
+
+**Files:**
+- `src/atomic.js` (new)
+- `src/data.js` (mod — 4 call sites)
+- `test/atomic.test.js` (new)
+
+**Signatures (TS-style):**
+```ts
+// src/atomic.js
+export function atomicWriteJson(filePath: string, obj: unknown): void
+// Steps: ensure dir exists, write to `${filePath}.tmp`, fsync the fd,
+//        close, rename(tmp → filePath). Throws on failure.
+```
+
+**BDD scenarios satisfied:**
+- "Settings write is atomic — crash mid-write leaves the file consistent"
+- "Existing git-root cache file uses the same atomic write helper"
+
+**Tests (`node --test test/atomic.test.js`):**
+- `atomicWriteJson writes valid JSON and the target file matches input`
+- `atomicWriteJson creates the parent directory if missing`
+- `atomicWriteJson removes the .tmp file after successful rename`
+- `atomicWriteJson throws on EACCES of the tmp file`
+- `atomicWriteJson does not leave partial data if rename fails (mock fs.renameSync to throw)`
+
+**Manual verification:**
+```
+node -e "require('./src/atomic').atomicWriteJson('/tmp/foo.json', {a:1})"
+cat /tmp/foo.json
+ls /tmp/foo.json*    # no .tmp left behind
+```
+Then start codbash, let it touch the existing caches; confirm files remain valid JSON and no `*.tmp` leftovers in `~/.codedash/`.
+
+**Size:** S
+
+---
+
+## Phase 2 — `RepoRefreshManager` core (no HTTP, no UI)
+
+**Type:** implementation + test
+
+**Files:**
+- `src/repo-refresh.js` (new)
+- `test/repo-refresh.test.js` (new)
+
+**Signatures (TS-style):**
+```ts
+// src/repo-refresh.js
+interface RepoState {
+  status: 'idle' | 'fetching' | 'error'
+  startedAt: number | null
+  lastSuccessAt: number | null
+  lastError: string | null
+  lastErrorAt: number | null
+}
+
+interface RefreshSettings {
+  version: 1
+  refreshOnStartup: boolean
+  perProject: Record<string, { autoRefreshOnNewChat: boolean }>
+}
+
+class RepoRefreshManager {
+  // module-level singleton via `module.exports = new RepoRefreshManager()`
+  triggerRefresh(gitRoot: string): Promise<RepoState>
+  triggerAllEnabled(): Promise<void>
+  waitForRefreshOrTimeout(gitRoot: string, timeoutMs: number): Promise<{ state: RepoState, timedOut: boolean }>
+  getState(): { repos: Record<string, RepoState>, settings: RefreshSettings }
+  updateSettings(partial: Partial<RefreshSettings>): RefreshSettings    // debounced 500ms save
+  loadSettings(): void                                                  // sync, called from ctor
+  initOnStartup(): void                                                 // async fire-and-forget
+}
+
+// Internal:
+// _semaphore = { running: 0, queue: [], max: 4 }
+// _inflight  = Map<gitRoot, Promise<RepoState>>
+// _runFetch(gitRoot): Promise<RepoState>   // execFile('git', ['-C', gitRoot, 'fetch', '--all', '--prune'], { timeout: 60_000 })
+// _truncateErr(msg): string                // ~200 chars
+// _saveSettingsDebounced()                 // calls atomicWriteJson
+```
+
+**Settings path:** `path.join(os.homedir(), '.codedash', 'refresh-settings.json')`. `ensureDir` on first save (legacy code already creates `~/.codedash/`).
+
+**BDD scenarios satisfied:**
+- "Service start with refreshOnStartup=true triggers all enabled repos"
+- "Fetch fails because SSH agent is not running"
+- "Fetch exceeds the 60-second timeout"
+- "Corrupt settings file on startup falls back to defaults"
+- "Saving settings fails (disk full, permission error)"
+- "Repeated trigger while a fetch is in flight is single-flight"
+- "Five simultaneous triggers respect the max-concurrency of 4"
+- "gitRoot path with spaces or special characters in settings file"
+- "Project exists but has no remote configured" (fetch exits 0)
+- "Bare repo skipped without error" (invariant — manager only acts on gitRoots provided)
+
+**Tests (`node --test test/repo-refresh.test.js`):**
+- `triggerRefresh transitions idle → fetching → idle on success` (stub `execFile`)
+- `triggerRefresh single-flight: 2 concurrent calls share the same promise, 1 child process spawned`
+- `semaphore caps concurrent fetches at 4; 5th queues until one finishes`
+- `60s timeout: child killed (SIGTERM then SIGKILL grace), state=error with "timeout" in lastError, inflight cleared`
+- `non-zero exit propagates as state=error with truncated stderr (≤200 chars)`
+- `corrupt settings file → loadSettings logs warning, sets defaults, leaves file on disk untouched`
+- `updateSettings round-trips through atomicWriteJson (mock the helper); debounced save`
+- `gitRoot with spaces is passed as a single argv element (snapshot the execFile args)`
+- `initOnStartup with refreshOnStartup=true triggers only autoRefreshOnNewChat=true repos and does not block`
+
+**Manual verification:**
+```
+node -e "const m=require('./src/repo-refresh'); m.triggerRefresh(process.cwd()).then(s=>console.log(s))"
+ls ~/.codedash/refresh-settings.json
+```
+
+**Size:** L
+
+---
+
+## Phase 3 — HTTP routes wired into `server.js`
+
+**Type:** wiring + test
+
+**Files:**
+- `src/server.js` (mod — +4 routes)
+- `test/repo-refresh-api.test.js` (new)
+
+**Routes:**
+```ts
+GET  /api/repo-refresh/state
+  → 200 { repos: Record<gitRoot, RepoState>, settings: RefreshSettings }
+
+POST /api/repo-refresh/trigger
+  body: { gitRoot: string }
+  → 200 { status, state }
+  → 404 { error, code: 'not_found' }                // unknown gitRoot (not in known projects)
+  → 400 { error, code: 'invalid_payload' }          // missing gitRoot
+
+POST /api/repo-refresh/wait
+  body: { gitRoot: string, timeoutMs?: number /* default 2000, max 10_000 */ }
+  → 200 { state, timedOut }
+
+GET  /api/repo-refresh/settings  → 200 RefreshSettings
+POST /api/repo-refresh/settings
+  body: Partial<RefreshSettings>
+  → 200 RefreshSettings
+  → 400 { error, code: 'invalid_payload' }          // unknown gitRoot in perProject
+  → 500 { error, code: 'write_failed' }             // atomicWriteJson threw
+```
+
+Validation: each `gitRoot` in `perProject` must be present in the set of known gitRoots (collected from `loadSessions()` + `loadProjects()` from `projects.js`).
+
+**BDD scenarios satisfied:**
+- "User clicks the Refresh button on a project card" (backend half)
+- "First-ever launch — no projects discovered yet" (returns `{ repos: {}, settings: defaults }`)
+- "Slow fetch shows persistent spinner without blocking other UI" (server stays responsive — relies on async execFile)
+- "Saving settings fails" (500 response shape)
+
+**Tests (`node --test test/repo-refresh-api.test.js`):**
+- Spin up `http.createServer` via `startServer` on an ephemeral port, hit each route with `http.request`.
+- `POST /trigger { gitRoot: <known> }` returns 200 with `status: "fetching"` immediately.
+- `POST /trigger { gitRoot: <unknown> }` returns 404 + code.
+- `POST /trigger { }` returns 400 + code.
+- `POST /wait` returns `{ timedOut: true }` after `timeoutMs` when the fetch is mocked to never finish.
+- `GET /state` returns `{ repos: {}, settings: <defaults> }` on a fresh service.
+- `POST /settings` with unknown gitRoot → 400.
+- `POST /settings` persists; subsequent `GET /settings` returns the saved value.
+
+**Manual verification:**
+```
+curl -s http://localhost:3847/api/repo-refresh/state | jq
+curl -s -X POST http://localhost:3847/api/repo-refresh/trigger \
+  -H 'content-type: application/json' \
+  -d '{"gitRoot":"/Users/pavelnovak/code/codbash"}' | jq
+curl -s http://localhost:3847/api/sessions -w '\n%{time_total}s\n' >/dev/null
+# event loop check: time_total < 0.1s while a fetch is mid-flight
+```
+
+**Size:** M
+
+---
+
+## Phase 4 — Startup hook in `bin/cli.js`
+
+**Type:** wiring
+
+**Files:**
+- `bin/cli.js` (mod)
+
+**Change:** in the `run` / `start` case, immediately after `startServer(host, port, !noBrowser);`, call:
+
+```ts
+const { repoRefreshManager } = require('../src/repo-refresh')
+process.nextTick(() => repoRefreshManager.initOnStartup())
+```
+
+`initOnStartup` reads settings; if `refreshOnStartup === true`, it iterates `perProject` entries where `autoRefreshOnNewChat === true` and calls `triggerRefresh(gitRoot)` for each (semaphore caps to 4). Errors are swallowed and recorded in the per-repo `RepoState`.
+
+**BDD scenarios satisfied:**
+- "Service start with refreshOnStartup=true triggers all enabled repos" (full end-to-end)
+- "Corrupt settings file on startup falls back to defaults" (no fetches launched)
+
+**Tests:** Covered indirectly by Phase 2's `initOnStartup` test (no new file).
+
+**Manual verification:**
+```
+echo '{"version":1,"refreshOnStartup":true,"perProject":{"'$PWD'":{"autoRefreshOnNewChat":true}}}' \
+  > ~/.codedash/refresh-settings.json
+make restart && sleep 1
+curl -s localhost:3847/api/repo-refresh/state | jq '.repos'
+# expect repos["<pwd>"].status to be "fetching" or "idle" with lastSuccessAt set
+```
+
+**Size:** S
+
+---
+
+## Phase 5 — Frontend: card UI, polling, new-chat hook
+
+**Type:** frontend
+
+**Files:**
+- `src/frontend/app.js` (mod)
+- `src/frontend/styles.css` (mod)
+
+**Functions added (plain browser JS, no modules):**
+```js
+// Module-scope state
+let repoRefreshState = { repos: {}, settings: { refreshOnStartup: false, perProject: {} } }
+let repoRefreshLoaded = false        // gates the "loading" state from BDD
+let repoRefreshPollTimer = null
+
+async function loadRepoRefreshState()                // GET /state — called on first render
+function renderRepoRefreshControls(projKey, projName) // returns HTML: toggle + refresh button + badge
+function renderGlobalRefreshToggle()                 // header HTML for "Refresh on startup"
+async function onClickRefresh(gitRoot)               // POST /trigger, kick polling
+async function onTogglePerProject(gitRoot, checked)  // optimistic flip → POST /settings → rollback+toast on fail
+async function onToggleGlobalStartup(checked)        // same pattern
+function startRepoRefreshPollingIfNeeded()           // setInterval(2000) only while any visible repo === 'fetching'
+function stopRepoRefreshPolling()
+async function maybeRefreshBeforeLaunch(gitRoot)     // called from existing /api/launch click path:
+  //   if (!autoRefresh) return;
+  //   showInlineSpinner(); await trigger; await wait({timeoutMs:2000}); hideInlineSpinner();
+```
+
+Integration points in existing code:
+- `renderProjects()` (around line 1248): inject controls + badge into each card; render header global toggle once.
+- Existing "New chat" click handler that calls `POST /api/launch` (~ lines 2183 / 2205): wrap with `await maybeRefreshBeforeLaunch(gitRoot)` ahead of the launch fetch.
+- Initial bootstrap: call `loadRepoRefreshState()` once at app init.
+
+A11y:
+- Toggle: `<input type="checkbox" role="switch" aria-checked="..." aria-label="Auto-refresh on new chat for <name>">`
+- Refresh button: `aria-label="Refresh <name>"`, `<span class="visually-hidden">` for the icon.
+- Status badge: `<span role="status" aria-live="polite">Fetching <name></span>` / `Updated` / `Refresh failed: <err>`.
+- Focus ring on all controls (no `outline:none` without replacement).
+
+Mobile: at `<640px`, refresh button always visible (no hover state), toggle on its own row beneath the title. Truncate long names with `text-overflow: ellipsis` + `title="<full path>"`.
+
+**BDD scenarios satisfied:**
+- "User clicks the Refresh button on a project card" (UI half)
+- "New-chat click on a project with auto-refresh toggle on, fetch completes within 2s"
+- "New-chat trigger times out at 2s, session opens with stale refs"
+- "First page load — frontend renders before /state responds"
+- "Slow fetch shows persistent spinner without blocking other UI"
+- "Saving settings fails" (toast + optimistic rollback)
+- "Toggling auto-refresh with keyboard only"
+- "Triggering Refresh with keyboard only"
+- "Screen reader announces state transitions"
+- "Project with a very long name renders the card without overflow"
+- "First-ever launch — no projects discovered yet" (no controls rendered)
+
+**Tests:** No automated frontend tests in this project (zero-dep, no Playwright). Manual + screen-reader verification.
+
+**Manual verification:**
+1. Open dashboard → Projects view; confirm header toggle and per-card controls render.
+2. Toggle off → controls disabled, no badge.
+3. Click "↻ Refresh" → spinner appears, polling starts at 2s, transitions to "Updated just now" within ~1s for a healthy repo.
+4. Disconnect network + click "↻ Refresh" → after ≤60s, red badge with truncated error; "Retry" re-triggers.
+5. Enable auto-refresh + click "New chat" → spinner shows then session window opens within 2s.
+6. Tab through controls — all reachable with visible focus, Space toggles, Enter triggers.
+7. VoiceOver: focus the badge during a fetch → hears "Fetching <name>"; after success → "Updated".
+8. Resize to 375px width → button visible, toggle on its own row, long names truncated with tooltip.
+
+**Size:** L
+
+---
+
+## Phase 6 — Docs
+
+**Type:** wiring (docs)
+
+**Files:**
+- `docs/ARCHITECTURE.md` (mod)
+
+**Content:** new section "Repo Auto-Refresh" with:
+- State machine diagram (copied from SDD)
+- Endpoint table (copied from SDD § "API contract")
+- Reference to `src/atomic.js` as the canonical write helper for all codbash JSON caches.
+
+**BDD scenarios satisfied:** none directly — documentation.
+
+**Manual verification:** read it.
+
+**Size:** S
+
+---
+
+## Order of phases — rationale
+
+| # | Phase | Why this order |
+|---|-------|----------------|
+| 1 | `atomic.js` + retrofit | Foundation. Pure stdlib helper with no dependents. Retrofitting now closes PR #212's deferred MEDIUM in the same PR (per D9) and exercises the helper before settings depend on it. |
+| 2 | `RepoRefreshManager` core | Pure-Node logic, fully testable without HTTP or UI. Catches the hardest semantics (single-flight, semaphore, timeout, debounce) before they're wrapped in network code. |
+| 3 | HTTP routes | Thin wrapper over Phase 2. Lets manual curl-driven testing validate the manager before the frontend lands. |
+| 4 | Startup hook | One-liner that depends on Phase 2's `initOnStartup` being reliable; trivial after Phase 3 because we can already curl `/state` to verify. |
+| 5 | Frontend | Reaches a working backend behind real endpoints; can be iterated visually without churning the backend. |
+| 6 | Docs | Last, because endpoint shapes and helper names are now stable. |
+
+Each phase is independently reviewable: 1 leaves the app functionally identical (retrofit + new helper); 2 adds dormant code; 3 makes it curl-testable; 4 wires startup; 5 ships UX; 6 documents.
+
+---
+
+## Risks specific to implementation (beyond SDD risk table)
+
+| # | Risk | Mitigation at code-writing time |
+|---|------|----------------------------------|
+| I1 | Circular dep between `bin/cli.js` → `src/server.js` → `src/repo-refresh.js` → `src/data.js` (for `resolveGitRoot`) | `repo-refresh.js` must `require('./data')` lazily inside `getKnownGitRoots()` to avoid load-order issues, or accept `resolveGitRoot` as an injected dep. Recommend lazy `require` inside the function. |
+| I2 | `atomicWriteJson` retrofit in `data.js` runs on hot paths (`_saveCostDiskCache` is called often) | Confirm `renameSync` cost is acceptable on macOS APFS / Linux ext4 (single syscall, ~1ms). If it shows up in profiling, switch to async `atomicWriteJson` for non-settings call sites. Out of scope for v1 unless tests show regression. |
+| I3 | `execFile('git', ['-C', gitRoot, 'fetch', '--all', '--prune'], { timeout })` does not kill on Windows with SIGKILL | Use `{ timeout: 60_000, killSignal: 'SIGTERM' }` and a manual 2s grace `setTimeout` → `child.kill('SIGKILL')`. macOS/Linux only matters for v1; Windows degrades to SIGTERM only — acceptable. |
+| I4 | Frontend polling not stopped when user leaves Projects view → wasted requests | Track `currentView` (already in app.js); in the 2s tick, exit early if `currentView !== 'projects'`. |
+| I5 | Optimistic toggle rollback races with a second toggle click | Disable the input while the POST is inflight; re-enable on response. Keep last-committed value in a side map for rollback. |
+| I6 | `~/.codedash/` directory does not exist on first run | `atomicWriteJson` must `mkdirSync(path.dirname(filePath), { recursive: true })` before writing the tmp file. |
+| I7 | Settings file shares `~/.codedash/` with existing legacy disk caches | Per resolved Open Question 1: co-locate. New `refresh-settings.json` sits alongside `gitroot-cache-v2.json` and friends. `mkdirSync(~/.codedash, {recursive:true})` already happens via legacy code; we reuse the same dir. |
+| I8 | Server already buffered JSON body parsing pattern — re-use it for the new POST routes | Audit `src/server.js` for the existing helper that reads `req` to a string and `JSON.parse`s it; re-use to keep style consistent. Do not introduce a new pattern. |
+| I9 | `node --test test/wsl-windows.test.js` already fails on macOS | Pre-existing and unrelated; don't gate the PR on it. CI matrix is unaffected. |
+
+---
+
+## Estimated effort per phase
+
+| Phase | Size |
+|-------|------|
+| 1 — `atomic.js` + retrofit + tests | S |
+| 2 — `RepoRefreshManager` core + tests | L |
+| 3 — HTTP routes + tests | M |
+| 4 — Startup hook | S |
+| 5 — Frontend (UI + polling + new-chat hook + a11y + CSS) | L |
+| 6 — Docs | S |
+
+Total: roughly two days of focused work, dominated by Phases 2 and 5.
+
+---
+
+## Out of scope for this plan (deferred from SDD)
+
+- Periodic scheduler (5/10/15/30/60 min) — SDD § Out of scope.
+- Page-refresh trigger from the browser — SDD § Out of scope.
+- Full settings modal with extended options — SDD § Out of scope.
+- "Behind by N commits" notifications when `origin/<tracking>` has moved ahead — SDD § Out of scope.
+- Discovery of repos without sessions — SDD § Out of scope (a card appears only after the first session in it).
+- Migration of legacy `~/.codedash/` cache file names — Phase 1 only retrofits the write path through `atomicWriteJson`; file names are unchanged.
+- Windows-specific SIGKILL escalation logic — degraded to SIGTERM via Node default; acceptable for v1.
+- Frontend automated tests (Playwright / jsdom) — project is zero-dep with no test runner for browser JS; manual verification only.
+
+---
+
+## Open questions — resolved
+
+1. **Settings file location** → `~/.codedash/refresh-settings.json` (co-located with legacy caches). SDD's earlier mention of a separate `~/.codbash/` directory is **superseded** by this answer; both the SDD and this plan now consistently use `~/.codedash/`. Settings file lives next to the existing `_save*DiskCache` outputs — one directory for all codbash state.
+2. **`maybeRefreshBeforeLaunch` on fetch failure** → open the session anyway; show a non-blocking toast `Fetch failed: <truncated err>`; the project card's red dot badge already reflects the error state. Don't block the user's primary action because of an auxiliary feature.
+3. **Orphan entries in `POST /settings`** → accept silently. On every `initOnStartup`, sweep `perProject` keys: any key for which `!fs.existsSync(gitRoot) || resolveGitRoot(gitRoot) === ''` is dropped, then `atomicWriteJson` persists the cleaned settings. This means a user who renames or deletes a project keeps the toggle history if they recreate the path at the same location.
diff --git a/test/atomic.test.js b/test/atomic.test.js
new file mode 100644
index 0000000..3870a8a
--- /dev/null
+++ b/test/atomic.test.js
@@ -0,0 +1,94 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { atomicWriteJson } = require('../src/atomic');
+
+function mkTmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+}
+
+test('atomicWriteJson writes valid JSON matching the input object', () => {
+  const tmp = mkTmp('codbash-atomic-');
+  try {
+    const target = path.join(tmp, 'data.json');
+    const obj = { a: 1, b: 'two', c: [3, 4], d: { nested: true } };
+    atomicWriteJson(target, obj);
+    const parsed = JSON.parse(fs.readFileSync(target, 'utf8'));
+    assert.deepEqual(parsed, obj);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('atomicWriteJson creates the parent directory if missing', () => {
+  const tmp = mkTmp('codbash-atomic-');
+  try {
+    const target = path.join(tmp, 'sub', 'nested', 'data.json');
+    assert.equal(fs.existsSync(path.dirname(target)), false);
+    atomicWriteJson(target, { ok: true });
+    assert.equal(fs.existsSync(target), true);
+    assert.deepEqual(JSON.parse(fs.readFileSync(target, 'utf8')), { ok: true });
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('atomicWriteJson cleans up the .tmp file after a successful rename', () => {
+  const tmp = mkTmp('codbash-atomic-');
+  try {
+    const target = path.join(tmp, 'data.json');
+    atomicWriteJson(target, { a: 1 });
+    assert.equal(fs.existsSync(target), true);
+    assert.equal(fs.existsSync(target + '.tmp'), false, '.tmp file must not linger');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('atomicWriteJson throws when the target directory is not writable (EACCES)', () => {
+  // Skip if running as root — chmod 555 won't deny root.
+  if (process.getuid && process.getuid() === 0) return;
+  const tmp = mkTmp('codbash-atomic-');
+  try {
+    fs.chmodSync(tmp, 0o555); // read+exec only — no write
+    const target = path.join(tmp, 'data.json');
+    assert.throws(
+      () => atomicWriteJson(target, { a: 1 }),
+      /EACCES|EPERM|permission denied/i,
+    );
+  } finally {
+    try { fs.chmodSync(tmp, 0o755); } catch {}
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('atomicWriteJson never leaves the target file in a partial-write state', () => {
+  // If rename fails, the original target (or absence) must be preserved.
+  // We simulate by writing valid v1 first, then making rename fail on v2.
+  const tmp = mkTmp('codbash-atomic-');
+  const origRename = fs.renameSync;
+  try {
+    const target = path.join(tmp, 'data.json');
+    atomicWriteJson(target, { version: 1 });
+    const v1Contents = fs.readFileSync(target, 'utf8');
+
+    // Force the next rename to throw.
+    fs.renameSync = () => { throw new Error('simulated rename failure'); };
+    assert.throws(
+      () => atomicWriteJson(target, { version: 2 }),
+      /simulated rename failure/,
+    );
+
+    // Target file must still be the old, valid v1 — never half-written.
+    fs.renameSync = origRename;
+    assert.equal(fs.readFileSync(target, 'utf8'), v1Contents);
+    // And no .tmp leftover.
+    assert.equal(fs.existsSync(target + '.tmp'), false);
+  } finally {
+    fs.renameSync = origRename;
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
diff --git a/test/repo-refresh-api.test.js b/test/repo-refresh-api.test.js
new file mode 100644
index 0000000..2cf790d
--- /dev/null
+++ b/test/repo-refresh-api.test.js
@@ -0,0 +1,279 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { createRepoRefreshManager } = require('../src/repo-refresh');
+const { handleRepoRefreshRoute } = require('../src/repo-refresh-routes');
+
+function mkTmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+}
+
+function makeMockExecFile() {
+  const calls = [];
+  function execFile(cmd, args, opts, cb) {
+    if (typeof opts === 'function') { cb = opts; opts = undefined; }
+    const child = { killed: false, _signals: [], kill(s) { this.killed = true; this._signals.push(s || 'SIGTERM'); } };
+    const call = { cmd, args, opts: opts || {}, child, _cb: cb, _resolved: false };
+    call.resolve = (stdout = '', stderr = '') => {
+      if (call._resolved) return; call._resolved = true; cb(null, stdout, stderr);
+    };
+    call.fail = (err, stderr = '') => {
+      if (call._resolved) return; call._resolved = true;
+      cb(Object.assign(err || new Error('fail'), { stderr }), '', stderr);
+    };
+    calls.push(call);
+    return child;
+  }
+  return { execFile, calls };
+}
+
+// Mount the router on a real http server bound to an ephemeral port.
+function startTestServer(deps) {
+  return new Promise((resolve) => {
+    const server = http.createServer((req, res) => {
+      const handled = handleRepoRefreshRoute(req, res, deps);
+      if (!handled) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'not_my_route' }));
+      }
+    });
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolve({ server, port });
+    });
+  });
+}
+
+function stopServer(server) {
+  return new Promise((resolve) => server.close(resolve));
+}
+
+function request(port, method, urlPath, body) {
+  return new Promise((resolve, reject) => {
+    const opts = {
+      host: '127.0.0.1', port, method, path: urlPath,
+      headers: body ? { 'Content-Type': 'application/json' } : {},
+    };
+    const req = http.request(opts, (res) => {
+      let buf = '';
+      res.on('data', (chunk) => buf += chunk);
+      res.on('end', () => {
+        let parsed = null;
+        try { parsed = buf ? JSON.parse(buf) : null; } catch {}
+        resolve({ status: res.statusCode, headers: res.headers, body: parsed, raw: buf });
+      });
+    });
+    req.on('error', reject);
+    if (body !== undefined) req.write(typeof body === 'string' ? body : JSON.stringify(body));
+    req.end();
+  });
+}
+
+function makeDeps(extraOverrides = {}) {
+  const settingsPath = path.join(mkTmp('codbash-api-'), 'settings.json');
+  const exec = makeMockExecFile();
+  const manager = createRepoRefreshManager({
+    execFile: exec.execFile,
+    settingsPath,
+    maxConcurrency: 4,
+    fetchTimeoutMs: 60_000,
+    sigkillGraceMs: 1_000,
+    debounceMs: 10,
+    resolveGitRoot: (p) => p,
+    existsSync: () => true,
+    ...extraOverrides,
+  });
+  // Fixed list of "known" gitRoots used for /trigger and /settings validation.
+  const knownGitRoots = new Set(['/repos/known-a', '/repos/known-b']);
+  const getKnownGitRoots = () => knownGitRoots;
+  return { manager, getKnownGitRoots, settingsPath, exec, knownGitRoots };
+}
+
+// ── Tests ─────────────────────────────────────────────────────
+
+test('GET /api/repo-refresh/state returns repos + settings on a fresh manager', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'GET', '/api/repo-refresh/state');
+    assert.equal(res.status, 200);
+    assert.deepEqual(res.body.repos, {});
+    assert.equal(res.body.settings.refreshOnStartup, false);
+    assert.deepEqual(res.body.settings.perProject, {});
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('POST /api/repo-refresh/trigger spawns a fetch for a known gitRoot', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'POST', '/api/repo-refresh/trigger', { gitRoot: '/repos/known-a' });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.state.status, 'fetching');
+    assert.equal(deps.exec.calls.length, 1);
+    assert.equal(deps.exec.calls[0].args[1], '/repos/known-a');
+    deps.exec.calls[0].resolve();
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('POST /api/repo-refresh/trigger returns 404 with code=not_found for an unknown gitRoot', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'POST', '/api/repo-refresh/trigger', { gitRoot: '/repos/wat' });
+    assert.equal(res.status, 404);
+    assert.equal(res.body.code, 'not_found');
+    assert.equal(deps.exec.calls.length, 0, 'no child process should be spawned for unknown gitRoot');
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('POST /api/repo-refresh/trigger returns 400 with code=invalid_payload when gitRoot is missing', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'POST', '/api/repo-refresh/trigger', {});
+    assert.equal(res.status, 400);
+    assert.equal(res.body.code, 'invalid_payload');
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('POST /api/repo-refresh/trigger returns 400 for malformed JSON body', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'POST', '/api/repo-refresh/trigger', '{ not json');
+    assert.equal(res.status, 400);
+    assert.equal(res.body.code, 'invalid_payload');
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('POST /api/repo-refresh/wait returns timedOut=true when fetch outruns the wait', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    // Start a fetch that never resolves.
+    await request(port, 'POST', '/api/repo-refresh/trigger', { gitRoot: '/repos/known-a' });
+    const res = await request(port, 'POST', '/api/repo-refresh/wait', { gitRoot: '/repos/known-a', timeoutMs: 30 });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.timedOut, true);
+    assert.equal(res.body.state.status, 'fetching');
+    deps.exec.calls[0].resolve();
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('POST /api/repo-refresh/wait returns 404 with code=not_found for unknown gitRoot', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'POST', '/api/repo-refresh/wait', { gitRoot: '/repos/not-mine' });
+    assert.equal(res.status, 404);
+    assert.equal(res.body.code, 'not_found');
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('POST /api/repo-refresh/wait clamps timeoutMs to a sane maximum', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    // No fetch in flight — wait should return immediately regardless of timeoutMs.
+    // gitRoot must be known (post-fix); known-a is in the test's known set.
+    const res = await request(port, 'POST', '/api/repo-refresh/wait', { gitRoot: '/repos/known-a', timeoutMs: 999_999_999 });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.timedOut, false);
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('GET /api/repo-refresh/settings returns the current settings', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'GET', '/api/repo-refresh/settings');
+    assert.equal(res.status, 200);
+    assert.equal(res.body.refreshOnStartup, false);
+    assert.deepEqual(res.body.perProject, {});
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('POST /api/repo-refresh/settings merges and persists valid input', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'POST', '/api/repo-refresh/settings', {
+      refreshOnStartup: true,
+      perProject: { '/repos/known-a': { autoRefreshOnNewChat: true } },
+    });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.refreshOnStartup, true);
+    assert.deepEqual(res.body.perProject, { '/repos/known-a': { autoRefreshOnNewChat: true } });
+
+    // Wait past the debounce so the file lands on disk.
+    await new Promise(r => setTimeout(r, 30));
+    const onDisk = JSON.parse(fs.readFileSync(deps.settingsPath, 'utf8'));
+    assert.equal(onDisk.refreshOnStartup, true);
+    assert.deepEqual(onDisk.perProject, { '/repos/known-a': { autoRefreshOnNewChat: true } });
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('POST /api/repo-refresh/settings returns 400 with code=invalid_payload for unknown gitRoot in perProject', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'POST', '/api/repo-refresh/settings', {
+      perProject: { '/repos/wat': { autoRefreshOnNewChat: true } },
+    });
+    assert.equal(res.status, 400);
+    assert.equal(res.body.code, 'invalid_payload');
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('GET /api/repo-refresh/settings returns the value just POSTed', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    await request(port, 'POST', '/api/repo-refresh/settings', {
+      perProject: { '/repos/known-a': { autoRefreshOnNewChat: true } },
+    });
+    const res = await request(port, 'GET', '/api/repo-refresh/settings');
+    assert.equal(res.status, 200);
+    assert.deepEqual(res.body.perProject, { '/repos/known-a': { autoRefreshOnNewChat: true } });
+  } finally {
+    await stopServer(server);
+  }
+});
+
+test('Unknown route under /api/repo-refresh/ returns 404', async () => {
+  const deps = makeDeps();
+  const { server, port } = await startTestServer(deps);
+  try {
+    const res = await request(port, 'GET', '/api/repo-refresh/nonsense');
+    assert.equal(res.status, 404);
+  } finally {
+    await stopServer(server);
+  }
+});
diff --git a/test/repo-refresh.test.js b/test/repo-refresh.test.js
new file mode 100644
index 0000000..aa34269
--- /dev/null
+++ b/test/repo-refresh.test.js
@@ -0,0 +1,404 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { createRepoRefreshManager } = require('../src/repo-refresh');
+
+function mkTmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+}
+
+// ── execFile mock ─────────────────────────────────────────────
+// Captures call args and lets the test resolve/reject each call independently.
+function makeMockExecFile() {
+  const calls = [];
+  function execFile(cmd, args, opts, cb) {
+    // execFile signature can be (cmd, args, cb) or (cmd, args, opts, cb).
+    if (typeof opts === 'function') { cb = opts; opts = undefined; }
+    const child = {
+      killed: false,
+      _signals: [],
+      kill(sig) { this.killed = true; this._signals.push(sig || 'SIGTERM'); },
+    };
+    const call = { cmd, args, opts: opts || {}, child, _cb: cb, _resolved: false };
+    call.resolve = (stdout = '', stderr = '') => {
+      if (call._resolved) return;
+      call._resolved = true;
+      cb(null, stdout, stderr);
+    };
+    call.fail = (err, stderr = '') => {
+      if (call._resolved) return;
+      call._resolved = true;
+      cb(Object.assign(err || new Error('fail'), { stderr }), '', stderr);
+    };
+    calls.push(call);
+    return child;
+  }
+  return { execFile, calls };
+}
+
+function makeMockAtomicWrite() {
+  const calls = [];
+  function atomicWriteJson(filePath, obj) { calls.push({ filePath, obj }); }
+  return { atomicWriteJson, calls };
+}
+
+function defaults(overrides = {}) {
+  const settingsPath = path.join(mkTmp('codbash-repo-refresh-'), 'settings.json');
+  return {
+    settingsPath,
+    maxConcurrency: 4,
+    fetchTimeoutMs: 60_000,
+    sigkillGraceMs: 2_000,
+    debounceMs: 500,
+    resolveGitRoot: (p) => p, // identity by default
+    existsSync: () => true,
+    ...overrides,
+  };
+}
+
+// ── Tests ─────────────────────────────────────────────────────
+
+test('triggerRefresh transitions idle → fetching → idle on success', async () => {
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), execFile: exec.execFile });
+
+  const before = mgr.getState().repos['/repos/x'];
+  assert.equal(before, undefined);
+
+  const pending = mgr.triggerRefresh('/repos/x');
+  const during = mgr.getState().repos['/repos/x'];
+  assert.equal(during.status, 'fetching');
+  assert.ok(during.startedAt > 0);
+
+  exec.calls[0].resolve('done\n', '');
+  const final = await pending;
+
+  assert.equal(final.status, 'idle');
+  assert.equal(final.lastError, null);
+  assert.ok(final.lastSuccessAt > 0);
+});
+
+test('triggerRefresh single-flight: 2 concurrent calls share the same promise', async () => {
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), execFile: exec.execFile });
+
+  const p1 = mgr.triggerRefresh('/repos/x');
+  const p2 = mgr.triggerRefresh('/repos/x');
+
+  assert.equal(exec.calls.length, 1, 'only one child process should be spawned');
+  assert.equal(p1, p2, 'returned promise must be identical (single-flight)');
+
+  exec.calls[0].resolve();
+  await p1;
+});
+
+test('semaphore caps concurrent fetches at 4; 5th queues until one finishes', async () => {
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({
+    ...defaults(),
+    execFile: exec.execFile,
+    maxConcurrency: 4,
+  });
+
+  const promises = ['a', 'b', 'c', 'd', 'e'].map(k => mgr.triggerRefresh('/repos/' + k));
+  // Let microtasks drain so the manager has a chance to start what it can.
+  await new Promise(r => setImmediate(r));
+
+  assert.equal(exec.calls.length, 4, '5th call must be queued, not started');
+
+  exec.calls[0].resolve();
+  await new Promise(r => setImmediate(r));
+  await new Promise(r => setImmediate(r));
+
+  assert.equal(exec.calls.length, 5, '5th call must start after 1st finishes');
+
+  for (let i = 1; i < exec.calls.length; i++) exec.calls[i].resolve();
+  await Promise.all(promises);
+});
+
+test('60s timeout: child killed (SIGTERM then SIGKILL grace), state=error, inflight cleared', async () => {
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({
+    ...defaults(),
+    execFile: exec.execFile,
+    fetchTimeoutMs: 50,
+    sigkillGraceMs: 30,
+  });
+
+  const p = mgr.triggerRefresh('/repos/x');
+  // Wait past timeout window (50ms) plus SIGKILL grace (30ms) plus slack.
+  await new Promise(r => setTimeout(r, 150));
+
+  // Manager should have killed the child and rejected/resolved with error.
+  const child = exec.calls[0].child;
+  assert.ok(child._signals.includes('SIGTERM'), 'expected SIGTERM');
+  assert.ok(child._signals.includes('SIGKILL'), 'expected SIGKILL after grace');
+
+  // Now invoke callback as the child would after kill — the manager must
+  // already have recorded the timeout state and not double-write it.
+  exec.calls[0].fail(new Error('killed'));
+  const state = await p;
+  assert.equal(state.status, 'error');
+  assert.match(state.lastError || '', /timeout/i);
+
+  // Inflight cleared — a subsequent trigger must spawn a fresh child.
+  const p2 = mgr.triggerRefresh('/repos/x');
+  assert.equal(exec.calls.length, 2);
+  exec.calls[1].resolve();
+  await p2;
+});
+
+test('non-zero exit propagates as state=error with truncated stderr (≤200 chars)', async () => {
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), execFile: exec.execFile });
+
+  const p = mgr.triggerRefresh('/repos/x');
+  const longErr = 'fatal: ' + 'x'.repeat(500);
+  exec.calls[0].fail(Object.assign(new Error('exit 128'), { code: 128 }), longErr);
+  const state = await p;
+
+  assert.equal(state.status, 'error');
+  assert.ok(state.lastError);
+  assert.ok(state.lastError.length <= 200, 'lastError must be truncated to ≤200 chars');
+  assert.ok(state.lastError.includes('fatal:'), 'truncation should keep the head of the message');
+  assert.ok(state.lastErrorAt > 0);
+});
+
+test('corrupt settings file → loadSettings logs warning, sets defaults, file untouched', () => {
+  const dir = mkTmp('codbash-repo-refresh-');
+  const settingsPath = path.join(dir, 'settings.json');
+  fs.writeFileSync(settingsPath, '{ not valid json');
+  const original = fs.readFileSync(settingsPath, 'utf8');
+
+  const warnings = [];
+  const mgr = createRepoRefreshManager({
+    ...defaults(),
+    settingsPath,
+    logger: { warn: (msg) => warnings.push(msg) },
+  });
+
+  const { settings } = mgr.getState();
+  assert.equal(settings.refreshOnStartup, false);
+  assert.deepEqual(settings.perProject, {});
+  assert.ok(warnings.some(w => /refresh.*settings/i.test(w)));
+  assert.equal(fs.readFileSync(settingsPath, 'utf8'), original, 'file must NOT be auto-overwritten');
+});
+
+test('updateSettings round-trips through atomicWriteJson (debounced)', async () => {
+  const exec = makeMockExecFile();
+  const atomic = makeMockAtomicWrite();
+  const mgr = createRepoRefreshManager({
+    ...defaults(),
+    execFile: exec.execFile,
+    atomicWriteJson: atomic.atomicWriteJson,
+    debounceMs: 30,
+  });
+
+  mgr.updateSettings({ refreshOnStartup: true });
+  mgr.updateSettings({ perProject: { '/repos/x': { autoRefreshOnNewChat: true } } });
+
+  // Inside debounce window — no write yet.
+  assert.equal(atomic.calls.length, 0);
+
+  await new Promise(r => setTimeout(r, 60));
+
+  // After debounce — exactly one write, with the merged state.
+  assert.equal(atomic.calls.length, 1, 'debounce must coalesce multiple updates into one write');
+  assert.equal(atomic.calls[0].obj.refreshOnStartup, true);
+  assert.deepEqual(atomic.calls[0].obj.perProject, { '/repos/x': { autoRefreshOnNewChat: true } });
+});
+
+test('gitRoot with spaces is passed as a single argv element', async () => {
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), execFile: exec.execFile });
+  const root = '/repos/My Project (legacy)';
+
+  const p = mgr.triggerRefresh(root);
+  assert.deepEqual(exec.calls[0].args, ['-C', root, 'fetch', '--all', '--prune']);
+  // Critical: the gitRoot is one argv element, not split on whitespace.
+  assert.equal(exec.calls[0].args[1], root);
+
+  exec.calls[0].resolve();
+  await p;
+});
+
+test('initOnStartup triggers only enabled repos and does not block', async () => {
+  const dir = mkTmp('codbash-repo-refresh-');
+  const settingsPath = path.join(dir, 'settings.json');
+  fs.writeFileSync(settingsPath, JSON.stringify({
+    version: 1,
+    refreshOnStartup: true,
+    perProject: {
+      '/repos/a': { autoRefreshOnNewChat: true },
+      '/repos/b': { autoRefreshOnNewChat: true },
+      '/repos/c': { autoRefreshOnNewChat: false },
+    },
+  }));
+
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), settingsPath, execFile: exec.execFile });
+
+  const t0 = Date.now();
+  mgr.initOnStartup();
+  const elapsed = Date.now() - t0;
+  assert.ok(elapsed < 50, `initOnStartup must not block (took ${elapsed}ms)`);
+
+  // Let microtasks drain so triggers fire.
+  await new Promise(r => setImmediate(r));
+
+  const triggered = exec.calls.map(c => c.args[1]).sort();
+  assert.deepEqual(triggered, ['/repos/a', '/repos/b']);
+  assert.equal(exec.calls.find(c => c.args[1] === '/repos/c'), undefined, '/repos/c (disabled) must NOT be triggered');
+
+  for (const c of exec.calls) c.resolve();
+});
+
+test('initOnStartup with refreshOnStartup=false launches nothing', async () => {
+  const dir = mkTmp('codbash-repo-refresh-');
+  const settingsPath = path.join(dir, 'settings.json');
+  fs.writeFileSync(settingsPath, JSON.stringify({
+    version: 1,
+    refreshOnStartup: false,
+    perProject: { '/repos/a': { autoRefreshOnNewChat: true } },
+  }));
+
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), settingsPath, execFile: exec.execFile });
+
+  mgr.initOnStartup();
+  await new Promise(r => setImmediate(r));
+  assert.equal(exec.calls.length, 0);
+});
+
+test('initOnStartup garbage-collects orphan perProject entries', async () => {
+  const dir = mkTmp('codbash-repo-refresh-');
+  const settingsPath = path.join(dir, 'settings.json');
+  fs.writeFileSync(settingsPath, JSON.stringify({
+    version: 1,
+    refreshOnStartup: false,
+    perProject: {
+      '/repos/alive':   { autoRefreshOnNewChat: true },
+      '/repos/deleted': { autoRefreshOnNewChat: true },
+    },
+  }));
+
+  const atomic = makeMockAtomicWrite();
+  const mgr = createRepoRefreshManager({
+    ...defaults(),
+    settingsPath,
+    atomicWriteJson: atomic.atomicWriteJson,
+    debounceMs: 10,
+    // /repos/deleted no longer exists on disk.
+    existsSync: (p) => p === '/repos/alive',
+  });
+
+  mgr.initOnStartup();
+  await new Promise(r => setTimeout(r, 40));
+
+  const finalPerProject = mgr.getState().settings.perProject;
+  assert.ok('/repos/alive' in finalPerProject);
+  assert.ok(!('/repos/deleted' in finalPerProject), 'orphan must be GC-ed');
+  // And the cleanup is persisted.
+  assert.ok(atomic.calls.some(c => c.obj.perProject && !('/repos/deleted' in c.obj.perProject)));
+});
+
+test('waitForRefreshOrTimeout returns timedOut=true when fetch outruns the wait', async () => {
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), execFile: exec.execFile });
+
+  const fetchP = mgr.triggerRefresh('/repos/x');
+  const result = await mgr.waitForRefreshOrTimeout('/repos/x', 30);
+
+  assert.equal(result.timedOut, true);
+  assert.equal(result.state.status, 'fetching');
+
+  // Cleanup — let the fetch finish so the test doesn't leak.
+  exec.calls[0].resolve();
+  await fetchP;
+});
+
+test('lastError redacts https://user:token@host credentials', async () => {
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), execFile: exec.execFile });
+
+  const p = mgr.triggerRefresh('/repos/x');
+  const errMsg = "fatal: Authentication failed for 'https://alice:ghp_secrettoken123@github.com/org/repo.git'";
+  exec.calls[0].fail(Object.assign(new Error('exit 128'), { code: 128 }), errMsg);
+  const state = await p;
+
+  assert.equal(state.status, 'error');
+  assert.ok(state.lastError);
+  assert.ok(!/ghp_secrettoken123/.test(state.lastError), 'token must not appear in lastError');
+  assert.ok(!/alice:/.test(state.lastError), 'username must not appear in lastError');
+  assert.ok(/<redacted>@github\.com/.test(state.lastError), 'should preserve host with <redacted> placeholder');
+});
+
+test('initOnStartup skips perProject entries not in known-roots set', async () => {
+  const dir = mkTmp('codbash-repo-refresh-');
+  const settingsPath = path.join(dir, 'settings.json');
+  fs.writeFileSync(settingsPath, JSON.stringify({
+    version: 1,
+    refreshOnStartup: true,
+    perProject: {
+      '/repos/legit':   { autoRefreshOnNewChat: true },
+      '/repos/injected':{ autoRefreshOnNewChat: true }, // not in known set — must be skipped
+    },
+  }));
+
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({
+    ...defaults(),
+    settingsPath,
+    execFile: exec.execFile,
+    getKnownGitRoots: () => new Set(['/repos/legit']),
+  });
+
+  mgr.initOnStartup();
+  await new Promise(r => setImmediate(r));
+
+  const triggered = exec.calls.map(c => c.args[1]).sort();
+  assert.deepEqual(triggered, ['/repos/legit']);
+  assert.equal(exec.calls.find(c => c.args[1] === '/repos/injected'), undefined,
+    'injected path must NOT be triggered');
+
+  for (const c of exec.calls) c.resolve();
+});
+
+test('setKnownGitRootsProvider wires the gate after construction', async () => {
+  const dir = mkTmp('codbash-repo-refresh-');
+  const settingsPath = path.join(dir, 'settings.json');
+  fs.writeFileSync(settingsPath, JSON.stringify({
+    version: 1,
+    refreshOnStartup: true,
+    perProject: { '/repos/a': { autoRefreshOnNewChat: true } },
+  }));
+
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), settingsPath, execFile: exec.execFile });
+  // No known-roots set yet — wire it in after construction.
+  mgr.setKnownGitRootsProvider(() => new Set(['/repos/a']));
+
+  mgr.initOnStartup();
+  await new Promise(r => setImmediate(r));
+  assert.equal(exec.calls.length, 1);
+  exec.calls[0].resolve();
+});
+
+test('waitForRefreshOrTimeout returns timedOut=false when fetch finishes first', async () => {
+  const exec = makeMockExecFile();
+  const mgr = createRepoRefreshManager({ ...defaults(), execFile: exec.execFile });
+
+  const fetchP = mgr.triggerRefresh('/repos/x');
+  const waitP = mgr.waitForRefreshOrTimeout('/repos/x', 200);
+
+  // Resolve fetch before the wait timeout.
+  setTimeout(() => exec.calls[0].resolve(), 10);
+
+  const result = await waitP;
+  assert.equal(result.timedOut, false);
+  assert.equal(result.state.status, 'idle');
+  await fetchP;
+});