fix(git): the fetch timeout reaches the whole tree, a tick covers every session on its folder, and the rest of the review (review)

`execFile` signals the `git` parent only, so a fetch that times out can leave its http helper
still running, and on the interval that repeats every run with nobody watching. `runFetch` now
spawns `detached`, so the fetch and the helper it spawns share one process group, and the kill
is SIGTERM to the negative pid then SIGKILL `FETCH_KILL_ESCALATION_MS` later; the escalation is
not cancelled when the promise settles, because the caller is answered at the timeout while the
group is still dying. The output cap is kept, and the clone's slot queue is not needed here.

The tick is two passes: every enabled local session is collected by folder, a folder is due when
ANY session open on it is due, the folder is probed once for the group, and the run is published
to every session on it. A single pass decided by the order the sessions were read, so [long,
short] published only the short one and the 3600 s session's row never updated again while its
folder was fetched every 30 s.

`gitNonInteractiveEnv` writes BatchMode ssh as a default, not an override: `core.sshCommand` is
read inside the same slot and the same bound as the fetch it serves, and `fetchEnvFor` keeps the
repository's answer when it has one, because that is usually the setup that works on a machine
with several ssh setups. The `accept-new` host key it can write is stated next to the BatchMode
note: a prompt is stopped, a write is not.

The write claim is scoped to the Git panel and to the timer, with cloning and worktree management
named as the writes that happen when the user asked for them, and the zh keys sit with the group
of the UI surface their English string belongs to.

Tests: the process-group test proves the tree by group membership, because the helper is a
grandchild (`git fetch` runs `git remote-http`, which spawns `git-remote-http`) and because the
group is what the negative pid reaches, and it remembers each process once found instead of
re-scanning a group it had already emptied. The non-zero-exit test changed premises: `git fetch
--quiet` in a repository with no remote exits 0 on git 2.47.3, so resolving empty stdout there was
correct, and the case that has to reject is a remote pointing at a path that is not a repository.
The join test asserts after the run and does not await the request before the held run is
released, which would wait on the run the test is holding.
This commit is contained in:
Devvyn committed 2026-10-25 22:31:25 +08:00
1 parent ea4318947b
commit 3411d7f35a
15 files changed
+686 -165

No files matched your search

+1 -1
View File
@@ -236,7 +236,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
**Git status indicator** (`showGitStatus`, per-device, default OFF; `src/git-workspace-status.ts`, `routes/git-status-routes.ts`, `git-status-ui.js`): the bottom-bar indicator and its panel read `GET /api/sessions/:id/git-status` and `/git-diff`, read-only and offline on its own (it never fetches; fetching is the separate path below). ⚠️ git never runs on a repository at or inside a Docker case workspace (walk-up, scan and diff alike, and a cached repository list is re-checked against the CURRENT Docker roots), since a container could plant a clean filter that runs on the host; remote and Docker sessions answer `unsupported`. ⚠️ `git-diff` takes `repo`/`path`/`kind` only as keys matched against the workspace's own repository list (`findWorkspaceRepo()`) and that repository's current status, never as paths. ⚠️ Keep `--no-optional-locks`, `core.fsmonitor=false` and `log.showSignature=false` on every call and `--no-ext-diff --no-textconv` on diffs; clean filters still run, which is why the Docker rule exists. ⚠️ An enclosing repository at `$HOME` or above is ignored (`isUnrelatedAncestor()`), and is identified by one cached `rev-parse` before any full status runs. Everything git supplies renders via `textContent`. Tests: `test/git-workspace-status.test.ts`, `test/routes/git-status-routes.test.ts`, and `test/git-status.browser.test.ts` (browser suite, not in the gate).
**Git fetch** (`src/git-fetch.ts`, `src/git-fetch-scheduler.ts`, `routes/git-status-routes.ts`, the panel's **Fetch** button): `POST /api/sessions/:id/git-fetch` is the ONLY git command Codeman runs that WRITES, and the only one that can run a repository's own hooks (`reference-transaction`, `pre-auto-gc` through the automatic maintenance a fetch triggers, config commands such as `credential.helper`) — which is why it is opt-in and never runs on a timer until the user turns it on. ⚠️ Fetch updates remote-tracking refs only; it must never commit, check out, merge or touch the working tree. ⚠️ It is not as harmless as a read: a fetch holds git's ref lock, so an agent's own `git pull` in the same clone can hit the same `cannot lock ref` — hence one folder is fetched by at most one run at a time (`fetchWorkspaceOnce` joins a run already going), and `FETCH_CONFIG_ARGS` (`-c core.fsmonitor=false -c maintenance.auto=false -c gc.auto=0`) keeps an unattended fetch from starting a gc in a repository the agent is using. ⚠️ `buildFetchArgs()` is `['fetch', '--quiet']` and must stay verb-invariant (`test/git-workspace-status.test.ts`); those `-c` overrides are added by the runner, not by `buildFetchArgs()`. ⚠️ The same Docker rule as above applies BEFORE any git runs (a repository at or inside a Docker case workspace is refused), and remote sessions answer `unsupported`. ⚠️ Keep it non-interactive (`gitNonInteractiveEnv()`: `GIT_TERMINAL_PROMPT=0` + BatchMode ssh) or a fetch hangs on an invisible login prompt, and bounded: `MAX_REPOS`/`MAX_REPOS_LIMIT` (12/50), `MAX_FETCH_OUTPUT_BYTES` (2 MB), the git timeout per spawn, and `FETCH_CONCURRENCY` (4) as ONE `Limiter` shared by the fetches of the whole tick — `createLimiter` keeps its count in the closure, so a limiter that delegated to `mapLimited` per call bounds each call, and 4 folders × 4 repositories would start 16 git processes. ⚠️ One semaphore cannot bound both the folders and the fetches: a folder holding a slot would then wait for a slot its own fetch needs, so the tick bounds its folders with `mapLimited` and hands the shared bound to every run. ⚠️ Failure text reaching a client is control-stripped and credential-redacted (`sanitizeGitOutput`) and the browser writes it with `textContent`. Scheduler semantics: settings are read fresh each tick (`GIT_FETCH_TICK_INTERVAL_MS`, 15 s), a per-session override wins even while the app-wide switch is off, the interval is timed from the run START, state is keyed by FOLDER (sessions sharing one folder are the same clone, so one run serves them all, the schedule is stamped at selection, and every session on a folder is remembered — closing the one that holds the override must not stop the folder's fetching while another session is still open on it), a tick is skipped while the previous one is still going, and a user-chosen folder is probed BOUNDED with the default options before anything runs (rule #516 — `unknown` is never read as `absent`). ⚠️ The two settings (`gitFetchEnabled`, `gitFetchIntervalSeconds`, off/300 by default, clamped 30–3600) are **synced**, not per-device: they must stay out of `displayKeys` and out of the strip destructure in settings-ui.js, or the scheduler reads nobody's value. Per-session state rides `SessionUpdated` (no new SSE event) as `gitFetch`, and the click route publishes its own run with `trigger: 'click'` — the UI's "by click" text depends on it. Tests: `test/git-fetch.test.ts`, `test/git-fetch-scheduler.test.ts`, `test/routes/session-routes-git-fetch-settings.test.ts`, `test/git-fetch-i18n.test.ts`, `test/app-settings-structure.test.ts`, `test/session-options-structure.test.ts`, and the Fetch block of `test/git-status.browser.test.ts` (browser suite, not in the gate).
**Git fetch** (`src/git-fetch.ts`, `src/git-fetch-scheduler.ts`, `routes/git-status-routes.ts`, the panel's **Fetch** button): `POST /api/sessions/:id/git-fetch` is the ONLY git command the Git PANEL runs that WRITES — cloning and worktree management write too, but only when the user asked for them at that moment — and it is the only one that can run later by itself, on a timer, and the only one that can run a repository's own hooks (`reference-transaction`, `pre-auto-gc` through the automatic maintenance a fetch triggers, config commands such as `credential.helper`) — which is why it is opt-in and never runs on a timer until the user turns it on. ⚠️ Fetch updates remote-tracking refs only; it must never commit, check out, merge or touch the working tree. ⚠️ It is not as harmless as a read: a fetch holds git's ref lock, so an agent's own `git pull` in the same clone can hit the same `cannot lock ref` — hence one folder is fetched by at most one run at a time (`fetchWorkspaceOnce` joins a run already going), and `FETCH_CONFIG_ARGS` (`-c core.fsmonitor=false -c maintenance.auto=false -c gc.auto=0`) keeps an unattended fetch from starting a gc in a repository the agent is using. ⚠️ `buildFetchArgs()` is `['fetch', '--quiet']` and must stay verb-invariant (`test/git-fetch.test.ts`); those `-c` overrides are added by the runner, not by `buildFetchArgs()`. ⚠️ The git timeout must reach the whole process TREE, not just the `git` parent: `execFile` signals the parent only, so `runFetch` spawns `detached` and signals the negative pid (SIGTERM, then SIGKILL `FETCH_KILL_ESCALATION_MS` later), and the caller is answered AT the timeout while the group is still dying — that is the point. `test/git-fetch.test.ts` proves it against a local server that never answers, by group membership rather than parentage. A non-zero exit must still reject the way `execFile` would, or a real failure reads as a clean run with no reason. ⚠️ The same Docker rule as above applies BEFORE any git runs (a repository at or inside a Docker case workspace is refused), and remote sessions answer `unsupported`. ⚠️ Keep it non-interactive (`gitNonInteractiveEnv()`: `GIT_TERMINAL_PROMPT=0` + BatchMode ssh) or a fetch hangs on an invisible login prompt — but that BatchMode ssh is a DEFAULT, never an override: `fetchEnvFor` must not overwrite the repository's `core.sshCommand` or the user's own `GIT_SSH_COMMAND` (`readRepoSshCommand` reads it inside the same limiter slot and the same wall-clock bound as the fetch it serves), and `StrictHostKeyChecking=accept-new` writes an unknown host key into `~/.ssh/known_hosts` without asking — BatchMode stops a prompt, not a write. Keep it bounded: `MAX_REPOS`/`MAX_REPOS_LIMIT` (12/50), `MAX_FETCH_OUTPUT_BYTES` (2 MB), the git timeout per spawn, and `FETCH_CONCURRENCY` (4) as ONE `Limiter` shared by the fetches of the whole tick — `createLimiter` keeps its count in the closure, so a limiter that delegated to `mapLimited` per call bounds each call, and 4 folders × 4 repositories would start 16 git processes. ⚠️ One semaphore cannot bound both the folders and the fetches: a folder holding a slot would then wait for a slot its own fetch needs, so the tick bounds its folders with `mapLimited` and hands the shared bound to every run. ⚠️ Failure text reaching a client is control-stripped and credential-redacted (`sanitizeGitOutput`) and the browser writes it with `textContent`. Scheduler semantics: settings are read fresh each tick (`GIT_FETCH_TICK_INTERVAL_MS`, 15 s), a per-session override wins even while the app-wide switch is off, the interval is timed from the run START, state is keyed by FOLDER (sessions sharing one folder are the same clone, so one run serves them all, the schedule is stamped at selection, and every session on a folder is remembered, a folder is due when ANY session open on it is due — so the order the sessions were read cannot decide which interval wins (both orders are tested) — and the folder is probed once for the whole group rather than once per session on it — closing the one that holds the override must not stop the folder's fetching while another session is still open on it), a tick is skipped while the previous one is still going, and a user-chosen folder is probed BOUNDED with the default options before anything runs (rule #516 — `unknown` is never read as `absent`). ⚠️ The two settings (`gitFetchEnabled`, `gitFetchIntervalSeconds`, off/300 by default, clamped 30–3600) are **synced**, not per-device: they must stay out of `displayKeys` and out of the strip destructure in settings-ui.js, or the scheduler reads nobody's value. Per-session state rides `SessionUpdated` (no new SSE event) as `gitFetch`, and the click route publishes the run's trigger, not the request's: `trigger: 'click'` only when the click was the run, because a click that joined a tick already going fetched nothing and cannot report itself as the fetch (`GitFeLine truncated
**Raw file bodies are streamed and range-aware**: `file-raw`, the attachments `/raw` route, `GET /api/download` and the rendered-HTML route `GET /html-view/<cap>/...` share `sendFileBody()`, advertise `Accept-Ranges: bytes` and answer `Range` with `206` + `Content-Range` (single-range, parser in `src/web/http-range.ts`); without it `<video>` cannot seek. The size cap (`MAX_FILE_DOWNLOAD_BYTES`, default 2GB, env `CODEMAN_MAX_DOWNLOAD_BYTES`, `0` = unlimited) is a sanity bound, not memory protection; never reintroduce a whole-file buffer. ⚠️ Bodies go out via `reply.hijack()`, so `sendRawStream` must copy the status onto `reply.raw` by hand or a partial body ships as `200`. ⚠️ Closing the preview must pause and unload media (`_stopFilePreviewMedia`), since a detached `HTMLMediaElement` keeps playing. → [architecture-invariants#raw-file-bodies-streamed-and-range-aware](docs/architecture-invariants.md#raw-file-bodies-streamed-and-range-aware)
+2 -2
View File
@@ -1175,11 +1175,11 @@ Both routes accept two optional query parameters, which the UI sends from its pe
Lists are capped (300 files and 50 commits per repository) while the counts stay exact. A branch with no upstream reports the commits no remote has (`HEAD --not --remotes`); a repository with no remote reports `unpushedCount: 0`, since there is nothing to push to. Concurrent polls of one folder share a single git invocation; `?fresh=1` (what the panel's Refresh button and opening the panel send) skips the short-lived caches, though it still joins a computation already running.
`POST /api/sessions/:id/git-fetch` is the panel's **Fetch** button: one `git fetch --quiet` per repository the panel would show, through the same resolver so the two cannot disagree about which repositories belong to a workspace, with the same `maxRepos` and `timeout` clamps. It is the only git command Codeman runs that writes, and it writes remote-tracking refs only — nothing commits, checks out, merges or touches the working tree. It is not quite as harmless as a read: a fetch holds git's ref lock, so an agent's own `git pull` in the same clone can hit the same `cannot lock ref` while a fetch is running, which is why one folder is fetched by one run at a time. It runs on that click, or on the interval below and never otherwise, and `git fetch` is exactly the command that can run a repository's own hooks (`reference-transaction`, `pre-auto-gc` through the automatic maintenance a fetch triggers, and config commands such as `credential.helper`), which is why nothing runs on a timer until you opt in, and why a repository at or inside a Docker case workspace is refused before any git runs. Remote and Docker sessions answer `state: 'unsupported'` like the status route. Bounded: 4 repositories at a time across the whole run (one shared bound, not one per repository group — a scheduled tick keeps that one bound for all its folders, so 4 folders do not mean 4 × 4, and works at most 4 folders at a time), one spawn per repository with the same per-command timeout, `GIT_TERMINAL_PROMPT=0` plus BatchMode ssh so a repository that needs a login fails fast instead of hanging the request on an invisible prompt — Codeman supplies no credentials, so a repository your own git is already signed in to works because that is your existing setup. A click joins a run already going for the same folder, and the click publishes what it got as the session's `gitFetch` state with `trigger: 'click'` (below), so another tab open on the same folder sees the same run.
`POST /api/sessions/:id/git-fetch` is the panel's **Fetch** button: one `git fetch --quiet` per repository the panel would show, through the same resolver so the two cannot disagree about which repositories belong to a workspace, with the same `maxRepos` and `timeout` clamps. It is the only git command the Git panel runs that writes — cloning and worktree management write too, but only when you asked for them at the moment you asked — and it writes remote-tracking refs only — nothing commits, checks out, merges or touches the working tree. It is not quite as harmless as a read: a fetch holds git's ref lock, so an agent's own `git pull` in the same clone can hit the same `cannot lock ref` while a fetch is running, which is why one folder is fetched by one run at a time. It runs on that click, or on the interval below and never otherwise, and `git fetch` is exactly the command that can run a repository's own hooks (`reference-transaction`, `pre-auto-gc` through the automatic maintenance a fetch triggers, and config commands such as `credential.helper`), which is why nothing runs on a timer until you opt in, and why a repository at or inside a Docker case workspace is refused before any git runs. Remote and Docker sessions answer `state: 'unsupported'` like the status route. Bounded: 4 repositories at a time across the whole run (one shared bound, not one per repository group — a scheduled tick keeps that one bound for all its folders, so 4 folders do not mean 4 × 4, and works at most 4 folders at a time), one spawn per repository with the same per-command timeout, which reaches the whole process group rather than only the `git` parent (a fetch over http spawns helper processes, and a timeout that signals the parent alone can leave one running after the answer goes out), `GIT_TERMINAL_PROMPT=0` plus BatchMode ssh so a repository that needs a login fails fast instead of hanging the request on an invisible prompt — Codeman supplies no credentials, so a repository your own git is already signed in to works because that is your existing setup. That BatchMode ssh is a default, never an override: your own `GIT_SSH_COMMAND` and the repository's `core.sshCommand` are honoured, and ⚠️ the default's `StrictHostKeyChecking=accept-new` records an unknown host key in `~/.ssh/known_hosts` without asking — BatchMode stops a prompt, not a write. A click joins a run already going for the same folder, and the click publishes the trigger of the run it actually did — `click` when the click was the run, `interval` when it joined a tick already going, because a click that fetched nothing cannot report itself as the fetch — as the session's `gitFetch` state (below), so another tab open on the same folder sees the same run.
`data` is `{ state, repos, reposTruncated, repoLimit, fetchedAt }`, `repos[]` each `{ name, path, ok }` and, when it failed, `failure` (`{ code, message, stderr }`: the codes as in the clone failures, plus `NO_REMOTE`). A repository that could not be fetched keeps its row rather than being dropped. The panel shows the result under its list and then re-reads, so `behind` reflects what this fetch brought.
The interval is two **synced** settings in `PUT /api/settings` (`src/git-fetch-scheduler.ts`): `gitFetchEnabled` (default `false`) and `gitFetchIntervalSeconds` (30 to 3600, default 300, the gap between runs timed from the start of a run so a slow repository does not push the next one out). Synced, not per-device, because the server is what acts on them; the scheduler reads them fresh on each 15 s tick, so a change works without a restart. A session can override both, and the override wins even while the app-wide switch is off: `POST /api/sessions/:id/git-fetch-settings` takes `{ "enabled": true | false | null, "intervalSeconds": number | null }` — `null` on a field clears that half so the app value applies again, a field left out of the body leaves the other half as it was — is `400 INVALID_INPUT` for a remote or Docker session, and answers `200` with `{ gitFetchSettings: { enabled, intervalSeconds } }` where `null` means the session follows the app. What the last run did rides the session state as `gitFetch` (`{ ranAt, trigger, state, repos, failed, firstFailure? }`, `trigger` is `click` or `interval`), on the existing `SessionUpdated` event: no new event. Sessions on the same folder share one run and both see its result, the schedule is keyed by folder, and a folder is fetched by at most one run at a time; every session open on a folder is remembered, so closing the one that holds the override does not stop that folder's fetching while another session is still open on it. The tick skips anything its bounded probe does not confirm is a directory, stamps each folder's schedule when it picks it, and does not run a second tick over a selection still going. Remote and Docker sessions are never fetched on a timer, and the Docker rule is re-checked against the CURRENT Docker roots every tick.
The interval is two **synced** settings in `PUT /api/settings` (`src/git-fetch-scheduler.ts`): `gitFetchEnabled` (default `false`) and `gitFetchIntervalSeconds` (30 to 3600, default 300, the gap between runs timed from the start of a run so a slow repository does not push the next one out). Synced, not per-device, because the server is what acts on them; the scheduler reads them fresh on each 15 s tick, so a change works without a restart. A session can override both, and the override wins even while the app-wide switch is off: `POST /api/sessions/:id/git-fetch-settings` takes `{ "enabled": true | false | null, "intervalSeconds": number | null }` — `null` on a field clears that half so the app value applies again, a field left out of the body leaves the other half as it was — is `400 INVALID_INPUT` for a remote or Docker session, and answers `200` with `{ gitFetchSettings: { enabled, intervalSeconds } }` where `null` means the session follows the app. What the last run did rides the session state as `gitFetch` (`{ ranAt, trigger, state, repos, failed, firstFailure? }`, `trigger` is `click` or `interval`), on the existing `SessionUpdated` event: no new event. Sessions on the same folder share one run and both see its result, the schedule is keyed by folder, and a folder is fetched by at most one run at a time; a folder is due when ANY session open on it is due, so the order the sessions were read cannot decide which interval wins, and the folder is probed once for the whole group rather than once per session on it; every session open on a folder is remembered, so closing the one that holds the override does not stop that folder's fetching while another session is still open on it. The tick skips anything its bounded probe does not confirm is a directory, stamps each folder's schedule when it picks it, and does not run a second tick over a selection still going. Remote and Docker sessions are never fetched on a timer, and the Docker rule is re-checked against the CURRENT Docker roots every tick.
## Git worktrees of a case
+8 -4
View File
@@ -89,17 +89,21 @@ bounds the Git window's Fetch button; raise it for repositories on a slow networ
**Git fetch on an interval** (synced, off by default) runs `git fetch` on a timer for the repositories the
Git window lists, so the `behind` number is current without a click, and **Git fetch: how often** (synced,
30 to 3600 seconds, default 300) is the gap between runs for a case with no choice of its own — timed from
30 to 3600 seconds, default 300) is the gap between runs for a session that has no override of its own — timed from
the start of a run, so a slow repository does not push the next one out. These are the only Git settings
that are synced rather than per device, because the server's scheduler is what acts on them: kept per
device, the scheduler would read nobody's number. **Session Options → Git** overrides both the switch and
the interval for one session, and that override wins even while the app switch is off; a session that follows
the app shows the app's values and its rows go inert until you turn **Follow the app setting** off. Nothing is
ever fetched for a Docker or remote (SSH) session, and a repository a container can write to is refused
before any git runs. Sessions open on the same folder share one run. Both default to off because `git fetch`
is the one git command Codeman runs that writes, and the one that can run a repository's own hooks
before any git runs. Sessions open on the same folder share one run, and a folder is fetched when ANY session open on it is due, so the order the sessions were read cannot decide which interval wins. Both default to off because `git fetch`
is the one git command the Git window runs that writes — cloning and worktree management write too, but only
when you asked for them at the moment you asked — and the one that can run a repository's own hooks
(`reference-transaction`, `pre-auto-gc` through the maintenance a fetch triggers, and config commands such as
`credential.helper`).
`credential.helper`), and the one that can run later by itself, on a timer. The ssh it runs is BatchMode so
nothing waits for a login, and that is a default, never an override: your own `GIT_SSH_COMMAND`, or the
repository's `core.sshCommand`, is used when either is set. ⚠️ The default's `StrictHostKeyChecking=accept-new`
records an unknown host key in `~/.ssh/known_hosts` without asking — BatchMode stops a prompt, not a write.
Most default to off. The stock desktop header is system stats, File Viewer, Tiles, and the gear.
**Header Stats Style** picks how the system stats and plan usage are drawn: *Compact*
+9 -5
View File
@@ -254,16 +254,20 @@ Click it for a draggable window, in the style of the File Viewer:
remote (SSH) sessions.
It is read-only apart from that fetch: Codeman never commits, checks out or changes the
repository, and `git fetch` writes remote-tracking refs only — it is the one git command here that
writes, and the one that can run a repository's own hooks (`reference-transaction`, `pre-auto-gc` through the
maintenance a fetch triggers, and config commands such as `credential.helper`), which is why nothing runs on
a timer until you opt in. A fetch holds git's ref lock, so an agent's own `git pull` in the same repository
repository, and `git fetch` writes remote-tracking refs only — it is the only git command the Git window
runs that writes, the only one that can run a repository's own hooks (`reference-transaction`,
`pre-auto-gc` through the maintenance a fetch triggers, and config commands such as `credential.helper`),
and the only one that can run later by itself, on a timer: cloning and worktree management write too, but
only when you asked for them at the moment you asked, which is why nothing runs on a timer until you opt in. A fetch holds git's ref lock, so an agent's own `git pull` in the same repository
can hit the same `cannot lock ref`, and a folder is fetched by one run at a time. It is not shown for Docker
or remote (SSH) sessions, and a repository at or inside a Docker case
workspace is skipped even from a local session, before any git runs (a container can write there,
and git would run that repository's own configuration on the host). Fetch asks nothing of you: it
uses the sign-in your own git already has, and it gives up quickly rather than waiting on an
invisible login prompt. The
invisible login prompt. That BatchMode ssh is a default, never an override: your own
`GIT_SSH_COMMAND`, or the repository's `core.sshCommand`, is used when either is set, and ⚠️ the default's
`StrictHostKeyChecking=accept-new` records an unknown host key in `~/.ssh/known_hosts` without asking —
BatchMode stops a prompt, not a write. The
data comes from `GET /api/sessions/:id/git-status`, `GET /api/sessions/:id/git-diff` and, on that
click or the interval you turned on, `POST /api/sessions/:id/git-fetch`
(see the [API reference](https://github.com/Ark0N/Codeman/blob/master/docs/api-reference.md)).
+55 -31
View File
@@ -2,9 +2,10 @@
* @fileoverview Git fetch on an interval: the cases the user turned on, fetched by a tick the server owns
* (`src/git-fetch-scheduler.ts`, wired in `src/web/server.ts`).
*
* The fetch module (src/git-fetch.ts) is the only place Codeman runs a git command that writes, and on a
* timer it is the only one that can run without being asked — which is why the whole feature is off until
* the user turns it on, in Settings → Bottom bar, per session in Session Options → Git.
* The fetch module (src/git-fetch.ts) is the only git command the Git panel runs that writes, and on a timer
* it is the only one that can run without being asked — cloning and worktree management write too, but those
* happen when the user asks for them. Which is why the whole feature is off until the user turns it on, in
* Settings → Bottom bar, per session in Session Options → Git.
*
* The scheduler holds no timers of its own. The server ticks it (`GIT_FETCH_TICK_INTERVAL_MS`) and every
* tick reads the app setting FRESH, so a live toggle takes effect on the next tick instead of at boot, and
@@ -23,7 +24,10 @@
* its result. State is keyed by `resolve(workingDir)` — deliberately not `realpath`, because `realpath`
* is itself one of the unbounded fs calls rule #516 bounds; the bounded probe below is the fs read.
* Every session open on a folder is remembered, so closing the one holding the override does not stop
* the folder's fetching while another session is still on it.
* the folder's fetching while another session is still on it. A folder is due when ANY session open on it
* is due, and the tick decides that per folder in a second pass: the order the sessions were read cannot
* change which interval wins, so a 30 s session on a folder a 3600 s session last fetched ten minutes ago
* is fetched now. The folder is probed once, not once per session on it.
* - Before anything is fetched, the folder is probed BOUNDED with the default options (rule #516): a case
* on a mount that stopped answering is skipped, never touched, and a probe that answers `unknown` is not
* read as "not a folder".
@@ -55,9 +59,10 @@ import {
MIN_GIT_FETCH_INTERVAL_SECONDS,
gitFetchStatusFrom,
type GitFetchOptions,
type GitFetchReport,
type GitFetchRun,
type GitFetchSettings,
type GitFetchStatus,
type GitFetchTrigger,
} from './git-fetch.js';
import { clampInt, DEFAULT_GIT_TIMEOUT_MS, MAX_REPOS, createLimiter, mapLimited } from './git-workspace-status.js';
import type { PathProbeKind } from './utils/bounded-path-probe.js';
@@ -73,6 +78,12 @@ export interface GitFetchSessionView {
gitFetchIntervalSeconds?: number;
}
/** A session open on a folder, with the interval that makes IT due. One folder's sessions are a group. */
interface GroupMember {
view: GitFetchSessionView;
intervalSeconds: number;
}
export interface GitFetchPorts {
sessionIds(): Iterable<string>;
getSession(id: string): GitFetchSessionView | undefined;
@@ -86,7 +97,7 @@ export interface GitFetchPorts {
*/
probePath(path: string): Promise<PathProbeKind>;
/** Called through `fetchWorkspaceOnce`, so a run already going for this folder is joined, not stacked. */
fetch(cwd: string, opts: GitFetchOptions): Promise<GitFetchReport>;
fetch(cwd: string, opts: GitFetchOptions, trigger: GitFetchTrigger): Promise<GitFetchRun>;
publish(id: string, status: GitFetchStatus): void;
log?(message: string): void;
}
@@ -139,39 +150,45 @@ export class GitFetchScheduler {
return 0;
}
// One entry per folder, holding every session open on it. Stamped here, at selection: a tick that is
// still running must not pick the same folder again, and a folder already being fetched is not picked
// at all.
const due = new Map<string, GitFetchSessionView[]>();
// Pass 1 — who is on what, before anything is decided. Every session open on a folder is recorded here,
// not only the one that would get picked, so `remove()` can still see who is open on it when the session
// holding the override is the one that closes.
const groups = new Map<string, GroupMember[]>();
for (const id of this.ports.sessionIds()) {
const view = this.ports.getSession(id);
if (!view || view.remote || view.docker) continue;
const effective = effectiveGitFetch(view, settings);
if (!effective.enabled) continue;
const folder = resolve(view.workingDir);
// Recorded for EVERY session on the folder, not just the one that got picked, so `remove()` can still
// see who is open on it when the session holding the override is the one that closes.
this.folderOf.set(id, folder);
// A session on a folder this tick already picked is the same clone: it joins that folder's run rather
// than starting its own. Two fetches in one clone collide on git's ref lock, so one run has to serve
// every session open on the folder.
const group = due.get(folder);
if (group) {
group.push(view);
continue;
}
const group = groups.get(folder);
const member = { view, intervalSeconds: effective.intervalSeconds };
if (group) group.push(member);
else groups.set(folder, [member]);
}
// Pass 2 — the folder's turn, decided from the whole group rather than from whichever session happened to
// be read first. A folder is due when ANY session open on it is due: a session on a 30 s interval on a
// folder a 3600 s session last fetched ten minutes ago has to be fetched now, because that same run
// satisfies the long interval too. Deciding in one pass means the session read first owns the clock — a
// group ordered [short, long] and a group ordered [long, short] would have behaved differently, and the
// run belongs to the folder, so no session in the group should.
const due = new Map<string, GroupMember[]>();
for (const [folder, group] of groups) {
if (this.inFlight.has(folder)) continue;
const started = this.lastRunAt.get(folder);
if (started !== undefined && now - started < effective.intervalSeconds * 1000) continue;
const kind = await this.ports.probePath(view.workingDir);
const isDue = started === undefined || group.some((m) => now - started >= m.intervalSeconds * 1000);
if (!isDue) continue;
// Bounded probe (rule #516), once per folder rather than once per session on it.
const kind = await this.ports.probePath(folder);
if (kind !== 'directory') {
this.ports.log?.(`git fetch: ${view.id} skipped, folder answered ${kind}`);
this.ports.log?.(`git fetch: ${folder} skipped, answered ${kind}`);
continue;
}
this.inFlight.add(folder);
// The clock starts at the selection, so a slow folder does not shift its own schedule.
this.lastRunAt.set(folder, now);
due.set(folder, [view]);
due.set(folder, group);
}
if (!due.size) return 0;
@@ -188,13 +205,20 @@ export class GitFetchScheduler {
// processes than the module's ceiling.
await mapLimited([...due.entries()], FETCH_CONCURRENCY, async ([folder, group]) => {
try {
const report = await this.ports.fetch(folder, {
dockerWorkspaces,
maxRepos: MAX_REPOS,
timeoutMs: DEFAULT_GIT_TIMEOUT_MS,
limiter: fetches,
});
for (const view of group) this.ports.publish(view.id, gitFetchStatusFrom(report, 'interval'));
const run = await this.ports.fetch(
folder,
{
dockerWorkspaces,
maxRepos: MAX_REPOS,
timeoutMs: DEFAULT_GIT_TIMEOUT_MS,
limiter: fetches,
},
'interval'
);
// Every session on the folder gets the SAME run, with the trigger of the run that actually happened:
// if this tick joined a run a click had already started, the row has to say it was a click, because
// that is what fetched it.
for (const member of group) this.ports.publish(member.view.id, gitFetchStatusFrom(run.report, run.trigger));
} catch (err) {
// The run that failed keeps its reason in the panel's own row; here only the folder-level failure is
// worth a line, because nothing else would say a scheduled fetch could not run at all.
+204 -26
View File
@@ -4,15 +4,17 @@
* (`src/git-fetch-scheduler.ts`).
*
* The status module (src/git-workspace-status.ts) is deliberately offline: "behind" is as of the last
* fetch, so a number that is stale can only be made current by fetching. This is the one place Codeman
* runs a git command that writes, and on a timer it is also the only one that can run without being asked.
* Nothing here commits, checks out, merges or touches the working tree: `git fetch` updates remote-tracking
* fetch, so a number that is stale can only be made current by fetching. This is the only git command the
* Git panel runs that writes, and the only git command Codeman runs on a timer. Cloning a repository and
* managing worktrees write too, but those are things the user asked for at the moment they asked; this is
* the one that can happen later, by itself. Nothing here commits, checks out, merges or touches the working
* tree: `git fetch` updates remote-tracking
* refs and nothing else, and `FETCH_CONFIG_ARGS` keeps it from starting a gc in a repository an agent is
* already using. It is not harmless in the way a read is: a fetch holds git's ref lock, so an agent's own
* `git pull` in the same clone can collide with it (`cannot lock ref`), which is why one folder is fetched
* by at most one run at a time (`fetchWorkspaceOnce`).
*
* Same split as git-clone.ts: the pure half (`buildFetchArgs`, `describeFetchFailure`,
* Same split as git-clone.ts: the pure half (`buildFetchArgs`, `describeFetchFailure`, `fetchEnvFor`,
* `gitFetchSettingsFrom`, `gitFetchStatusFrom`) holds every decision and tests without spawning, and the IO
* half runs one bounded `git fetch --quiet` per repository.
*
@@ -27,19 +29,31 @@
* - One run per folder at a time: `fetchWorkspaceOnce` joins a run already going for the same folder
* instead of starting a second one, because two fetches in one clone collide on the ref lock.
* - Bounded: the git timeout from Settings → Bottom bar per repository, `MAX_REPOS_LIMIT` repositories at
* most, a hard `timeout` on each spawn, and `FETCH_CONCURRENCY` git processes at a time for the whole
* run — one `Limiter`, shared by the scheduler's tick, not one bound per folder.
* most, a hard wall-clock bound on each spawn, and `FETCH_CONCURRENCY` git processes at a time for the
* whole run — one `Limiter`, shared by the scheduler's tick, not one bound per folder.
* - Non-interactive: `GIT_TERMINAL_PROMPT=0` and BatchMode ssh, so a private repository that needs a
* login fails fast instead of hanging the request on an invisible username prompt. Codeman collects
* no credentials; a repository the user's own git is already signed in to works because that is the
* user's existing setup, so unlike a clone no credential helper is disabled here.
* user's existing setup, so unlike a clone no credential helper is disabled here. That BatchMode ssh is
* a default, never an override: `fetchEnvFor` keeps whatever the repository's `core.sshCommand` or the
* user's own `GIT_SSH_COMMAND` already says, because on a machine with several ssh setups that choice
* is usually the one that works. ⚠️ The default still leaves a record: `StrictHostKeyChecking=accept-new`
* writes an unknown host key into `~/.ssh/known_hosts` without asking — BatchMode stops a prompt, not a
* write.
* - The timeout kills the PROCESS GROUP, not just the `git` parent. A fetch over http spawns
* `git-remote-http` children, and `execFile`'s `timeout` signals the parent only, so the answer can go
* out while a helper is still running — and on a timer that repeats every tick with nobody watching.
* `spawn` with `detached: true` puts the tree in its own group so the escalation (SIGTERM, then SIGKILL
* `FETCH_KILL_ESCALATION_MS` later) reaches the children too, which is why the negative pid is used
* rather than `child.kill()`. Same shape as `runGit` in git-clone.ts, without that module's slot queue:
* fetch is bounded by `FETCH_CONCURRENCY`, not by a clone queue.
* - Failure text reaching a client is control-stripped and credential-redacted (`sanitizeGitOutput`),
* and the browser writes it with `textContent` only.
*
* @module git-fetch
*/
import { execFile } from 'node:child_process';
import { execFile, spawn } from 'node:child_process';
import { basename, relative, resolve } from 'node:path';
import { promisify } from 'node:util';
import { classifyGitFailure, gitNonInteractiveEnv, sanitizeGitOutput, type GitFailureCode } from './git-clone.js';
@@ -63,6 +77,15 @@ const execFileAsync = promisify(execFile);
export const FETCH_CONCURRENCY = 4;
/** A fetch on a busy remote can print a lot; a bound on what we will hold. */
const MAX_FETCH_OUTPUT_BYTES = 2 * 1024 * 1024;
/** git's stderr is kept as a bounded tail (as in git-clone.ts): enough for the reason, not the whole stream. */
const MAX_FETCH_STDERR_BYTES = 8_192;
/** A `git config --get` answer is one line; this is a sanity cap, not an expected size. */
const MAX_SSH_COMMAND_BYTES = 4_096;
/**
* How long the process group gets to answer SIGTERM before the same escalation goes to SIGKILL. Kept as a
* const so a test can say how long it is willing to wait for the group to actually die.
*/
export const FETCH_KILL_ESCALATION_MS = 3_000;
/**
* Config overrides set ahead of the argv, so an unattended fetch cannot do more than move refs: no
@@ -151,15 +174,148 @@ export function describeFetchFailure(err: unknown): FetchFailure {
return failure;
}
/** Fetch is allowed to write refs, so this runner does not carry `--no-optional-locks`: fetch takes a required lock anyway. */
/**
* The environment a fetch gets, as a pure decision so it can be pinned without spawning git.
*
* `gitNonInteractiveEnv` supplies the BatchMode default, and the default is only a default: git reads
* `GIT_SSH_COMMAND` from the environment ahead of the repository's `core.sshCommand`, so setting it would
* override a repository that already chose its own ssh — an alternative host, an identity file, a jump box —
* and break a setup that works today. That is the only case where this module makes an ssh choice on the
* user's behalf, so it is the whole decision here: the caller supplies the value it read, and this decides
* between the user's environment and the repository's own answer.
*/
export function fetchEnvFor(base: NodeJS.ProcessEnv, repoSshCommand: string | null): NodeJS.ProcessEnv {
const env = gitNonInteractiveEnv(base);
// `gitNonInteractiveEnv` only writes the default when the environment had nothing, so this is exactly the
// case where it was a choice rather than a pass-through — and the repository's own answer wins over it.
if (!base.GIT_SSH_COMMAND && repoSshCommand) delete env.GIT_SSH_COMMAND;
return env;
}
/**
* The repository's own `core.sshCommand`, or null. One bounded, read-only `git config --get` per fetch:
* git would honour that config itself if we did not write `GIT_SSH_COMMAND` over it, so honouring it means
* not writing one. `--get` reads local and global config, which is the value git would have used, and no
* hook or filter runs on the way to it.
*
* The read happens inside the same slot and the same wall-clock bound as the fetch it serves, so it cannot
* add a fifth git process or push a fetch past the user's timeout — it spends part of it.
*/
export async function readRepoSshCommand(cwd: string, timeoutMs: number): Promise<string | null> {
try {
const { stdout } = await execFileAsync('git', ['config', '--get', 'core.sshCommand'], {
cwd,
timeout: timeoutMs,
maxBuffer: MAX_SSH_COMMAND_BYTES,
env: gitNonInteractiveEnv(),
});
return stdout.trim() || null;
} catch {
// A repository with no such setting, or a read that could not finish: the default is what git would have
// used anyway, and a fetch must not fail because the check for a config value failed.
return null;
}
}
/**
* Fetch is allowed to write refs, so this runner does not carry `--no-optional-locks`: fetch takes a
* required lock anyway.
*
* `spawn`, not `execFile`, because the bound has to reach the whole tree (see the fileoverview): the
* caller is answered at the timeout, and the SIGTERM → SIGKILL escalation is deliberately NOT cancelled
* when the answer goes out, because the promise is a promise about the answer while the group still has to
* die. That is the difference from `runGit` in git-clone.ts, which disarms the escalation at `finish` and so
* can leave a `git-remote-http` child running after a timed-out call.
*
* The thrown error keeps the shape `describeFetchFailure` reads: `stderr` for the reason, `message` for a
* spawn failure (`spawn git ENOENT` → GIT_MISSING), `killed` and `code` for the timeout. A non-zero exit
* rejects the way `execFile` would — `code` is then the exit code — because resolving it would report a real
* failure as a clean run with an empty reason.
*/
export const runFetch: GitRunner = async (cwd, args, opts) => {
const { stdout } = await execFileAsync('git', [...FETCH_CONFIG_ARGS, ...args], {
cwd,
timeout: opts?.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS,
maxBuffer: MAX_FETCH_OUTPUT_BYTES,
env: gitNonInteractiveEnv(),
const timeoutMs = opts?.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS;
const env = fetchEnvFor(process.env, await readRepoSshCommand(cwd, timeoutMs));
return new Promise<string>((resolve, reject) => {
let child: ReturnType<typeof spawn>;
try {
child = spawn('git', [...FETCH_CONFIG_ARGS, ...args], {
cwd,
env,
stdio: ['ignore', 'pipe', 'pipe'],
detached: true,
});
} catch (err) {
reject(err);
return;
}
let stdout = '';
let stderr = '';
let stdoutBytes = 0;
let timedOut = false;
let settled = false;
let killTimer: NodeJS.Timeout | undefined;
const killTree = (signal: NodeJS.Signals) => {
try {
if (child.pid) process.kill(-child.pid, signal);
} catch {
try {
child.kill(signal);
} catch {
/* already gone */
}
}
};
const fail = (spawnError?: string, exitCode?: number | null) => {
if (settled) return;
settled = true;
// Only the timeout timer is disarmed here. On a timeout the escalation is what the caller is waiting
// for, and cancelling it is the bug this runner exists to fix.
clearTimeout(timeoutTimer);
reject(
Object.assign(new Error(spawnError ?? `Command failed: git ${args.join(' ')}`), {
stderr,
killed: timedOut,
code: timedOut ? 'ETIMEDOUT' : (exitCode ?? undefined),
})
);
};
const timeoutTimer = setTimeout(() => {
timedOut = true;
killTree('SIGTERM');
killTimer = setTimeout(() => killTree('SIGKILL'), FETCH_KILL_ESCALATION_MS);
fail();
}, timeoutMs);
child.stdout?.on('data', (chunk: Buffer) => {
stdoutBytes += chunk.length;
if (stdoutBytes <= MAX_FETCH_OUTPUT_BYTES) stdout += chunk.toString('utf-8');
});
child.stderr?.on('data', (chunk: Buffer) => {
stderr += chunk.toString('utf-8');
if (stderr.length > MAX_FETCH_STDERR_BYTES * 2) stderr = stderr.slice(-MAX_FETCH_STDERR_BYTES);
});
const finish = (code: number | null) => {
if (settled) return;
// execFile's contract, which `describeFetchFailure` depends on: a non-zero exit rejects, so a real
// git failure keeps its reason in `stderr` instead of becoming a green row with an empty one. `null`
// means a signal, reachable only when something outside this runner killed the group — our own timeout
// has already answered by then, and `settled` above is what keeps that answer the answer.
if (code !== 0) return fail(undefined, code);
settled = true;
clearTimeout(timeoutTimer);
if (killTimer) clearTimeout(killTimer);
resolve(stdout);
};
child.on('error', (err) => fail(String(err)));
child.on('close', (code) => finish(code));
});
return stdout;
};
export interface GitFetchEntry {
@@ -191,9 +347,12 @@ export interface GitFetchReport {
* whether the user clicked or the interval fired, because a number the user did not ask for should read
* differently from one they did.
*/
/** What a run was, and why it happened. */
export type GitFetchTrigger = 'click' | 'interval';
export interface GitFetchStatus {
ranAt: number;
trigger: 'click' | 'interval';
trigger: GitFetchTrigger;
/** As in the report: `ok`, or the state that stopped the run. */
state: GitFetchReport['state'];
/** Repositories this run covered. */
@@ -204,7 +363,17 @@ export interface GitFetchStatus {
firstFailure?: { name: string; code: FetchFailureCode };
}
export function gitFetchStatusFrom(report: GitFetchReport, trigger: GitFetchStatus['trigger']): GitFetchStatus {
/**
* One run, with the trigger that caused it. A joiner gets the run already going, so what it reports is that
* run's trigger rather than the one that made it ask: a click that joins an interval run did not fetch
* anything itself, and the row the panel shows has to describe the fetch that actually happened.
*/
export interface GitFetchRun {
report: GitFetchReport;
trigger: GitFetchTrigger;
}
export function gitFetchStatusFrom(report: GitFetchReport, trigger: GitFetchTrigger): GitFetchStatus {
const failed = report.repos.filter((r) => !r.ok);
const status: GitFetchStatus = {
ranAt: report.fetchedAt,
@@ -283,25 +452,34 @@ export async function fetchGitWorkspaceOverview(cwd: string, opts: GitFetchOptio
* Runs already going, keyed by the resolved folder. A request for a folder another run is already working on
* JOINS that run instead of starting a second `git fetch` in the same clone: two fetches there collide on
* git's ref lock (`cannot lock ref 'refs/remotes/origin/main'`), which is what a click during a tick would
* otherwise do. A joiner gets the run already going's answer, including its limits — the point is not to
* fetch twice, not to fetch with the freshest options.
* otherwise do. A joiner gets the run already going's answer, including its limits and its trigger — the point
* is not to fetch twice, not to fetch with the freshest options, and a click that fetched nothing cannot
* report itself as the fetch.
*
* Keyed by `resolve`, not `realpath`, because `realpath` is itself one of the unbounded fs calls rule #516
* bounds for user-chosen paths; the scheduler probes the folder bounded and calls this. Two paths that
* resolve the same are the same folder here; a workspace reached through a symlink resolves to the link, so
* a link and its target can be fetched by two runs — the accepted trade for keeping the probe bounded.
*/
const lane = new Map<string, Promise<GitFetchReport>>();
const lane = new Map<string, Promise<GitFetchRun>>();
export async function fetchWorkspaceOnce(folder: string, opts: GitFetchOptions = {}): Promise<GitFetchReport> {
export async function fetchWorkspaceOnce(
folder: string,
opts: GitFetchOptions = {},
trigger: GitFetchTrigger
): Promise<GitFetchRun> {
const key = resolve(folder);
const going = lane.get(key);
// The joiner is handed the run already going as it is, trigger included: it did not cause that fetch, so it
// must not report itself as having.
if (going) return going;
const run = fetchGitWorkspaceOverview(key, opts).finally(() => {
// Only the run that is still the lane's own: a later run for the same folder must not be dropped by an
// earlier one finishing late.
if (lane.get(key) === run) lane.delete(key);
});
const run: Promise<GitFetchRun> = fetchGitWorkspaceOverview(key, opts)
.then((report) => ({ report, trigger }))
.finally(() => {
// Only the run that is still the lane's own: a later run for the same folder must not be dropped by an
// earlier one finishing late.
if (lane.get(key) === run) lane.delete(key);
});
lane.set(key, run);
return run;
}
+11 -6
View File
@@ -11,8 +11,10 @@
* `GET /api/sessions/:id/git-status` for the active session on a slow poll (and at once when the
* session changes or the window regains focus). The status route is read-only: it never changes the
* repository, so the "behind" number reflects the last `git fetch`, which the panel footer says. Fetching
* happens only when the user clicks Fetch in that window's header (`POST /api/sessions/:id/git-fetch`,
* src/git-fetch.ts): the only git command Codeman runs that writes, and only on that click. Remote (SSH)
* happens when the user clicks Fetch in that window's header (`POST /api/sessions/:id/git-fetch`,
* src/git-fetch.ts), or on the interval when the session is on: this is the only git command the Git panel
* runs that writes, and the only one Codeman runs on a timer — cloning and worktree management write too,
* but only when the user asked for them at that moment. Remote (SSH)
* and Docker sessions answer `unsupported`, show no indicator, and cannot be fetched.
*
* Everything that comes from git (file names, commit subjects, author names) is untrusted text: it is
@@ -269,10 +271,13 @@ Object.assign(CodemanApp.prototype, {
/**
* Fetch, on this click only: one `git fetch --quiet` per repository the panel shows
* (`POST /api/sessions/:id/git-fetch`). It is the only git command Codeman runs that writes, and it
* updates remote-tracking refs only, so an agent working in the same repository is not disturbed. One
* click means one fetch per repository: the button is busy and a second click is ignored while it runs.
* The panel then re-reads, so the "behind" number reflects what this fetch brought.
* (`POST /api/sessions/:id/git-fetch`). It is the only git command the Git panel runs that writes, and the
* only one Codeman runs on a timer, and it updates remote-tracking refs only: nothing here commits or
* touches the working tree, so an agent's own work is left alone — though a fetch does hold git's ref lock,
* so an agent's `git pull` in the same repository can hit the same `cannot lock ref` while it runs. One
* click means one fetch per repository: the button is busy and a second click is ignored while it runs, and
* a click that joins a fetch already running reports that run, not itself. The panel then re-reads, so the
* "behind" number reflects what this fetch brought.
*/
async fetchGitStatusNow() {
const sid = this.activeSessionId || null;
+28 -26
View File
@@ -520,12 +520,13 @@
'Connection tile: offline': '离线',
'Connection tile: queued': '已排队',
'Connection tile: retry': '重连中',
// App Settings → Bottom bar, translated as one group (the Git status rows,
// #543's two included). Keys are the trimmed label text, without the scope tag.
// App Settings → Bottom bar, translated as one group (the Git status rows, #543's two included, and the
// two Git fetch rows, in the order the page lists them). Keys are the trimmed label text, without the
// scope tag. The Session Options → Git strings are in that group's own block further down.
'Bottom bar': '底部栏',
'Git status': 'Git 状态',
"Shows, at the right of the bottom bar, when the active session's repository (or each repository inside its folder, up to two levels down) has uncommitted files or commits that are not pushed. Click it for the list. Read-only apart from Fetch: Codeman never commits or changes the repository, and `git fetch` — the one git command here that writes — runs only when you click Fetch in that window, or on the interval below if you turned it on. Not shown for Docker or remote sessions. Off by default.":
'在底部栏右侧显示当前会话的仓库(或其文件夹内向下两层以内的每个仓库)是否有未提交的文件或未推送的提交。点击可查看列表。除拉取外只读:{name} 从不提交或更改仓库,而拉取(这里唯一会写入的 git 命令)只在您点击该窗口中的拉取按钮时运行,或在您开启了下方的定时后按间隔运行。Docker 和远程会话不显示。默认关闭。',
"Shows, at the right of the bottom bar, when the active session's repository (or each repository inside its folder, up to two levels down) has uncommitted files or commits that are not pushed. Click it for the list. Read-only apart from Fetch: Codeman never commits or changes the repository, and `git fetch` — the only git command the Git window runs that writes, and the only one Codeman runs on a timer (cloning and worktree management write too, but only when you asked for them at the moment you asked) — runs when you click Fetch in that window, or on the interval below if you turned it on. Not shown for Docker or remote sessions. Off by default.":
'在底部栏右侧显示当前会话的仓库(或其文件夹内向下两层以内的每个仓库)是否有未提交的文件或未推送的提交。点击可查看列表。除拉取外只读:{name} 从不提交或更改仓库,而拉取是 Git 窗口运行的唯一会写入的 git 命令,也是 {name} 唯一会按间隔自行运行的命令(克隆和工作树管理也会写入,但只在您当时要求时才运行),它只在您点击该窗口中的拉取按钮时运行,或在您开启了下方的定时后按间隔运行。Docker 和远程会话不显示。默认关闭。',
'Git status: group files by folder': 'Git 状态:按文件夹分组显示文件',
'In the Git window, show changed files under their folders, collapsed until you click a folder. Off lists every file by its full path. On by default.':
'在 Git 窗口中,将更改的文件显示在各自的文件夹下,点击文件夹前保持折叠。关闭时按完整路径列出每个文件。默认开启。',
@@ -535,32 +536,15 @@
'Git status: git timeout': 'Git 状态:git 超时',
'Seconds one git command may run before that repository is reported as unreadable (5 to 120, default 30). Raise it for repositories on a slow network share.':
'单条 git 命令可运行的秒数,超时后该仓库会被报告为无法读取(5 到 120,默认 30)。仓库位于较慢的网络共享上时请调高此值。',
'Fetch git status': '拉取 Git 状态',
'Refresh git status': '刷新 Git 状态',
'Close git status': '关闭 Git 状态',
// Git fetch on an interval (App Settings → Bottom bar, Session Options → Git, and the save toast in
// session-ui.js). 'Status' and 'Git' are not added: the first already has a key, the second stays a
// technical name, and the status row's text is written at runtime.
"Whether Codeman fetches this session's repositories on a timer.": '{name} 是否按间隔拉取此会话的仓库。',
'Git fetch on an interval': 'Git 定时拉取',
'Runs `git fetch` for the repositories the Git window lists on a timer, so the "behind" number is current without a click. Off by default: this is the one git command Codeman runs that writes, and the one that runs a repository\'s own hooks, so nothing runs on a timer until you turn it on. A session can override both the switch and the interval in Session Options → Git.':
'按间隔为 Git 窗口列出的仓库运行拉取,这样“落后”的数字无需点击就是最新的。默认关闭:这是 {name} 运行的唯一会写入的 git 命令,也是唯一会运行仓库自身钩子的命令,所以在您开启之前不会有任何定时运行。会话可以在“会话选项 → Git”中同时覆盖开关和间隔。',
'Runs `git fetch` for the repositories the Git window lists on a timer, so the "behind" number is current without a click. Off by default: this is the only git command the Git panel runs that writes, and the only one Codeman runs on a timer (cloning and worktree management write too, but only when you asked for them at the moment you asked), so nothing runs until you turn it on. A session can override both the switch and the interval in Session Options → Git.':
'按间隔为 Git 窗口列出的仓库运行拉取,这样“落后”的数字无需点击就是最新的。默认关闭:这是 {name} 运行的唯一会写入的 git 命令,也是唯一会按间隔自行运行的命令(克隆和工作树管理也会写入,但只在您当时要求时才运行),所以在您开启之前不会有任何运行。会话可以在“会话选项 → Git”中同时覆盖开关和间隔。',
'Git fetch: how often': 'Git 定时拉取:多久一次',
'Seconds between runs for a session that has no override of its own (30 to 3600, default 300). Only a session that is on — here, or in Session Options → Git — is fetched, and sessions sharing one folder are fetched by one run.':
'没有自己覆盖设置的会话,两次运行之间的秒数(30 到 3600,默认 300)。只有已开启的会话——这里,或在“会话选项 → Git”——才会被拉取,共用一个文件夹的会话由一次运行拉取。',
'Fetch on an interval': '按间隔拉取',
"Fetching is the only git command Codeman runs that writes, and the only one that runs a repository's own hooks, so nothing runs on a timer until you turn it on — here, or in App Settings → Bottom bar. The panel's Fetch button is always just a click.":
'拉取是 {name} 运行的唯一会写入的 git 命令,也是唯一会运行仓库自身钩子的命令,所以在您开启之前(这里,或“应用设置 → 底部栏”)不会有任何定时运行。该窗口中的拉取按钮始终只是一次点击。',
'Follow the app setting': '跟随应用设置',
'Uses the app-wide switch and interval for this session. Switch it off to pick your own.':
'为此会话使用应用级的开关和间隔。关闭它即可自行选择。',
'Fetch this session': '拉取此会话',
"Runs on its own even while the app-wide switch is off: a session that turned itself on means exactly that. Sessions sharing one folder share one run, and each sees that run's result.":
'即使应用级开关关闭也自行运行:一个自己开启的会话正是这个意思。共用一个文件夹的会话共享一次运行,每个会话都会看到该运行的结果。',
'How often': '多久一次',
'30 sec to 1 hr, timed from the start of a run, so a slow repository does not push the next one out.':
'30 秒到 1 小时,从一次运行的开始计时,所以较慢的仓库不会把下一次推远。',
'Git fetch settings saved': 'Git 定时拉取设置已保存',
'Fetch git status': '拉取 Git 状态',
'Refresh git status': '刷新 Git 状态',
'Close git status': '关闭 Git 状态',
Panels: '面板',
Monitor: '监视器',
'Project Insights': '项目洞察',
@@ -857,6 +841,24 @@
Memory: '内存',
GPUs: 'GPU',
// Session Options → Git (the tab's blurb, its group head, its hint and its three rows in index.html, plus
// the save toast session-ui.js raises). 'Status' is not a key here: that row's text is built at runtime
// by updateGitFetchStatus, and 'Git' stays a technical name.
"Whether Codeman fetches this session's repositories on a timer.": '{name} 是否按间隔拉取此会话的仓库。',
'Fetch on an interval': '按间隔拉取',
"Fetching is the only git command the Git panel runs that writes, and the only one Codeman runs on a timer, so nothing runs until you turn it on — here, or in App Settings → Bottom bar. Cloning and worktree management write too, but only when you asked for them at the moment you asked. The panel's Fetch button is always just a click.":
'拉取是 Git 窗口运行的唯一会写入的 git 命令,也是 {name} 唯一会按间隔自行运行的命令,所以在您开启之前(这里,或“应用设置 → 底部栏”)不会有任何运行。克隆和工作树管理也会写入,但只在您当时要求时才运行。该窗口中的拉取按钮始终只是一次点击。',
'Follow the app setting': '跟随应用设置',
'Uses the app-wide switch and interval for this session. Switch it off to pick your own.':
'为此会话使用应用级的开关和间隔。关闭它即可自行选择。',
'Fetch this session': '拉取此会话',
"Runs on its own even while the app-wide switch is off: a session that turned itself on means exactly that. Sessions sharing one folder share one run, and each sees that run's result.":
'即使应用级开关关闭也自行运行:一个自己开启的会话正是这个意思。共用一个文件夹的会话共享一次运行,每个会话都会看到该运行的结果。',
'How often': '多久一次',
'30 sec to 1 hr, timed from the start of a run, so a slow repository does not push the next one out.':
'30 秒到 1 小时,从一次运行的开始计时,所以较慢的仓库不会把下一次推远。',
'Git fetch settings saved': 'Git 定时拉取设置已保存',
// Cron / lifecycle / panels
'Cron Jobs': '定时任务',
'+ New Job': '+ 新建任务',
+3 -3
View File
@@ -1738,7 +1738,7 @@
<div class="set-group">
<div class="set-group-head"><h4>Fetch on an interval</h4></div>
<p class="set-group-hint">Fetching is the only git command Codeman runs that writes, and the only one that runs a repository's own hooks, so nothing runs on a timer until you turn it on &mdash; here, or in App Settings &rarr; Bottom bar. The panel's Fetch button is always just a click.</p>
<p class="set-group-hint">Fetching is the only git command the Git panel runs that writes, and the only one Codeman runs on a timer, so nothing runs until you turn it on &mdash; here, or in App Settings &rarr; Bottom bar. Cloning and worktree management write too, but only when you asked for them at the moment you asked. The panel's Fetch button is always just a click.</p>
<div class="set-group-body">
<!-- Live from the session's own last run (session-ui.js: updateGitFetchStatus), which is the
run its folder got: several sessions on one folder share one run and read the same row. -->
@@ -2252,7 +2252,7 @@
<div class="set-row" data-search="git status uncommitted unpushed commit push indicator bottom bar toolbar">
<div class="set-row-text">
<span class="set-row-label">Git status <span class="set-scope">device</span></span>
<span class="set-row-desc">Shows, at the right of the bottom bar, when the active session's repository (or each repository inside its folder, up to two levels down) has uncommitted files or commits that are not pushed. Click it for the list. Read-only apart from Fetch: Codeman never commits or changes the repository, and `git fetch` — the one git command here that writes — runs only when you click Fetch in that window, or on the interval below if you turned it on. Not shown for Docker or remote sessions. Off by default.</span>
<span class="set-row-desc">Shows, at the right of the bottom bar, when the active session's repository (or each repository inside its folder, up to two levels down) has uncommitted files or commits that are not pushed. Click it for the list. Read-only apart from Fetch: Codeman never commits or changes the repository, and `git fetch` — the only git command the Git window runs that writes, and the only one Codeman runs on a timer (cloning and worktree management write too, but only when you asked for them at the moment you asked) — runs when you click Fetch in that window, or on the interval below if you turned it on. Not shown for Docker or remote sessions. Off by default.</span>
</div>
<label class="switch switch-sm"><input type="checkbox" id="appSettingsShowGitStatus"><span class="slider"></span></label>
</div>
@@ -2280,7 +2280,7 @@
<div class="set-row" data-search="git fetch interval timer behind remote tracking refs poll run automatically">
<div class="set-row-text">
<span class="set-row-label">Git fetch on an interval <span class="set-scope">synced</span></span>
<span class="set-row-desc">Runs `git fetch` for the repositories the Git window lists on a timer, so the "behind" number is current without a click. Off by default: this is the one git command Codeman runs that writes, and the one that runs a repository's own hooks, so nothing runs on a timer until you turn it on. A session can override both the switch and the interval in Session Options → Git.</span>
<span class="set-row-desc">Runs `git fetch` for the repositories the Git window lists on a timer, so the "behind" number is current without a click. Off by default: this is the only git command the Git panel runs that writes, and the only one Codeman runs on a timer (cloning and worktree management write too, but only when you asked for them at the moment you asked), so nothing runs until you turn it on. A session can override both the switch and the interval in Session Options → Git.</span>
</div>
<label class="switch switch-sm"><input type="checkbox" id="appSettingsGitFetchEnabled"><span class="slider"></span></label>
</div>
+18 -14
View File
@@ -132,11 +132,13 @@ export function registerGitStatusRoutes(
// Fetch, and only because the user clicked Fetch in the panel (src/git-fetch.ts): one
// `git fetch --quiet` per repository the panel would show, through the same resolver so the two cannot
// disagree about which repositories belong to the workspace. This is the only git command Codeman runs
// that writes, and it writes remote-tracking refs only — nothing commits, checks out or merges. It is not
// as harmless as a read though: a fetch holds git's ref lock, so an agent's own `git pull` in the same
// clone can collide with it, which is why the run goes through `fetchWorkspaceOnce` — a click while a tick
// is already fetching this folder joins that run instead of starting a second one. It can also run a
// disagree about which repositories belong to the workspace. This is the only git command the Git panel runs
// that writes, and it writes remote-tracking refs only — nothing commits, checks out or merges. Cloning and
// worktree management write too, but those happen when the user asked for them; this route is the one that
// can also run later, on a timer. It is not as harmless as a read though: a fetch holds git's ref lock, so
// an agent's own `git pull` in the same clone can collide with it, which is why the run goes through
// `fetchWorkspaceOnce` — a click while a tick is already fetching this folder joins that run instead of
// starting a second one. It can also run a
// repository's own hooks (`reference-transaction`, `pre-auto-gc` through the maintenance git runs after a
// fetch) and its config commands such as `credential.helper`, so the `FETCH_CONFIG_ARGS` overrides turn
// maintenance and gc off, and a repository a container can write to is refused before any git runs. Remote
@@ -148,16 +150,18 @@ export function registerGitStatusRoutes(
const session = findSessionOrFail(ctx, id, req);
if (session.remote) return { success: true, data: emptyReport('unsupported', { reason: 'remote' }) };
if (session.docker) return { success: true, data: emptyReport('unsupported', { reason: 'docker' }) };
const report = await fetchWorkspaceOnce(session.workingDir, {
git,
...limits,
dockerWorkspaces: await dockerWorkspaces(),
});
const run = await fetchWorkspaceOnce(
session.workingDir,
{ git, ...limits, dockerWorkspaces: await dockerWorkspaces() },
'click'
);
// The response answers the click, and the run is also the session's current truth: what the panel's
// "behind" number is based on. Publishing it is what the api docs say a click does, and what makes a
// second tab open on the same folder see the same run — including a click that joined a tick already
// going, where the row has to say who last fetched.
if (session.setGitFetchStatus(gitFetchStatusFrom(report, 'click'))) persistAndBroadcastSession(ctx, session);
return { success: true, data: report };
// second tab open on the same folder see the same run. The trigger recorded is the RUN's, not this
// request's: a click that joined a tick already going fetched nothing itself, so the row has to name the
// interval as what fetched.
if (session.setGitFetchStatus(gitFetchStatusFrom(run.report, run.trigger)))
persistAndBroadcastSession(ctx, session);
return { success: true, data: run.report };
});
}
+5 -4
View File
@@ -1491,10 +1491,11 @@ export const SettingsUpdateSchema = z
/**
* Git fetch on an interval (src/git-fetch-scheduler.ts): `git fetch` for the repositories the Git panel
* lists, run on a timer instead of only on the panel's Fetch click. SYNCED, default OFF, because the
* server is what runs it: `git fetch` is the only git command Codeman runs that writes, and the only
* one that can run a repository's own hooks (`reference-transaction`, `pre-auto-gc` through the
* automatic maintenance a fetch triggers, config commands such as `credential.helper`), so nothing runs
* on a timer until the user turns this on. Cap in seconds between runs (30 to 3600, default 300). A
* server is what runs it: `git fetch` is the only git command the Git panel runs that writes — cloning
* and worktree management write too, but only when the user asked for them at the moment they asked — and
* the only one that can run later by itself, on a timer, and the only one that can run a repository's own
* hooks (`reference-transaction`, `pre-auto-gc` through the automatic maintenance a fetch triggers, config
* commands such as `credential.helper`), so nothing runs on a timer until the user turns this on. Cap in seconds between runs (30 to 3600, default 300). A
* session can override both in Session Options → Git; `null` there clears the override, and sessions
* sharing one folder are fetched by one run.
*/
+3 -2
View File
@@ -410,8 +410,9 @@ export class WebServer extends EventEmitter {
// never be handed `pastCap`. A folder on a mount that stopped answering is skipped, not fetched.
probePath: (path) => probePathKind(path),
// Through the join, so the tick and the panel's Fetch button are the same run: a click on a folder the
// tick is already fetching joins it rather than starting a second `git fetch` in the same clone.
fetch: (cwd, opts) => fetchWorkspaceOnce(cwd, opts),
// tick is already fetching joins it rather than starting a second `git fetch` in the same clone — and the
// run that gets published is the one that ran, with its own trigger.
fetch: (cwd, opts, trigger) => fetchWorkspaceOnce(cwd, opts, trigger),
publish: (id, status) => {
const session = this.sessions.get(id);
if (!session?.setGitFetchStatus(status)) return;
+71 -12
View File
@@ -5,7 +5,9 @@
*
* The run belongs to the FOLDER, so these tests put two sessions on one folder and expect one fetch that
* both see, and they check the tick's two bounds separately: one shared bound for the fetches of the whole
* tick, and the folders bounded by a bound that cannot be the same semaphore.
* tick, and the folders bounded by a bound that cannot be the same semaphore. A folder is due when ANY session
* open on it is due, so the order the sessions were read cannot decide it — that is checked in both orders.
* A run carries the trigger that caused it, and what is published says the run's, not the tick's.
*
* Port: N/A.
*/
@@ -20,8 +22,10 @@ import {
FETCH_CONCURRENCY,
type GitFetchOptions,
type GitFetchReport,
type GitFetchRun,
type GitFetchSettings,
type GitFetchStatus,
type GitFetchTrigger,
} from '../src/git-fetch.js';
import { DEFAULT_GIT_TIMEOUT_MS, MAX_REPOS } from '../src/git-workspace-status.js';
import type { PathProbeKind } from '../src/utils/bounded-path-probe.js';
@@ -41,11 +45,17 @@ const report = (cwd: string, name: string): GitFetchReport => ({
fetchedAt: Date.now(),
});
/** A run: the report plus the trigger that caused it, which is what the published row has to name. */
const run = (cwd: string, name: string, trigger: GitFetchTrigger = 'interval'): GitFetchRun => ({
report: report(cwd, name),
trigger,
});
type Harness = {
scheduler: GitFetchScheduler;
ports: GitFetchPorts;
/** The folders the tick actually ran, in the order they were picked. */
calls: Array<{ cwd: string; opts: GitFetchOptions }>;
/** The folders the tick actually ran, in the order they were picked, with the trigger the tick passed. */
calls: Array<{ cwd: string; opts: GitFetchOptions; trigger: GitFetchTrigger }>;
published: Array<{ id: string; status: GitFetchStatus }>;
/** Every path the tick probed, in order — the probe has to happen before anything is fetched. */
probed: string[];
@@ -74,7 +84,7 @@ function harness(
sessions: GitFetchSessionView[],
opts: {
settings?: GitFetchSettings;
fetch?: (cwd: string, portOpts: GitFetchOptions) => Promise<GitFetchReport>;
fetch?: (cwd: string, portOpts: GitFetchOptions, trigger: GitFetchTrigger) => Promise<GitFetchRun>;
/** Default: every path answers as a folder, so a test that does not care about the probe stays quiet. */
probe?: (path: string) => Promise<PathProbeKind>;
} = {}
@@ -110,9 +120,9 @@ function harness(
h.probed.push(path);
return opts.probe ? await opts.probe(path) : 'directory';
},
fetch: async (cwd, portOpts) => {
h.calls.push({ cwd, opts: portOpts });
return customFetch ? customFetch(cwd, portOpts) : report(cwd, cwd.slice(3));
fetch: async (cwd, portOpts, trigger) => {
h.calls.push({ cwd, opts: portOpts, trigger });
return customFetch ? customFetch(cwd, portOpts, trigger) : run(cwd, cwd.slice(3), trigger);
},
publish: (id, status) => h.published.push({ id, status }),
};
@@ -245,9 +255,45 @@ describe('one folder, one run', () => {
expect(new Set(h.published.map((p) => p.status.failed)).size).toBe(1);
});
it('is due when ANY session open on the folder is due, in either read order, because the clock belongs to the folder and not to whichever session was read first', async () => {
const short = { ...VIEW('short'), workingDir: '/w/shared', gitFetchIntervalSeconds: 30 };
const long = { ...VIEW('long'), workingDir: '/w/shared', gitFetchIntervalSeconds: 300 };
for (const order of [
[short, long],
[long, short],
]) {
const h = harness(order);
// Nothing has run yet, so both are due and both are published from the one run. The folder is probed
// once, not once per session open on it.
expect(await h.scheduler.tick(0)).toBe(1);
expect(h.probed).toEqual(['/w/shared']);
expect(h.published.map((p) => p.id).sort()).toEqual(['long', 'short']);
// Before the short interval elapses neither is due, and the order they were read in cannot change that.
h.published.length = 0;
expect(await h.scheduler.tick(15_000)).toBe(0);
expect(h.published).toEqual([]);
// The short session is past its own interval, so the folder is fetched — once, for both. The run that
// happens covers the long session's interval too, and both still get it because both are open on the
// folder: publishing only the session that made the folder due would leave the other tab on a stale row.
h.published.length = 0;
expect(await h.scheduler.tick(30_000)).toBe(1);
expect(h.calls.length).toBe(2);
expect(h.published.map((p) => p.id).sort()).toEqual(['long', 'short']);
// The long one's own interval comes round, so the folder is due again.
h.published.length = 0;
expect(await h.scheduler.tick(300_000)).toBe(1);
expect(h.published.map((p) => p.id).sort()).toEqual(['long', 'short']);
}
});
it('does not pick a folder again while its run is going, and does not run a second tick over the same selection', async () => {
const ids = Array.from({ length: FETCH_CONCURRENCY + 2 }, (_, i) => `s${i}`);
const gate = deferred<GitFetchReport>(report('/w/first', 'first'));
const gate = deferred<GitFetchRun>(run('/w/first', 'first'));
const h = harness(
ids.map((id) => VIEW(id)),
{
@@ -266,7 +312,7 @@ describe('one folder, one run', () => {
expect(await h.scheduler.tick(15_000)).toBe(0);
expect(h.calls.length).toBe(picked);
gate.resolve(report('/w/first', 'first'));
gate.resolve(run('/w/first', 'first'));
await first;
// Every folder ran exactly once, and no folder ran twice.
expect(h.calls.length).toBe(ids.length);
@@ -299,7 +345,7 @@ describe('one folder, one run', () => {
fetchesLive--;
});
foldersLive--;
return report(cwd, cwd.slice(3));
return run(cwd, cwd.slice(3));
},
}
);
@@ -310,7 +356,7 @@ describe('one folder, one run', () => {
});
it('times the interval from the START of a run, so a slow repository does not push the next one out', async () => {
const slow = deferred<GitFetchReport>(report('/w/a', 'a'));
const slow = deferred<GitFetchRun>(run('/w/a', 'a'));
const h = harness([VIEW('a')], { settings: { enabled: true, intervalSeconds: 30 }, fetch: () => slow.promise });
const first = h.scheduler.tick(0);
@@ -319,7 +365,7 @@ describe('one folder, one run', () => {
// The run takes 200 s, longer than its own interval. Once it lands, the folder is already past due: the
// next tick runs it again instead of waiting another 30 s from when the slow one finished.
slow.resolve(report('/w/a', 'a'));
slow.resolve(run('/w/a', 'a'));
await first;
expect(await h.scheduler.tick(200_000)).toBe(1);
expect(h.calls.length).toBe(2);
@@ -338,6 +384,19 @@ describe('what a run reports', () => {
]);
});
it('publishes the trigger of the run that actually happened rather than the trigger the tick asked for, because a tick that joined a click did not fetch anything', async () => {
const h = harness([VIEW('a')], {
// The port is `fetchWorkspaceOnce`, so it can hand back a run a click had already started for this
// folder. The tick asked for its own; the row has to name the run.
fetch: (cwd, _opts, trigger) => {
expect(trigger).toBe('interval');
return Promise.resolve({ report: report(cwd, 'a'), trigger: 'click' });
},
});
await h.scheduler.tick(0);
expect(h.published[0].status.trigger).toBe('click');
});
it("reports a failure instead of retrying harder, and keeps the folder's next run at its own interval", async () => {
const h = harness([VIEW('a')], {
settings: { enabled: true, intervalSeconds: 30 },
+231 -28
View File
@@ -1,26 +1,35 @@
/**
* @fileoverview Tests for the Git panel's Fetch button (src/git-fetch.ts): the one git command Codeman
* runs that writes, and the one that can run a repository's own hooks — which is why it is a click, not a
* poll.
* @fileoverview Tests for the Git panel's Fetch button (src/git-fetch.ts): the only git command the Git panel
* runs that writes, and the only one that can run without being asked — which is why it is a click, or an
* interval the user turned on, and why the writing and the hooks it can run are pinned here. Cloning and
* worktree management write too, but they write when the user asked.
*
* Three halves, mirroring the module:
* Four halves, mirroring the module:
*
* 1. The PURE half — the fixed argv, the `-c` overrides the runner adds ahead of it, the failure
* classification, and the two reads the interval scheduler depends on: what the settings say
* (`gitFetchSettingsFrom`) and what a run did (`gitFetchStatusFrom`). No spawning.
* 1. The PURE half — the fixed argv, the `-c` overrides the runner adds ahead of it, the ssh environment the
* runner refuses to override (`fetchEnvFor`), the failure classification, and the two reads the interval
* scheduler depends on: what the settings say (`gitFetchSettingsFrom`) and what a run did
* (`gitFetchStatusFrom`). No spawning.
* 2. The IO half — a REAL git fetching a REAL local bare repo, so that "remote-tracking refs only" is
* proven against git's actual behavior: HEAD, the index and the working tree must be exactly what they
* were while the remote-tracking ref moves. The rest of the half uses an injected runner over real
* repositories on disk, because what is being pinned is WHICH repositories git is allowed to touch.
* 3. The join (`fetchWorkspaceOnce`) — one run per folder at a time, because two fetches in one clone
* collide on git's ref lock, and the bound is ONE limiter shared with the scheduler's tick rather than a
* bound each run gets for itself.
* 3. The process group — a timed-out fetch has to take its `git-remote-http` helper with it, against a
* server that accepts and never answers, so the assertion is about what is still RUNNING after the answer
* went out. A test that only checked the returned error would pass with the old `execFile` runner, which
* signals the parent only.
* 4. The join (`fetchWorkspaceOnce`) — one run per folder at a time, because two fetches in one clone
* collide on git's ref lock, the bound is ONE limiter shared with the scheduler's tick rather than a bound
* each run gets for itself, and the trigger a join reports is the joined run's, not the joiner's.
*
* Port: N/A (no server).
* Port: N/A (no Codeman server). The process-group test listens on its own loopback socket, on a port the OS
* picks, because the point of that test is a remote that never answers.
*/
import { execFileSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { createServer, type AddressInfo } from 'node:http';
import type { Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { basename, join } from 'node:path';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
@@ -28,13 +37,16 @@ import { classifyGitFailure, isGitAvailable } from '../src/git-clone.js';
import {
FETCH_CONCURRENCY,
FETCH_CONFIG_ARGS,
FETCH_KILL_ESCALATION_MS,
buildFetchArgs,
clearGitFetchLane,
describeFetchFailure,
fetchEnvFor,
fetchGitWorkspaceOverview,
fetchWorkspaceOnce,
gitFetchSettingsFrom,
gitFetchStatusFrom,
runFetch,
type GitFetchReport,
} from '../src/git-fetch.js';
import { createLimiter, runGit, type GitRunner } from '../src/git-workspace-status.js';
@@ -212,6 +224,30 @@ describe('FETCH_CONFIG_ARGS', () => {
});
});
describe('fetchEnvFor', () => {
const BASE = { HOME: '/home/t', PATH: '/usr/bin' };
it('writes the BatchMode default when nothing else already answered', () => {
const env = fetchEnvFor(BASE, null);
expect(env.GIT_SSH_COMMAND).toContain('BatchMode=yes');
expect(env.GIT_TERMINAL_PROMPT).toBe('0');
});
it('does not override a repository that already chose its own ssh, because that choice is usually the one that works', () => {
const env = fetchEnvFor(BASE, 'ssh -i /home/t/work_key -o ProxyJump=gw');
// The whole point: nothing is written, so git takes the repository's value from its own config.
expect(env.GIT_SSH_COMMAND).toBeUndefined();
// Honouring the repository's ssh is not the same as letting it prompt, so the rest still applies.
expect(env.GIT_TERMINAL_PROMPT).toBe('0');
expect(env.SSH_ASKPASS_REQUIRE).toBe('never');
});
it("the user's own GIT_SSH_COMMAND still beats the repository's, because that is git's rule and not this module's to second-guess", () => {
const env = fetchEnvFor({ ...BASE, GIT_SSH_COMMAND: 'ssh -i /home/t/personal' }, 'ssh -i /repo/key');
expect(env.GIT_SSH_COMMAND).toBe('ssh -i /home/t/personal');
});
});
// ─── Real git, real local repository ─────────────────────────────────────────
const gitPresent = isGitAvailable();
@@ -385,6 +421,143 @@ describe.skipIf(!gitPresent)('fetchGitWorkspaceOverview (real git)', () => {
});
});
// ─── The whole tree, not just the git parent ─────────────────────────────────
/** One process as /proc reports it. `null` means it is gone, which is what the last assertion is about. */
interface Proc {
pid: number;
comm: string;
ppid: number;
/** The PROCESS GROUP. `detached: true` puts the fetch in its own, so the negative pid reaches the children. */
pgrp: number;
cmdline: string;
}
/**
* Every process on the machine, as /proc reports it — so this half can only run on Linux, and the fields are
* counted from the closing parenthesis because `comm` can hold spaces.
*
* Membership of the GROUP is what is checked, not parentage: a helper that outlives its parent stops being a
* child of this test process, and a test that looked for children would pass for the wrong reason.
*/
function scanProc(): Proc[] {
const out: Proc[] = [];
for (const entry of readdirSync('/proc')) {
if (!/^\d+$/.test(entry)) continue;
const pid = Number(entry);
try {
const stat = readFileSync(join('/proc', entry, 'stat'), 'utf8');
const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
out.push({
pid,
comm: readFileSync(join('/proc', entry, 'comm'), 'utf8').trim(),
ppid: Number(fields[1]),
pgrp: Number(fields[2]),
cmdline: readFileSync(join('/proc', entry, 'cmdline'), 'utf8')
.replace(/\0/g, ' ')
.trim(),
});
} catch {
/* gone between the listing and the read */
}
}
return out;
}
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
describe.skipIf(!gitPresent)('runFetch (the whole tree, not just the git parent)', () => {
it.skipIf(!existsSync('/proc/self/environ'))(
'kills the helper processes too, so nothing is left running after the timeout',
async () => {
const server = createServer(() => {
// Accept and never answer: git's http helper connects, waits, and stays.
});
const sockets = new Set<Socket>();
server.on('connection', (s) => {
sockets.add(s);
s.on('close', () => sockets.delete(s));
});
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
const port = (server.address() as AddressInfo).port;
try {
const repo = initRepo(join(dir, 'hang'), `http://127.0.0.1:${port}/x.git`);
// The handler goes on the moment the promise is made, not when it is read: the timeout fires while the
// tree is still being looked at, and a rejection with nothing listening to it becomes an unhandled
// rejection instead of this test's answer.
const answered = runFetch(repo, buildFetchArgs(), { timeoutMs: 1_500 }).catch((e) => e);
// The tree has to be a tree before the timeout, or nothing is being proven: git itself, and the helper
// it spawns for an http remote. The helper is a grandchild — `git fetch` runs `git remote-http`, which
// spawns `git-remote-http` — so the group, not the parentage, is what proves it. Each process is
// remembered once found rather than re-scanned: after the kill the group is empty, and a test that kept
// looking would report a tree it had already destroyed. The `git config` read the runner does first is
// a `git` too, so the fetch is found by what it was asked to do.
let parent: Proc | null = null;
let helper: Proc | null = null;
for (let i = 0; i < 60 && !(parent && helper); i++) {
const live = scanProc();
parent =
parent ??
live.find((p) => p.comm === 'git' && p.cmdline.includes('fetch') && p.ppid === process.pid) ??
null;
helper =
helper ??
(parent
? live.find((p) => p.pgrp === parent!.pgrp && p.pid !== parent!.pid && p.cmdline.includes('remote-http'))
: null);
if (!helper) await sleep(25);
}
expect(parent, 'the fetch was never running').not.toBeNull();
expect(helper, 'nothing else in the fetch group, so there was no tree to kill').not.toBeNull();
// `detached: true` puts the fetch in a group of its own, which is why the negative pid is the right
// thing to signal: a helper outside that group would survive a `child.kill()`.
expect(parent!.pgrp).toBe(parent!.pid);
expect(helper!.pgrp).toBe(parent!.pgrp);
const err = (await answered) as { code?: string; killed?: boolean };
expect(err.code).toBe('ETIMEDOUT');
expect(err.killed).toBe(true);
// The answer went out before the tree died — that is the whole point of the fix, and it is why the
// escalation is given its own time here instead of being cancelled when the promise settles.
const deadline = Date.now() + FETCH_KILL_ESCALATION_MS + 2_000;
while (Date.now() < deadline && scanProc().some((p) => p.pgrp === parent!.pgrp)) await sleep(50);
expect(scanProc().some((p) => p.pgrp === parent!.pgrp)).toBe(false);
// Nothing of this test's own is left running either.
await sleep(200);
expect(scanProc().filter((p) => p.ppid === process.pid)).toEqual([]);
} finally {
for (const s of sockets) s.destroy();
server.close();
}
}
);
it('rejects on a non-zero exit instead of resolving empty stdout, so a failure keeps a reason to be read', async () => {
// A remote git cannot read. A repository with no remote is not usable for this: `git fetch --quiet` exits 0
// there on the git this was checked against (2.47.3), so resolving empty stdout would have been the right
// answer and the test would prove nothing. A remote pointing at a path that is not a repository exits 128
// and says why, which is the case the row needs a reason for.
const repo = initRepo(join(dir, 'unreadable-remote'), 'file:///tmp/definitely-not-a-repo-xyz');
let err: unknown = null;
try {
await runFetch(repo, buildFetchArgs());
} catch (e) {
err = e;
}
expect(err, 'a fetch that failed resolved instead of rejecting').not.toBeNull();
const e = err as { code?: unknown; stderr?: string; killed?: boolean };
// The exit code, not the timeout marker, so a caller can still tell a failure from a stall.
expect(e.code).toBe(128);
expect(e.killed).toBe(false);
expect(e.stderr).toMatch(/does not appear to be a git repository/);
expect(describeFetchFailure(err).code).toBe('NOT_FOUND');
});
});
// ─── One run per folder, and one bound for the whole tick ────────────────────
describe.skipIf(!gitPresent)('fetchWorkspaceOnce (the join)', () => {
@@ -412,18 +585,17 @@ describe.skipIf(!gitPresent)('fetchWorkspaceOnce (the join)', () => {
}
return '';
};
const first = fetchWorkspaceOnce(folder, { git: firstRunner });
const first = fetchWorkspaceOnce(folder, { git: firstRunner }, 'interval');
await runStarted; // the run is going, and still going
// A click while that run is working the folder: it joins, so it never touches git at all — not even the
// resolver's own probe, because it does not resolve anything for itself.
let joinerCalls = 0;
const joiner = fetchWorkspaceOnce(folder, {
git: async () => {
joinerCalls++;
return '';
},
});
const joinerRunner: GitRunner = async () => {
joinerCalls++;
return '';
};
const joiner = fetchWorkspaceOnce(folder, { git: joinerRunner }, 'click');
releaseRun();
const answer = await first;
@@ -433,6 +605,35 @@ describe.skipIf(!gitPresent)('fetchWorkspaceOnce (the join)', () => {
expect(firstRunFetches).toBe(1);
});
it('a join reports the trigger of the run it joined, not the trigger that made it ask, because a click that fetched nothing cannot claim the fetch', async () => {
const folder = join(dir, 'folder');
initRepo(join(folder, 'api'));
let releaseRun = () => {};
const held = new Promise<void>((resolve) => (releaseRun = resolve));
let running = () => {};
const runStarted = new Promise<void>((resolve) => (running = resolve));
const runner: GitRunner = async (cwd, args) => {
if (args[0] === 'fetch') {
running();
await held;
}
return '';
};
// The tick got there first; the click is the joiner.
const intervalRun = fetchWorkspaceOnce(folder, { git: runner }, 'interval');
await runStarted;
const joinerRun = fetchWorkspaceOnce(folder, { git: async () => '' }, 'click');
releaseRun();
const run = await intervalRun;
expect(await joinerRun).toBe(run); // one run, not two answers
expect(run.trigger).toBe('interval');
// The row the panel shows is built from the run that ran, so it names the interval.
expect(gitFetchStatusFrom(run.report, run.trigger).trigger).toBe('interval');
});
it('keys the join on the resolved folder, so the same folder written two ways is one run', async () => {
const folder = join(dir, 'folder');
initRepo(join(folder, 'api'));
@@ -450,16 +651,15 @@ describe.skipIf(!gitPresent)('fetchWorkspaceOnce (the join)', () => {
}
return '';
};
const first = fetchWorkspaceOnce(folder, { git: firstRunner });
const first = fetchWorkspaceOnce(folder, { git: firstRunner }, 'click');
await runStarted;
// Two sessions on one folder reach it by different spellings; the scheduler keys by `resolve`.
let joinerCalls = 0;
const second = fetchWorkspaceOnce(join(dir, 'folder', '.'), {
git: async () => {
joinerCalls++;
return '';
},
});
const joinerRunner: GitRunner = async () => {
joinerCalls++;
return '';
};
const second = fetchWorkspaceOnce(join(dir, 'folder', '.'), { git: joinerRunner }, 'click');
releaseRun();
expect(await second).toBe(await first);
expect(joinerCalls).toBe(0);
@@ -474,10 +674,13 @@ describe.skipIf(!gitPresent)('fetchWorkspaceOnce (the join)', () => {
if (args[0] === 'fetch') fetches++;
return '';
};
await fetchWorkspaceOnce(folder, { git: runner });
const firstRun = await fetchWorkspaceOnce(folder, { git: runner }, 'interval');
expect(fetches).toBe(1);
await fetchWorkspaceOnce(folder, { git: runner });
const secondRun = await fetchWorkspaceOnce(folder, { git: runner }, 'click');
expect(fetches).toBe(2);
// A run that is its own reports its own trigger; only a joiner borrows the trigger of the run it joined.
expect(firstRun.trigger).toBe('interval');
expect(secondRun.trigger).toBe('click');
});
it('bounds a whole tick with the limiter it is handed, because two runs given a bound each would get twice the bound', async () => {
+37 -1
View File
@@ -11,7 +11,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { createRouteTestHarness } from './_route-test-utils.js';
import { registerGitStatusRoutes } from '../../src/web/routes/git-status-routes.js';
import { clearGitStatusCache, runGit, type GitRunner } from '../../src/git-workspace-status.js';
import { clearGitFetchLane } from '../../src/git-fetch.js';
import { clearGitFetchLane, fetchWorkspaceOnce } from '../../src/git-fetch.js';
const ENV = {
...process.env,
@@ -518,6 +518,42 @@ describe('POST /api/sessions/:id/git-fetch', () => {
expect(b).toEqual(a); // both tabs get the same run's answer, not a partial one
});
it('publishes the trigger of the run the click joined, because a click that fetched nothing cannot report itself as the fetch', async () => {
git(dir, 'init', '-q', '-b', 'main');
let releaseRun = () => {};
const held = new Promise<void>((resolve) => (releaseRun = resolve));
let running = () => {};
const runStarted = new Promise<void>((resolve) => (running = resolve));
const fetches: string[] = [];
const runner: GitRunner = async (cwd, args) => {
if (args[0] === 'fetch') {
fetches.push(cwd);
running();
await held;
}
return execFileSyncGit(cwd, args);
};
const { app, ctx } = await setup({ git: runner });
// The interval tick got to this clone first. The click joins it, so the row the other tabs see has to name
// the interval — the user clicked, but nothing this click did was a fetch. The request is left open, not
// awaited: awaiting it here would wait on the run this test is holding, and the test would wait on itself.
const intervalRun = fetchWorkspaceOnce(dir, { git: runner }, 'interval');
await runStarted;
const res = app.inject({ method: 'POST', url: '/api/sessions/test-session-1/git-fetch' });
await new Promise((resolve) => setImmediate(resolve));
releaseRun();
const run = await intervalRun;
const body = (await res).json().data;
expect(body).toEqual(run.report); // the run it joined, not a partial answer of its own
// Asserted after the run, so this can only pass if the click reached the lane and joined: a click that had
// started its own fetch would make this two, and would have nothing to call the interval.
expect(fetches).toHaveLength(1);
expect(session.gitFetch).toMatchObject({ trigger: 'interval', state: 'ok', repos: 1, failed: 0 });
expect(ctx.broadcast).toHaveBeenCalled();
});
it('404s an unknown session, running no fetch', async () => {
const { calls, fetches, runner } = recordingRunner();
const { app } = await setup({ git: runner });