Files
PaperClipAI/server/src/server-info.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

223 lines
6.2 KiB
TypeScript

import { execFileSync } from "node:child_process";
import { existsSync } from "node:fs";
import { dirname, join } from "node:path";
import type { ServerGitInfo, ServerGitLocalChanges, ServerInfoSnapshot } from "@paperclipai/shared";
import { parseBuildCommit, readBuildCommit } from "./build-commit.js";
export type { ServerGitInfo, ServerInfoSnapshot };
type GitCommand = () => string;
type BuildCommitCommand = () => string | null;
const SHORT_SHA_RE = /^[0-9a-f]{7,40}$/i;
function workingDirectoryIsInsideGitCheckout(): boolean {
if (process.env.GIT_DIR) return true;
let directory = process.cwd();
for (;;) {
if (existsSync(join(directory, ".git"))) return true;
const parent = dirname(directory);
if (parent === directory) return false;
directory = parent;
}
}
function defaultGitCommand() {
if (!workingDirectoryIsInsideGitCheckout()) {
throw new Error("The working directory is not inside a Git checkout");
}
return execFileSync(
"git",
["show", "-s", "--format=%H%n%h%n%s%n%cI", "HEAD"],
{
encoding: "utf8",
stdio: ["ignore", "pipe", "ignore"],
timeout: 1500,
},
);
}
function defaultGitStatusCommand() {
return execFileSync(
"git",
["status", "--porcelain=v1", "--untracked-files=normal"],
{
encoding: "utf8",
stdio: ["ignore", "pipe", "ignore"],
timeout: 1500,
},
);
}
function defaultGitBranchCommand() {
return execFileSync(
"git",
["symbolic-ref", "--quiet", "--short", "HEAD"],
{
encoding: "utf8",
stdio: ["ignore", "pipe", "ignore"],
timeout: 1500,
},
);
}
function parseGitLocalChanges(output: string): ServerGitLocalChanges {
let stagedFileCount = 0;
let unstagedFileCount = 0;
let untrackedFileCount = 0;
for (const line of output.split(/\r?\n/)) {
if (!line) continue;
const indexStatus = line[0] ?? " ";
const worktreeStatus = line[1] ?? " ";
if (indexStatus === "?" && worktreeStatus === "?") {
untrackedFileCount += 1;
continue;
}
if (indexStatus !== " " && indexStatus !== "?") stagedFileCount += 1;
if (worktreeStatus !== " " && worktreeStatus !== "?") unstagedFileCount += 1;
}
return {
available: true,
hasLocalChanges: stagedFileCount + unstagedFileCount + untrackedFileCount > 0,
stagedFileCount,
unstagedFileCount,
untrackedFileCount,
};
}
function getGitLocalChanges(gitStatusCommand: GitCommand): ServerGitLocalChanges {
try {
return parseGitLocalChanges(gitStatusCommand());
} catch {
return { available: false, unavailableReason: "git_status_unavailable" };
}
}
function parseGitInfo(
output: string,
branchName: string | null,
localChanges: ServerGitLocalChanges,
): ServerGitInfo {
const [fullSha = "", shortSha = "", subject = "", committedAt = ""] = output
.trimEnd()
.split("\n");
const parsedFullSha = parseBuildCommit(fullSha);
const committedAtTime = Date.parse(committedAt);
if (!parsedFullSha || !SHORT_SHA_RE.test(shortSha)) {
return { available: false, unavailableReason: "invalid_git_metadata" };
}
return {
available: true,
fullSha: parsedFullSha,
shortSha,
branchName,
subject: subject.trim() || "No commit subject",
committedAt: Number.isNaN(committedAtTime) ? null : new Date(committedAtTime).toISOString(),
localChanges,
};
}
function readGitInfo(
gitCommand: GitCommand = defaultGitCommand,
gitStatusCommand: GitCommand = defaultGitStatusCommand,
gitBranchCommand: GitCommand = defaultGitBranchCommand,
buildCommitCommand: BuildCommitCommand = readBuildCommit,
): ServerGitInfo {
try {
const output = gitCommand();
const localChanges = getGitLocalChanges(gitStatusCommand);
let branchName: string | null = null;
try {
branchName = gitBranchCommand().trim() || null;
} catch {
branchName = null;
}
return parseGitInfo(output, branchName, localChanges);
} catch {
const buildCommit = parseBuildCommit(buildCommitCommand());
if (!buildCommit) {
return { available: false, unavailableReason: "git_unavailable" };
}
return {
available: true,
fullSha: buildCommit,
shortSha: buildCommit.slice(0, 7),
branchName: null,
subject: "Source build",
committedAt: null,
localChanges: {
available: false,
unavailableReason: "git_status_unavailable",
},
};
}
}
export function createServerInfoSnapshot(
opts: {
now?: Date;
gitCommand?: GitCommand;
gitStatusCommand?: GitCommand;
gitBranchCommand?: GitCommand;
buildCommitCommand?: BuildCommitCommand;
} = {},
): ServerInfoSnapshot {
return {
processStartedAt: (opts.now ?? new Date()).toISOString(),
git: readGitInfo(
opts.gitCommand,
opts.gitStatusCommand,
opts.gitBranchCommand,
opts.buildCommitCommand,
),
};
}
// processStartedAt is a true boot constant, but the running commit can change
// without the Node process restarting: a managed dev-server restart re-runs the
// code while keeping this module alive, so a commit captured once at boot goes
// stale. Re-read git HEAD on demand, throttled by a short TTL so frequent health
// polls don't spawn git on every request.
const GIT_INFO_CACHE_TTL_MS = 3000;
const processStartedAt = new Date().toISOString();
let gitInfoCache: { value: ServerGitInfo; expiresAt: number } | null = null;
// Lifecycle identity must not run the synchronous Git probes used by diagnostics.
export function getServerProcessStartedAt(): string {
return processStartedAt;
}
export function getServerInfoSnapshot(
opts: {
now?: number;
gitCommand?: GitCommand;
gitStatusCommand?: GitCommand;
gitBranchCommand?: GitCommand;
buildCommitCommand?: BuildCommitCommand;
} = {},
): ServerInfoSnapshot {
const now = opts.now ?? Date.now();
if (!gitInfoCache || now >= gitInfoCache.expiresAt) {
gitInfoCache = {
value: readGitInfo(
opts.gitCommand,
opts.gitStatusCommand,
opts.gitBranchCommand,
opts.buildCommitCommand,
),
expiresAt: now + GIT_INFO_CACHE_TTL_MS,
};
}
return { processStartedAt, git: gitInfoCache.value };
}
export function resetServerInfoCacheForTests(): void {
gitInfoCache = null;
}