Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

fix(brain): read a repository in a child process so the app keeps answering

anirudhkumar-nanonets270edcccddf7
diff --git a/src/app/brain-build-process.ts b/src/app/brain-build-process.ts
new file mode 100644
index 00000000..501e1993
--- /dev/null
+++ b/src/app/brain-build-process.ts
@@ -0,0 +1,151 @@
+/**
+ * Running a repository read somewhere it cannot stop the App answering.
+ *
+ * The same problem the reviewer had, and the same fix — see review-process.ts
+ * for the full reasoning and the production measurements behind it. In short:
+ * every expensive step of a read is synchronous (git through `spawnSync`, the
+ * parse a loop of native tree-sitter calls, the graph written with a blocking
+ * stringify), so in-process one read holds the event loop for its whole
+ * duration.
+ *
+ * Onboarding made that visible in a way reviews did not. Measured on
+ * NanoNets/assign: 0.7s to check access, 7s to clone, 81s to build the symbol
+ * graph, 21s to walk the pull requests. During those 81 seconds the App
+ * answered nothing at all — including the one-second question "can we see this
+ * other repository", asked by the next person to paste a URL, who then waited
+ * out someone else's clone before being told their repo is private. At a
+ * hundred signups there is nearly always a read in flight, so that is not an
+ * edge case, it is the normal case.
+ *
+ * The split is where the credential is: the parent resolves access and mints
+ * the token (network, never blocking), and the child does the work with it.
+ */
+import { fork, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolveRepoRead, type BrainBuildDeps, type BrainBuildJob, type BrainBuildResult } from "./brain-build.js";
+import type { FromChild, StartMessage } from "./brain-build-worker.js";
+
+/**
+ * How long one read may take before the process running it is killed.
+ *
+ * Well above the worst honest read seen (110s on a large monorepo) plus the
+ * clone budget checkout.ts allows itself, because the cost of being wrong is a
+ * read that never happens. It bounds a lost slot, not responsiveness — the
+ * server stopped caring how long a read takes the moment it left this process.
+ */
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+
+export interface ChildBuilderOptions {
+ /** The module the child runs. Only tests pass this. */
+ entry?: string;
+ timeoutMs?: number;
+}
+
+/**
+ * The module a read runs in. `dist/app/brain-build-worker.js` when installed or
+ * containerised; the TypeScript source next door when run from a checkout,
+ * since `fork` inherits `process.execArgv` and a parent started through tsx
+ * hands the child the same loader.
+ */
+export function brainBuildWorkerEntry(): string {
+ const js = fileURLToPath(new URL("./brain-build-worker.js", import.meta.url));
+ if (existsSync(js)) return js;
+ const ts = js.replace(/\.js$/, ".ts");
+ return existsSync(ts) ? ts : js;
+}
+
+/** Reads in flight, so a shutdown does not leave a clone made with a token. */
+const live = new Set<ChildProcess>();
+let hooked = false;
+
+function track(child: ChildProcess): void {
+ live.add(child);
+ if (hooked) return;
+ hooked = true;
+ process.on("exit", () => {
+ for (const c of live) c.kill("SIGKILL");
+ });
+}
+
+/**
+ * A builder with buildRepoIntoBrain's signature that runs the heavy half in a
+ * child process. Same shape on purpose: server.ts swaps one for the other in a
+ * single line, and a test injecting its own builder keeps running in-process.
+ */
+export function childBuilder(opts: ChildBuilderOptions = {}): (job: BrainBuildJob, deps: BrainBuildDeps) => Promise<BrainBuildResult> {
+ const entry = opts.entry ?? brainBuildWorkerEntry();
+ const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+ return async (job, deps) => {
+ // In the parent, deliberately: it is pure network, it is what decides
+ // whether there is anything to fork for, and a RepoNotAccessibleError has
+ // to reach the caller as itself rather than as a dead child process.
+ const auth = await resolveRepoRead(job, deps);
+ return runInChild(job, deps, auth, entry, timeoutMs);
+ };
+}
+
+async function runInChild(
+ job: BrainBuildJob,
+ deps: BrainBuildDeps,
+ auth: Awaited<ReturnType<typeof resolveRepoRead>>,
+ entry: string,
+ timeoutMs: number,
+): Promise<BrainBuildResult> {
+ const log = deps.log ?? ((): void => {});
+ const tag = `${job.owner}/${job.repo}`;
+ // The repository as argv makes `ps` in a container say which read each
+ // process is; the token stays out of it.
+ const child = fork(entry, [tag], { stdio: ["ignore", "inherit", "inherit", "ipc"] });
+ track(child);
+
+ try {
+ return await new Promise<BrainBuildResult>((resolve, reject) => {
+ let settled = false;
+ const settle = (fn: () => void): void => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ fn();
+ };
+
+ const timer = setTimeout(() => {
+ settle(() => reject(new Error(`read of ${tag} exceeded ${timeoutMs}ms and was killed`)));
+ }, timeoutMs);
+ timer.unref();
+
+ child.on("message", (raw) => {
+ const msg = raw as FromChild;
+ if (msg.t === "log") {
+ log(msg.msg);
+ return;
+ }
+ if (msg.t === "done") {
+ settle(() => resolve(msg.result));
+ return;
+ }
+ settle(() => reject(new Error(msg.message)));
+ });
+
+ child.on("error", (err) => settle(() => reject(err)));
+
+ // The case that used to be an outage: a child that dies without
+ // reporting. An OOM kill on a large repository, a grammar segfault on a
+ // stranger's source. Now it costs one read, named, with the signal.
+ child.on("exit", (code, signal) =>
+ settle(() =>
+ reject(new Error(`read of ${tag} exited ${signal ? `on ${signal}` : `with code ${code}`} before reporting a result`)),
+ ),
+ );
+
+ const start: StartMessage = { t: "start", job, auth, api: deps.api, githubHost: deps.githubHost };
+ if (child.connected) child.send(start);
+ });
+ } finally {
+ live.delete(child);
+ if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+ }
+}
+
+/** The App's default builder. */
+export const buildRepoInChildProcess = childBuilder();
diff --git a/src/app/brain-build-worker.ts b/src/app/brain-build-worker.ts
new file mode 100644
index 00000000..f21dbc19
--- /dev/null
+++ b/src/app/brain-build-worker.ts
@@ -0,0 +1,72 @@
+/**
+ * The process one repository read runs in.
+ *
+ * Forked by brain-build-process.ts, one per read, and it exits when the read
+ * does. It receives the credential it needs rather than the App's private key,
+ * for the same reason the reviewer's worker does: `ps` and `/proc/<pid>/environ`
+ * are readable, and a key that never crosses the boundary cannot leak across it.
+ *
+ * Everything expensive happens here — the clone, the tree-sitter parse, the
+ * pull-request walk — and none of it can reach the server's event loop.
+ */
+import { readRepository, type BrainBuildJob, type RepoReadAuth } from "./brain-build.js";
+
+/** Parent → child, once, immediately after the fork. */
+export interface StartMessage {
+ t: "start";
+ job: BrainBuildJob;
+ auth: RepoReadAuth;
+ api?: string;
+ githubHost?: string;
+}
+
+/** Child → parent: a line for the App's log, so a read is still traceable. */
+export interface LogMessage {
+ t: "log";
+ msg: string;
+}
+
+export interface DoneMessage {
+ t: "done";
+ result: Awaited<ReturnType<typeof readRepository>>;
+}
+
+export interface FailedMessage {
+ t: "failed";
+ message: string;
+}
+
+export type FromChild = LogMessage | DoneMessage | FailedMessage;
+
+function send(msg: FromChild): void {
+ if (!process.send) return;
+ try {
+ process.send(msg);
+ } catch {
+ /* parent went away; the exit is the report */
+ }
+}
+
+process.on("message", (raw) => {
+ const msg = raw as StartMessage;
+ if (msg.t !== "start") return;
+ void readRepository(msg.job, {
+ // No creds: this half needs none. resolveRepoRead already did every call
+ // that requires the App's identity, and its answer is in `auth`.
+ creds: { appId: "", privateKey: "" },
+ fetch: globalThis.fetch,
+ api: msg.api,
+ githubHost: msg.githubHost,
+ log: (line: string) => send({ t: "log", msg: line }),
+ }, msg.auth)
+ .then((result) => {
+ send({ t: "done", result });
+ // The digest can be several megabytes and the channel is asynchronous, so
+ // let the write drain rather than exiting out from under it.
+ process.disconnect?.();
+ })
+ .catch((e: unknown) => {
+ send({ t: "failed", message: e instanceof Error ? e.message : String(e) });
+ process.disconnect?.();
+ });
+});
diff --git a/src/app/brain-build.ts b/src/app/brain-build.ts
index 83c01c30..8b9d1094 100644
--- a/src/app/brain-build.ts
+++ b/src/app/brain-build.ts
@@ -173,17 +173,90 @@ export async function checkRepoAccess(job: { owner: string; repo: string }, deps
* both ways is one we genuinely cannot see, and that is the case the UI turns
* into "read it on your machine".
*/
-export async function buildRepoIntoBrain(
- job: BrainBuildJob,
- deps: BrainBuildDeps,
-): Promise<BrainBuildResult> {
+/** Everything the heavy half needs, and nothing it could mint for itself. */
+export interface RepoReadAuth {
+ /** Installation or public-read token, for the GitHub API calls. */
+ token: string;
+ /** Credential for the clone. Empty for a public repository we are not
+ * installed on: git serves those to anyone, and a token minted for another
+ * account is not promised to work on this one. */
+ cloneToken: string;
+ meta: RepoMeta;
+}
+
+/**
+ * Decide how this repository gets read, and mint the credential for it.
+ *
+ * The network half of a build, kept separate from the work: an installation
+ * lookup, a token, a repository lookup. About a second, none of it blocking.
+ *
+ * Throws RepoNotAccessibleError when there is no way in. That is the answer the
+ * onboarding UI turns into a choice, which is why it is raised here — before a
+ * single byte is cloned — rather than discovered somewhere inside the read.
+ */
+export async function resolveRepoRead(job: BrainBuildJob, deps: BrainBuildDeps): Promise<RepoReadAuth> {
+ const api = deps.api ?? "https://api.github.com";
+ const tag = `${job.owner}/${job.repo}`;
+ const installationId = await installationFor(deps.creds, job.owner, job.repo, deps.fetch, (deps.now ?? Date.now)(), api);
+ if (installationId !== null) {
+ const token = await installationToken(deps, installationId, tag, api);
+ const meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);
+ return { token, cloneToken: token, meta: meta ?? { isPrivate: true, defaultBranch: "" } };
+ }
+
+ // No installation on this repository. That rules out nothing yet: a public
+ // repo clones with no credential at all, and its API answers to any token we
+ // hold. So find a credential for the reading, then ask whether it is public.
+ const token = await publicReadToken(deps, api);
+ const meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);
+ if (!meta || meta.isPrivate) {
+ // Which of the two gaps it is decides what the UI can offer, so it is
+ // resolved here rather than guessed there.
+ const gap = await repoAccessGap(deps.creds, job.owner, deps.fetch, (deps.now ?? Date.now)(), api);
+ throw new RepoNotAccessibleError(
+ gap.reason === "repo_not_selected"
+ ? `graft is installed on ${job.owner} but ${tag} is not in the list of repositories it can see`
+ : `graft is not installed on ${job.owner}`,
+ gap,
+ );
+ }
+ return { token, cloneToken: "", meta };
+}
+
+/**
+ * Read the repository and hand its history to the brain.
+ *
+ * An installation is the preferred way in: it is the only way into a private
+ * repository, and it carries a rate limit worth having. It is not required for
+ * a public one, though — those clone anonymously and answer the API
+ * anonymously — so a failed installation lookup is a reason to try the open
+ * door, not a reason to stop. Only a repository that is private or unreadable
+ * both ways is one we genuinely cannot see, and that is the case the UI turns
+ * into "read it on your machine".
+ */
+export async function buildRepoIntoBrain(job: BrainBuildJob, deps: BrainBuildDeps): Promise<BrainBuildResult> {
+ return readRepository(job, deps, await resolveRepoRead(job, deps));
+}
+
+/**
+ * The heavy half: clone, graph, history, digest.
+ *
+ * Takes its credential rather than minting one, because this is the half that
+ * runs somewhere else. Every expensive thing in it is synchronous — the git
+ * calls are spawnSync, the parse is a loop of native tree-sitter calls, the
+ * graph is written with a blocking stringify — so in the server process it
+ * holds the event loop for the whole read, and a second person pasting a URL
+ * waits behind the first. See brain-build-process.ts.
+ */
+export async function readRepository(job: BrainBuildJob, deps: BrainBuildDeps, auth: RepoReadAuth): Promise<BrainBuildResult> {
const rawLog = deps.log ?? ((): void => {});
const api = deps.api ?? "https://api.github.com";
const tag = `${job.owner}/${job.repo}`;
+ const { token, cloneToken, meta } = auth;
// Every line carries how long we have been at it. A read that feels slow is
- // four things in a trench coat — the access check, the clone, the graph
- // build, the pull-request walk — and without the elapsed time on each, the
+ // four things in a trench coat — the clone, the graph build, the
+ // pull-request walk, the digest — and without the elapsed time on each, the
// only observation anyone can make is "it took two minutes".
const startedAt = (deps.now ?? Date.now)();
const log = (msg: string): void => rawLog(`[+${(((deps.now ?? Date.now)() - startedAt) / 1000).toFixed(1)}s] ${msg}`);
@@ -192,59 +265,12 @@ export async function buildRepoIntoBrain(
return () => log(`${tag}: ${name} took ${(((deps.now ?? Date.now)() - at) / 1000).toFixed(1)}s`);
};
- const doneAccess = phase("access check");
-
- const installationId = await installationFor(
- deps.creds,
- job.owner,
- job.repo,
- deps.fetch,
- (deps.now ?? Date.now)(),
- api,
- );
- // Whether the repository is private decides what the UI may show before
- // signup, and the default branch is not discoverable from a shallow
- // single-ref fetch (there is no origin/HEAD to resolve), so both are read
- // from the API rather than guessed.
- let token = "";
- let cloneToken: string | null = null;
- let meta: RepoMeta | null = null;
- if (installationId !== null) {
- token = await installationToken(deps, installationId, tag, api);
- meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);
- } else {
- // No installation on this repository. That rules out nothing yet: a public
- // repo clones with no credential at all, and its API answers to any token
- // we hold. So find a credential for the reading, then ask the repo whether
- // it is in fact public.
- token = await publicReadToken(deps, api);
- meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);
- if (!meta || meta.isPrivate) {
- // Which of the two gaps it is decides what the UI can offer, so it is
- // resolved here rather than guessed there.
- const gap = await repoAccessGap(deps.creds, job.owner, deps.fetch, (deps.now ?? Date.now)(), api);
- throw new RepoNotAccessibleError(
- gap.reason === "repo_not_selected"
- ? `graft is installed on ${job.owner} but ${tag} is not in the list of repositories it can see`
- : `graft is not installed on ${job.owner}`,
- gap,
- );
- }
- log(`${tag}: no installation, reading it as a public repository${token ? "" : " anonymously"}`);
- // The clone is the one part that stays anonymous. A public repository
- // serves it to anyone, and a token minted for a different account is not
- // something git is promised to accept on this one.
- cloneToken = "";
- }
- if (!meta) meta = { isPrivate: true, defaultBranch: "" };
- doneAccess();
-
const doneClone = phase("clone");
const checkout = checkoutRepository({
owner: job.owner,
repo: job.repo,
ref: job.ref || meta.defaultBranch,
- token: cloneToken ?? token,
+ token: cloneToken,
api: deps.githubHost,
log,
});
diff --git a/src/app/server.ts b/src/app/server.ts
index c1bc1ad7..b23553bf 100644
--- a/src/app/server.ts
+++ b/src/app/server.ts
@@ -21,6 +21,7 @@ import { timingSafeEqual } from "node:crypto";
import { jobKey, reviewJobFor, type ReviewJob } from "./events.js";
import { InstallationTokens, verifySignature, type AppCredentials, type Fetch } from "./identity.js";
import { buildRepoIntoBrain, checkRepoAccess, RepoNotAccessibleError, type BrainBuildJob } from "./brain-build.js";
+import { buildRepoInChildProcess } from "./brain-build-process.js";
import { PageStore } from "./pages.js";
import { WorkQueue } from "./queue.js";
import { reviewInChildProcess } from "./review-process.js";
@@ -223,7 +224,12 @@ export function createApp(
// The deployment's platform URL wins over anything a caller sends, so a
// request cannot redirect a repository's history to another host.
if (config.brainBaseUrl) job.brainBaseUrl = config.brainBaseUrl;
- const built = await (seams.brainBuild ?? buildRepoIntoBrain)(job, {
+ // Out of this process by default. A read is minutes of blocking work
+ // and the App has to keep answering — including the one-second access
+ // question the next person's onboarding is waiting on. A test that
+ // injects its own builder still runs in-process, which is what a test
+ // wants.
+ const built = await (seams.brainBuild ?? buildRepoInChildProcess)(job, {
creds: config,
fetch: fetchImpl,
api: config.api,
diff --git a/test/app-brain-build-process.test.ts b/test/app-brain-build-process.test.ts
new file mode 100644
index 00000000..16b21122
--- /dev/null
+++ b/test/app-brain-build-process.test.ts
@@ -0,0 +1,39 @@
+/**
+ * The one failure in forking a read that no protocol test would catch: the
+ * entry path being wrong, or the read stack failing to load in a child.
+ *
+ * Everything else about the child protocol is the reviewer's, tested next door
+ * in app-review-process.test.ts. What is specific here is that a deployed App
+ * forks THIS module, and that importing it pulls in the same nine tree-sitter
+ * native addons at graph/extract.ts's module scope. A grammar that cannot load
+ * in a forked child dies during import — silently, at runtime, on every read.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { fork } from "node:child_process";
+import { brainBuildWorkerEntry } from "../src/app/brain-build-process.js";
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+test("the brain build worker is where a deployed App looks for it, and it comes up", async () => {
+ const entry = brainBuildWorkerEntry();
+ assert.ok(existsSync(entry), `${entry} must exist — it is what a deployed App forks`);
+
+ const child = fork(entry, ["load-probe"], { stdio: ["ignore", "pipe", "pipe", "ipc"] });
+ let stderr = "";
+ child.stderr?.on("data", (c) => {
+ stderr += String(c);
+ });
+ const ended = new Promise<string>((resolve) => {
+ child.on("exit", (code, signal) => resolve(signal ? `signal ${signal}` : `code ${code}`));
+ });
+ try {
+ // No read runs — a read wants a clone and a token. Still waiting for work
+ // after this long means the stack imported cleanly, which is the assertion.
+ const outcome = await Promise.race([ended, sleep(2500).then(() => "still waiting for work")]);
+ assert.equal(outcome, "still waiting for work", `the brain build worker did not come up: ${stderr}`);
+ } finally {
+ child.kill("SIGKILL");
+ }
+});