Files
PaperClipAI/server/src/__tests__/health-server-info-git-probe.test.ts
T
DottaandClaude Fable 5.2 8bdd53c11f perf(server): start no git process for server info outside a checkout (#21122)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The server reports which commit it runs. `GET /api/health` and `GET
/api/liveness` return it, and the board UI and the hosting control plane
poll these routes
> - The commit comes from `getServerInfoSnapshot()` in
`server/src/server-info.ts`. The health route calls it on each request.
The snapshot keeps its Git metadata for 3 seconds, then reads it again
with `execFileSync("git", ["show", ...])`, which is a synchronous child
process
> - A container or packaged install has the `git` command but no
checkout. There `git show` can only fail, and the server then uses the
commit that the build supplied. The failed start still stops the event
loop for the length of a process start
> - A CPU profile of a busy hosted server showed this cost on the main
thread
> - This pull request looks for a checkout before it starts `git`.
Without a checkout the server takes the build-commit path directly
> - The benefit is that health polls start no child process on a server
that does not run from a checkout, and the responses stay the same

## Linked Issues or Issue Description

No public issue exists. I searched open and closed pull requests for
`server-info git health`, `readGitInfo` and `getServerInfoSnapshot`.
Related merged work: #8753 added the 3 second refresh so that the debug
view follows a checkout, #10563 and #10566 added the build commit,
#18649 took the process start time off the Git probes. No open pull
request covers this change.

**What happened?**
`server/src/app.ts` creates the health routes without a `serverInfo`
option, so each `GET /api/health` request calls
`getServerInfoSnapshot()`. When the 3 second cache is expired, the call
starts `git show -s HEAD`. On an install without a checkout the command
fails each time, so the failure is paid again on each refresh. The rate
is one `git` start for each request when requests are 3 seconds or more
apart, and one start for each 3 seconds when requests are more frequent.
It is not one start for each request in a burst.

A 30 second CPU profile of the main thread of a hosted server (commit
1d153f62b6, Node 24, main thread at 93% of one core, process about 4 GB
resident) showed `getServerInfoSnapshot` → `readGitInfo` → the `git
show` command at 0.6% inclusive. That is about 190 ms in 32 seconds,
which agrees with one failed start for each 3 second refresh. The
profile showed only the `git show` command under `readGitInfo`, not the
status or branch commands that run after a successful `git show`. The
native child-process spawn was 0.9% self time in the full profile; other
callers also start processes.

**Expected behavior**
A server that does not run from a Git checkout starts no `git` process
for health or liveness requests. It reports the build commit, as before.
A server that runs from a checkout continues to read Git after each 3
second refresh, because the commit and the local changes of a checkout
can change while the process runs (#8753).

**Steps to reproduce**
1. Run `pnpm --filter @paperclipai/server exec tsx
scripts/benchmark-health-server-info.ts --requests=200` on the parent
commit. The benchmark puts a counting `git` wrapper first on `PATH`. The
wrapper records the start and then runs the real `git`.
2. Read the row `packaged install: no checkout, build supplies the
commit`, pattern `polled every 5000 ms`. It shows 200 `git` execs for
200 health requests, and 1 exec when the routes are created.

**Paperclip version or commit**
`master` at ef2b53b675. The profile is from 1d153f62b6.

**Deployment mode**
All modes. The profile is from an `authenticated` hosted server that
runs the container image. The image installs `git`, and the build
context excludes `.git` (`.dockerignore`).

**Node.js version**
Profile: Node 24. Local benchmark and tests: Node 26.4.0 on darwin
arm64.

## What Changed

- `server/src/server-info.ts`: the default `git show` command first
looks for a checkout. A checkout is a `.git` entry in the working
directory or in one of its parents, or a `GIT_DIR` value. Without one,
the command throws before it starts a process, and `readGitInfo` takes
its existing build-commit path. The same check applies when
`/api/liveness` reads the snapshot at route creation.
- The 3 second refresh, the checkout path, the injected-command path for
tests and `processStartedAt` are not changed.
- `server/src/__tests__/health-server-info-git-probe.test.ts` (new):
regression tests that count the `git` processes that the server starts.
The tests use real Git and real directories.
- `server/scripts/benchmark-health-server-info.ts` (new): the
reproduction and benchmark.
- No route file is changed. `server/src/routes/health.ts` continues to
read the snapshot on each request.

## Verification

Regression test, red then green:

- `cd server && pnpm exec vitest run
src/__tests__/health-server-info-git-probe.test.ts`
- Parent commit (with the test file of this branch): 1 of 4 tests fails.
`starts no git process when the server does not run from a checkout`
fails with `expected 6 to be +0`: one start when the routes are created
and one for each of 5 polls. The response assertions in that test pass
on the parent commit.
- This branch: 4 of 4 tests pass.
- The tests assert the number of `git` starts and the response content.
They do not assert time. The first test compares the full response text
of anonymous health, board health and liveness with the responses of a
server that has the snapshot injected. The other 3 tests pass on both
commits. They keep the checkout behavior: a new commit is visible after
the refresh, also from a subdirectory; a linked worktree (`.git` is a
file) is read; `GIT_DIR` is obeyed.

Benchmark, same machine, 200 health requests per row, 3 runs each
(ranges shown). Each row alternates anonymous and board requests against
routes that are created as `server/src/app.ts` creates them.

| Scenario | Request pattern | Before: `git` execs (route creation +
requests) | Before: ms per request | After: `git` execs | After: ms per
request |
| --- | --- | --- | --- | --- | --- |
| No checkout, build supplies the commit | polled each 5 s | 1 + 200 |
12.5 to 13.8 | 0 + 0 | 1.05 to 1.53 |
| No checkout, build supplies the commit | burst | 1 + 0 | 1.47 to 1.63
| 0 + 0 | 1.19 to 1.57 |
| Source checkout | polled each 5 s | 3 + 600 | 36.3 to 50.2 | 3 + 600 |
36.8 to 40.7 |
| Source checkout | burst | 3 + 0 | 1.38 to 1.40 | 3 + 0 | 1.03 to 1.45
|

- Command: `pnpm --filter @paperclipai/server exec tsx
scripts/benchmark-health-server-info.ts --requests=200`
- The `polled` pattern moves the clock that the server reads forward by
5 seconds before each request. It does not wait for real time.
- The benchmark prints a SHA-256 prefix of the anonymous health body, of
`serverInfo.git` in the board health body and of the liveness body. The
values are the same before and after in all rows.
- The `git` call is synchronous, so the difference per request (about 11
to 12 ms locally, which includes the shell wrapper) is time that the
event loop is blocked.
- The source checkout rows do not change. This is the intended result.

Assumption and evidence (`rules/runtime-dependency-boundaries.mdc`): the
change assumes that real Git fails where the check finds no checkout,
and that the check finds each checkout that Git finds. The first
regression test runs real `git show` in the same directory and asserts
that it fails. The other tests run real Git from a repository
subdirectory, from a linked worktree and with `GIT_DIR`. The new check
itself is a small number of `existsSync` calls (one for each directory
level) on each 3 second refresh.

Other checks:

- `cd server && pnpm exec vitest run src/__tests__/server-info.test.ts
src/__tests__/health.test.ts src/__tests__/liveness.test.ts
src/__tests__/health-dev-server-token.test.ts
src/__tests__/health-workspace-readiness.test.ts
src/__tests__/cloud-warm-standby.test.ts
src/services/native-runtime/native-controller-identity.test.ts` and the
new test file: 58 tests in 8 files pass.
- `tsc --noEmit` over the three changed TypeScript files: clean.
- `pnpm verify` exits 2 (broader verification required, because of the
new file in `server/scripts`). Required CI supplies that coverage.
- Not verified: the benchmark on Linux with a multi-gigabyte process,
and the hosted server after deploy. The local numbers come from a
process of about 700 MB, where a process start is cheaper than on the
profiled server. That the profiled server has no checkout is a
conclusion from the image build and from the profile; I did not read its
`serverInfo` response.

## Risks

- Low risk. The response bodies of `/api/health` and `/api/liveness` are
the same as before for an install without a checkout and for a checkout.
- Behavior shift: a server whose working directory is inside a bare
repository, with no `.git` entry and no `GIT_DIR`, reported the commit
of that repository before. It now reports the build commit, or no
commit. This layout is not a supported way to run the server.
- A server that runs from a source checkout continues to start up to 3
`git` processes on each 3 second refresh while health is polled. This
pull request does not change that path, because #8753 made it read the
checkout live on purpose.
- If a checkout is created around the working directory while the server
runs, the next refresh finds it, because the check runs on each refresh.

## Model Used

- Claude Fable 5.2 (Anthropic, model ID `claude-fable-5-2`), in Claude
Code with tool use (shell, file edits, GitHub CLI).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 09:28:07 -06:00

220 lines
8.7 KiB
TypeScript

import { spawnSync } from "node:child_process";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import express from "express";
import request from "supertest";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { Db } from "@paperclipai/db";
import type { ServerGitInfo } from "@paperclipai/shared";
const BUILD_COMMIT = "0123456789abcdef0123456789abcdef01234567";
const POLL_INTERVAL_MS = 5000;
const serverGit = vi.hoisted(() => ({ execFileSync: vi.fn() }));
vi.mock("node:child_process", async (importOriginal) => {
const actual = await importOriginal<typeof import("node:child_process")>();
serverGit.execFileSync.mockImplementation((...args: unknown[]) =>
(actual.execFileSync as (...values: unknown[]) => unknown)(...args));
return { ...actual, execFileSync: serverGit.execFileSync };
});
const { healthRoutes } = await import("../routes/health.js");
const { livenessRoutes } = await import("../routes/liveness.js");
const { getServerProcessStartedAt, resetServerInfoCacheForTests } = await import("../server-info.js");
const { resetStartupRecoveryStateForTests, setStartupRecoveryPhase } = await import("../startup-recovery-state.js");
type HealthOptions = NonNullable<Parameters<typeof healthRoutes>[1]>;
const healthOptionsAsAppPassesThem: HealthOptions = {
deploymentMode: "authenticated",
deploymentExposure: "private",
authReady: true,
companyDeletionEnabled: false,
isWarmStandby: () => false,
};
function serverGitStarts(): number {
return serverGit.execFileSync.mock.calls.filter(([command]) => command === "git").length;
}
function fixtureGit(cwd: string, ...args: string[]) {
const result = spawnSync("git", args, {
cwd,
encoding: "utf8",
env: {
...process.env,
GIT_CONFIG_GLOBAL: os.devNull,
GIT_CONFIG_SYSTEM: os.devNull,
GIT_AUTHOR_NAME: "Test",
GIT_AUTHOR_EMAIL: "test@example.com",
GIT_COMMITTER_NAME: "Test",
GIT_COMMITTER_EMAIL: "test@example.com",
},
});
return { status: result.status, stdout: result.stdout.trim() };
}
function commit(checkout: string, subject: string): string {
fs.writeFileSync(path.join(checkout, "file.txt"), `${subject}\n`);
expect(fixtureGit(checkout, "add", "file.txt").status).toBe(0);
expect(fixtureGit(checkout, "commit", "--quiet", "--message", subject).status).toBe(0);
return fixtureGit(checkout, "rev-parse", "HEAD").stdout;
}
function createCheckout(): string {
const checkout = path.join(home, "checkout");
fs.mkdirSync(path.join(checkout, "server"), { recursive: true });
expect(fixtureGit(checkout, "init", "--quiet", "--initial-branch=main").status).toBe(0);
return checkout;
}
function stubDatabase(): Db {
const rows = (value: unknown[]) => Object.assign(Promise.resolve(value), { groupBy: () => Promise.resolve([]) });
return {
execute: vi.fn().mockResolvedValue([{ "?column?": 1 }]),
select: () => ({ from: () => ({ where: () => rows([{ count: 1 }]) }) }),
} as unknown as Db;
}
function createServer(serverInfo?: HealthOptions["serverInfo"]) {
const app = express();
app.use((req, _res, next) => {
if (req.get("x-test-actor") === "board") {
(req as unknown as { actor: { type: string } }).actor = { type: "board" };
}
next();
});
app.use("/api/liveness", serverInfo ? livenessRoutes(serverInfo) : livenessRoutes());
app.use("/api/health", healthRoutes(stubDatabase(), { ...healthOptionsAsAppPassesThem, ...(serverInfo ? { serverInfo } : {}) }));
return app;
}
async function pollAfterCacheExpiry(app: express.Express, polls = 1) {
const responses: Array<{ anonymous: string; board: string; liveness: string }> = [];
for (let index = 0; index < polls; index += 1) {
vi.setSystemTime(Date.now() + POLL_INTERVAL_MS);
const anonymous = await request(app).get("/api/health").expect(200);
const board = await request(app).get("/api/health").set("x-test-actor", "board").expect(200);
const liveness = await request(app).get("/api/liveness").expect(200);
responses.push({ anonymous: anonymous.text, board: board.text, liveness: liveness.text });
}
return responses;
}
const originalDirectory = process.cwd();
let home: string;
beforeEach(() => {
home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-health-git-probe-")));
for (const name of Object.keys(process.env)) {
if (name.startsWith("GIT_") || name.startsWith("PAPERCLIP_CLOUD_")) vi.stubEnv(name, undefined);
}
vi.stubEnv("PAPERCLIP_BUILD_COMMIT", undefined);
vi.useFakeTimers({ toFake: ["Date"] });
serverGit.execFileSync.mockClear();
resetServerInfoCacheForTests();
setStartupRecoveryPhase("ready");
});
afterEach(() => {
process.chdir(originalDirectory);
vi.useRealTimers();
vi.unstubAllEnvs();
resetServerInfoCacheForTests();
resetStartupRecoveryStateForTests();
fs.rmSync(home, { recursive: true, force: true });
});
describe("git processes behind health and liveness requests", () => {
it("starts no git process when the server does not run from a checkout", async () => {
const install = path.join(home, "app");
fs.mkdirSync(install);
process.chdir(install);
vi.stubEnv("PAPERCLIP_BUILD_COMMIT", BUILD_COMMIT);
const realGitShowOutsideCheckout = fixtureGit(install, "show", "-s", "--format=%H", "HEAD");
expect(realGitShowOutsideCheckout.status).not.toBe(0);
const buildGitInfo: ServerGitInfo = {
available: true,
fullSha: BUILD_COMMIT,
shortSha: BUILD_COMMIT.slice(0, 7),
branchName: null,
subject: "Source build",
committedAt: null,
localChanges: { available: false, unavailableReason: "git_status_unavailable" },
};
const responses = await pollAfterCacheExpiry(createServer(), 5);
const serverWithInjectedSnapshot = createServer({ processStartedAt: getServerProcessStartedAt(), git: buildGitInfo });
const [reference] = await pollAfterCacheExpiry(serverWithInjectedSnapshot);
for (const response of responses) expect(response).toEqual(reference);
expect(JSON.parse(reference!.anonymous)).toMatchObject({ status: "ok", commit: BUILD_COMMIT });
expect(JSON.parse(reference!.anonymous).serverInfo).toBeUndefined();
expect(JSON.parse(reference!.board).serverInfo).toEqual({
processStartedAt: getServerProcessStartedAt(),
git: buildGitInfo,
});
expect(JSON.parse(reference!.liveness)).toEqual({ status: "ok", commit: BUILD_COMMIT });
expect(serverGitStarts()).toBe(0);
});
it("reads a checkout again after its commit changes, also from a subdirectory", async () => {
const checkout = createCheckout();
const firstCommit = commit(checkout, "First commit");
process.chdir(path.join(checkout, "server"));
const app = createServer();
const [first] = await pollAfterCacheExpiry(app);
expect(JSON.parse(first!.board).serverInfo.git).toMatchObject({
fullSha: firstCommit,
branchName: "main",
subject: "First commit",
localChanges: { available: true, hasLocalChanges: false },
});
const secondCommit = commit(checkout, "Second commit");
const [second] = await pollAfterCacheExpiry(app);
expect(JSON.parse(second!.anonymous).commit).toBe(secondCommit);
expect(JSON.parse(second!.board).serverInfo).toMatchObject({
processStartedAt: getServerProcessStartedAt(),
git: { fullSha: secondCommit, subject: "Second commit" },
});
const commitReadAtRouteCreation = firstCommit;
expect(JSON.parse(second!.liveness)).toEqual({ status: "ok", commit: commitReadAtRouteCreation });
});
it("reads a linked worktree, where .git is a file", async () => {
const checkout = createCheckout();
commit(checkout, "First commit");
const worktree = path.join(home, "worktree");
expect(fixtureGit(checkout, "worktree", "add", "--quiet", "-b", "feature", worktree).status).toBe(0);
const worktreeCommit = commit(worktree, "Worktree commit");
expect(fs.statSync(path.join(worktree, ".git")).isFile()).toBe(true);
process.chdir(worktree);
const [response] = await pollAfterCacheExpiry(createServer());
expect(JSON.parse(response!.board).serverInfo.git).toMatchObject({
fullSha: worktreeCommit,
branchName: "feature",
subject: "Worktree commit",
});
});
it("still asks git when GIT_DIR names a repository outside the working directory", async () => {
const checkout = createCheckout();
const headCommit = commit(checkout, "Commit found through GIT_DIR");
const install = path.join(home, "app");
fs.mkdirSync(install);
process.chdir(install);
vi.stubEnv("GIT_DIR", path.join(checkout, ".git"));
const [response] = await pollAfterCacheExpiry(createServer());
expect(JSON.parse(response!.anonymous).commit).toBe(headCommit);
expect(serverGitStarts()).toBeGreaterThan(0);
});
});