@skydiveai/git-cache 0.1.0-beta.1480

package/dist/server-B5u5DETT.mjs

@@ -0,0 +1,1829 @@
+import http from "node:http";
+import https from "node:https";
+import { createHmac, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { mkdir, readFile, readdir, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import path from "node:path";
+import { createGunzip, gunzip } from "node:zlib";
+import { promisify } from "node:util";
+//#region src/server.ts
+/**
+* Sandbox-local Git smart-HTTP cache.
+*
+* NOT a hosted git proxy or remote: this is a loopback-only daemon that runs
+* on the same machine as the git clients it serves, and accelerates
+* clone/fetch of any HTTPS git repo by keeping a local mirror. Different
+* machine, different layer, different purpose than a deployed git remote.
+*
+* Data paths
+* ----------
+* System git config rewrites every `https://` fetch/clone URL to this daemon,
+* preserving the true authority as the first path segment:
+*
+*   https://github.com/owner/repo.git
+*     -> http://127.0.0.1:PORT/github.com/owner/repo.git
+*
+* Pushes are restored to direct HTTPS by a matching `pushInsteadOf`, so this
+* daemon only ever serves upload-pack (never receive-pack).
+*
+* Cold miss  : stream the origin's upload-pack response to the first client
+*              byte-for-byte while opportunistically ingesting the sideband
+*              pack into a quarantined bare repo. If the ingest cannot form a
+*              complete standalone mirror (filtered / shallow / have-based /
+*              too large / disconnected), it is abandoned — the client's clone
+*              is never affected. On success the mirror is atomically published
+*              for warm reuse.
+* Warm hit   : serve `git-upload-pack` from the local mirror.
+* Refresh    : stale mirrors are served immediately (stale-while-revalidate)
+*              and refreshed in the background.
+*
+* Security: binds loopback only; upstream host/path are strictly validated
+* (SSRF surface); credentials come from the platform git credential helper and
+* never touch the client hop, the mirror config, URLs, argv, or logs.
+*
+* Zero runtime dependencies (stdlib only) so it can run in the system layer
+* with no npm install.
+*/
+const gunzip$1 = promisify(gunzip);
+/**
+* An unset/empty env resolves to trusted-client (the daemon's original
+* contract); anything other than the two known modes is a hard startup
+* error rather than a silent fallback — a typo'd GIT_CACHE_AUTH_MODE on a
+* shared deployment must never quietly run without authorization.
+*/
+function parseAuthMode(raw) {
+	if (!raw) return "trusted-client";
+	if (raw === "trusted-client" || raw === "check-through") return raw;
+	throw new Error(`git-cache: unknown GIT_CACHE_AUTH_MODE '${raw}' (expected 'trusted-client' or 'check-through')`);
+}
+const config = {
+	port: Number(process.env.GIT_CACHE_PORT || process.env.PORT || 38996),
+	bindHost: process.env.GIT_CACHE_BIND || "127.0.0.1",
+	cacheDir: process.env.GIT_CACHE_DIR || "/home/user/.cache/git-cache",
+	ttlSeconds: Number(process.env.GIT_CACHE_TTL_SECONDS || 300),
+	credentialHelper: process.env.GIT_CACHE_CREDENTIAL_HELPER || "",
+	authMode: parseAuthMode(process.env.GIT_CACHE_AUTH_MODE),
+	maxPackBytes: Number(process.env.GIT_CACHE_MAX_PACK_BYTES || 8 * 1024 * 1024 * 1024),
+	maxImporterQueueBytes: Number(process.env.GIT_CACHE_MAX_IMPORTER_QUEUE_BYTES || 256 * 1024 * 1024),
+	maxCacheBytes: Number(process.env.GIT_CACHE_MAX_CACHE_BYTES || 0),
+	hostAllowlist: (process.env.GIT_CACHE_HOST_ALLOWLIST || "").split(",").map((h) => h.trim().toLowerCase()).filter(Boolean),
+	logLevel: process.env.GIT_CACHE_LOG_LEVEL || "info",
+	testOriginBase: (process.env.GIT_CACHE_TEST_ORIGIN_BASE || "").replace(/\/+$/, "")
+};
+const LOG_LEVELS = {
+	error: 0,
+	warn: 1,
+	info: 2,
+	debug: 3
+};
+const GIT_ENV = {
+	...process.env,
+	GIT_TERMINAL_PROMPT: "0",
+	GIT_ASKPASS: "/bin/true",
+	SSH_ASKPASS: "/bin/true",
+	GCM_INTERACTIVE: "never",
+	GIT_CONFIG_NOSYSTEM: process.env.GIT_CONFIG_NOSYSTEM || "1"
+};
+const activeLevel = LOG_LEVELS[config.logLevel] ?? LOG_LEVELS.info;
+function log(level, event, fields = {}) {
+	if ((LOG_LEVELS[level] ?? 2) > activeLevel) return;
+	const record = {
+		ts: (/* @__PURE__ */ new Date()).toISOString(),
+		service: "git-cache",
+		level,
+		event,
+		...fields
+	};
+	const line = JSON.stringify(record);
+	if (level === "error" || level === "warn") process.stderr.write(line + "\n");
+	else process.stdout.write(line + "\n");
+}
+const metrics = {
+	cold_requests: 0,
+	cold_followers: 0,
+	warm_hits: 0,
+	refreshes: 0,
+	publications: 0,
+	abandoned_ineligible: 0,
+	abandoned_oversize: 0,
+	abandoned_queue_overflow: 0,
+	abandoned_import_error: 0,
+	abandoned_disconnect: 0,
+	passthrough_ineligible: 0,
+	passthrough_missing_want: 0,
+	invalidations: 0,
+	evictions: 0,
+	refresh_failures: 0,
+	refresh_deferred: 0,
+	publish_deferred: 0,
+	credential_url_redirects: 0,
+	lfs_redirects: 0,
+	upstream_errors: 0,
+	bad_requests: 0,
+	cold_proxy_bytes: 0,
+	captured_pack_bytes: 0,
+	cold_build_failures: 0,
+	backfills: 0,
+	backfill_failures: 0,
+	auth_checks: 0,
+	auth_memo_hits: 0,
+	auth_denials: 0
+};
+/** The counter payload `/metrics` serves. Copied so callers can't mutate it. */
+function metricsSnapshot() {
+	return { ...metrics };
+}
+/**
+* Record the outcome of a finished cold build. A failure leaves the mirror
+* unpublished, so every later clone silently pays full upstream cost — it must
+* move a counter and not just write a log line, or a cache that never publishes
+* reads as healthy on /metrics.
+*/
+function recordColdBuildOutcome(error) {
+	if (!error) return;
+	metrics.cold_build_failures++;
+}
+/** repo -> Promise resolving when an in-flight background refresh finishes. */
+const inflightRefresh = /* @__PURE__ */ new Map();
+/** Set of repos with a cold-stream leader currently populating the cache. */
+const coldLeaders = /* @__PURE__ */ new Set();
+/** repo -> parsed advertisement refs from the most recent cold info/refs. */
+const advertisements = /* @__PURE__ */ new Map();
+/** Wall-clock ms; any mirror last-fetched before this is treated as stale. */
+let invalidateBeforeMs = 0;
+function upstreamGitArgs(args) {
+	return config.credentialHelper ? [
+		"-c",
+		`credential.helper=${config.credentialHelper}`,
+		...args
+	] : args;
+}
+/**
+* @param {string[]} args
+* @param {import('node:child_process').SpawnOptions} [options]
+* @returns {Promise<{ stdout: string, stderr: string }>}
+*/
+function runGit(args, options = {}) {
+	return new Promise((resolve, reject) => {
+		const child = spawn("git", args, {
+			env: GIT_ENV,
+			...options,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		let outBytes = 0;
+		let errBytes = 0;
+		const CAP = 256 * 1024;
+		child.stdout.on("data", (d) => {
+			if (outBytes < CAP) {
+				stdout += d;
+				outBytes += d.length;
+			}
+		});
+		child.stderr.on("data", (d) => {
+			if (errBytes < CAP) {
+				stderr += d;
+				errBytes += d.length;
+			}
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) resolve({
+				stdout,
+				stderr
+			});
+			else reject(/* @__PURE__ */ new Error(`git ${args[0]} exited ${code}: ${stderr.trim()}`));
+		});
+	});
+}
+/** host -> Promise<string|null> Basic auth header ("Basic base64(user:pass)"). */
+const credentialCache = /* @__PURE__ */ new Map();
+async function fetchCredentialHeader(host) {
+	if (!config.credentialHelper) return null;
+	if (credentialCache.has(host)) return credentialCache.get(host);
+	const p = (async () => {
+		try {
+			/** @type {string} */
+			const stdout = await new Promise((resolve, reject) => {
+				const child = spawn("git", [
+					"-c",
+					`credential.helper=${config.credentialHelper}`,
+					"credential",
+					"fill"
+				], {
+					stdio: [
+						"pipe",
+						"pipe",
+						"pipe"
+					],
+					env: GIT_ENV
+				});
+				let out = "";
+				let err = "";
+				child.stdout.on("data", (d) => out += d);
+				child.stderr.on("data", (d) => {
+					if (err.length < 64 * 1024) err += d;
+				});
+				child.on("error", reject);
+				child.on("close", (code) => {
+					if (code === 0) resolve(out);
+					else reject(/* @__PURE__ */ new Error(`git credential fill exited ${code}: ${err.trim()}`));
+				});
+				child.stdin.end(`protocol=https\nhost=${host}\n\n`);
+			});
+			const fields = {};
+			for (const line of stdout.split("\n")) {
+				const eq = line.indexOf("=");
+				if (eq > 0) fields[line.slice(0, eq)] = line.slice(eq + 1);
+			}
+			if (!fields.username && !fields.password) return null;
+			return `Basic ${Buffer.from(`${fields.username || ""}:${fields.password || ""}`).toString("base64")}`;
+		} catch (_error) {
+			log("debug", "credential_fill_miss", { host });
+			return null;
+		}
+	})();
+	credentialCache.set(host, p);
+	return p;
+}
+function dropCredential(host) {
+	credentialCache.delete(host);
+}
+/**
+* Guard against non-numeric env values explicitly: NaN would only be
+* fail-safe through the accident of `elapsed < NaN` being false, and any
+* later refactor to a `>= ttl` comparison would silently flip that into
+* memoize-forever.
+*/
+function parseTtlMs(raw, fallback) {
+	const n = Number(raw);
+	return raw !== void 0 && Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+const AUTH_ALLOW_TTL_MS = parseTtlMs(process.env.GIT_CACHE_AUTH_ALLOW_TTL_MS, 6e4);
+const AUTH_DENY_TTL_MS = parseTtlMs(process.env.GIT_CACHE_AUTH_DENY_TTL_MS, 5e3);
+const AUTH_CACHE_MAX = 1e4;
+let AUTH_HMAC_KEY = randomBytes(32);
+/** memoKey -> { at, allowed, status } */
+const authCache = /* @__PURE__ */ new Map();
+/** memoKey -> in-flight validation. A clone is a GET+POST pair and a herd is
+* many clients on one repo; coalescing means each (credential, repo) costs one
+* upstream round-trip per TTL window, not one per request. */
+const authInflight = /* @__PURE__ */ new Map();
+function authMemoKey(credHeader, repo) {
+	return `${createHmac("sha256", AUTH_HMAC_KEY).update(credHeader).digest("hex")} ${repo}`;
+}
+function evictAuthCache() {
+	if (authCache.size <= AUTH_CACHE_MAX) return;
+	const now = Date.now();
+	for (const [key, entry] of authCache) {
+		const ttl = entry.allowed ? AUTH_ALLOW_TTL_MS : AUTH_DENY_TTL_MS;
+		if (now - entry.at > ttl) authCache.delete(key);
+	}
+	if (authCache.size > AUTH_CACHE_MAX) {
+		const iter = authCache.keys();
+		while (authCache.size > AUTH_CACHE_MAX) {
+			const next = iter.next();
+			if (next.done) break;
+			authCache.delete(next.value);
+		}
+	}
+}
+function validateUpstream(credHeader, upstreamUrl) {
+	return new Promise((resolve) => {
+		const request = requestUpstream(new URL(`${upstreamUrl}/info/refs?service=git-upload-pack`), {
+			method: "GET",
+			headers: {
+				authorization: credHeader,
+				"user-agent": "git/git-cache-authz"
+			}
+		}, (res) => {
+			res.resume();
+			const status = res.statusCode ?? 502;
+			if (status === 200) {
+				resolve({
+					allowed: true,
+					status: 200
+				});
+				return;
+			}
+			if (status >= 300 && status < 400) {
+				resolve({
+					allowed: false,
+					status: 404
+				});
+				return;
+			}
+			resolve({
+				allowed: false,
+				status: status === 401 || status === 403 || status === 404 ? status : 502
+			});
+		});
+		request.setTimeout(1e4, () => {
+			request.destroy();
+			resolve({
+				allowed: false,
+				status: 502
+			});
+		});
+		request.on("error", () => resolve({
+			allowed: false,
+			status: 502
+		}));
+		request.end();
+	});
+}
+async function authorizeCheckThrough(credHeader, repo, upstreamUrl) {
+	const key = authMemoKey(credHeader, repo);
+	const cached = authCache.get(key);
+	if (cached) {
+		const ttl = cached.allowed ? AUTH_ALLOW_TTL_MS : AUTH_DENY_TTL_MS;
+		if (Date.now() - cached.at < ttl) {
+			metrics.auth_memo_hits++;
+			return cached;
+		}
+		authCache.delete(key);
+	}
+	const inflight = authInflight.get(key);
+	if (inflight) return inflight;
+	const p = (async () => {
+		const verdict = await validateUpstream(credHeader, upstreamUrl);
+		metrics.auth_checks++;
+		if (!verdict.allowed) metrics.auth_denials++;
+		if (verdict.status !== 502) {
+			authCache.set(key, {
+				at: Date.now(),
+				...verdict
+			});
+			evictAuthCache();
+		}
+		return verdict;
+	})().finally(() => authInflight.delete(key));
+	authInflight.set(key, p);
+	return p;
+}
+/**
+* Env fragment handing a client's credential to a spawned git subprocess via
+* config-over-environment — never argv (visible in /proc) and never on-disk
+* config. Composes with GIT_ENV: GIT_CONFIG_NOSYSTEM does not affect
+* GIT_CONFIG_COUNT entries.
+*/
+function upstreamGitCredentialEnv(credHeader) {
+	if (!credHeader) return {};
+	return {
+		GIT_CONFIG_COUNT: "1",
+		GIT_CONFIG_KEY_0: "http.extraHeader",
+		GIT_CONFIG_VALUE_0: `Authorization: ${credHeader}`
+	};
+}
+const HOSTNAME_RE = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+/**
+* True for anything that looks like an IPv4 dotted-quad or an IPv6 literal
+* (with or without brackets). We refuse IP-literal upstream hosts entirely.
+*/
+function isIpLiteral(host) {
+	const h = host.replace(/^\[|\]$/g, "");
+	if (/:/.test(h)) return true;
+	const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+	if (m) return m.slice(1).every((o) => Number(o) <= 255);
+	const last = h.split(".").pop();
+	return /^\d+$/.test(last || "");
+}
+function parseUpstream(rawPathname, rawSearch = "") {
+	if (/[\u0000-\u001f\u007f]/.test(rawPathname)) return null;
+	let pathname;
+	try {
+		pathname = decodeURIComponent(rawPathname);
+	} catch (_error) {
+		return null;
+	}
+	try {
+		if (decodeURIComponent(pathname) !== pathname) return null;
+	} catch (_error) {
+		return null;
+	}
+	const match = pathname.match(/^\/([^/]+)\/(.+?)(\.git)?\/(info\/refs|git-upload-pack)$/);
+	if (!match) {
+		const lfs = pathname.match(/^\/([^/@]+)\/(.+?\/info\/lfs(?:\/.*)?)$/);
+		if (lfs && !isIpLiteral(lfs[1].split(":")[0])) {
+			const authority = lfs[1];
+			const host = authority.split(":")[0].toLowerCase();
+			if (HOSTNAME_RE.test(host) && host !== "localhost" && !host.endsWith(".localhost")) return {
+				redirect: `https://${authority}/${lfs[2]}${rawSearch || ""}`,
+				operation: "lfs"
+			};
+		}
+		return null;
+	}
+	const authority = match[1];
+	const at = authority.lastIndexOf("@");
+	if (at !== -1) {
+		const hostPort = authority.slice(at + 1);
+		const rest = pathname.slice(1 + authority.length);
+		if (hostPort && authority.indexOf("@") === at && /^[A-Za-z0-9.:-]+$/.test(hostPort)) return {
+			redirect: `https://${authority}${rest}${rawSearch || ""}`,
+			operation: match[4]
+		};
+		return null;
+	}
+	const repoPath = match[2].replace(/\.git$/, "");
+	const hadDotGit = Boolean(match[3]);
+	const operation = match[4];
+	let host = authority;
+	let port = 443;
+	const colon = authority.lastIndexOf(":");
+	if (colon !== -1) {
+		host = authority.slice(0, colon);
+		const p = authority.slice(colon + 1);
+		if (!/^\d{1,5}$/.test(p)) return null;
+		port = Number(p);
+		if (port !== 443) return null;
+	}
+	host = host.toLowerCase();
+	if (isIpLiteral(host)) return null;
+	if (!HOSTNAME_RE.test(host)) return null;
+	if (host === "localhost" || host.endsWith(".localhost")) return null;
+	if (!/\.[a-z]{2,}$/.test(host)) return null;
+	if (config.hostAllowlist.length && !config.hostAllowlist.includes(host)) return null;
+	if (repoPath.includes("..") || repoPath.startsWith("/") || repoPath.endsWith("/") || repoPath.split("/").some((seg) => seg === "" || seg === "." || seg === "..")) return null;
+	if (!/^[A-Za-z0-9._~+@/-]+$/.test(repoPath)) return null;
+	const repo = `${host}/${repoPath}`;
+	const suffix = hadDotGit ? ".git" : "";
+	return {
+		repo,
+		upstreamUrl: config.testOriginBase ? `${config.testOriginBase}/${repo}${suffix}` : `https://${authority}/${repoPath}${suffix}`,
+		operation
+	};
+}
+/**
+* Best-effort human explanation for a request parseUpstream refused, used
+* ONLY in the 404 body so an agent whose (legitimate but unproxyable) remote
+* hits a security rejection gets an actionable error instead of an opaque
+* "git cache endpoint". Diagnostic only — the actual gate is parseUpstream;
+* this never influences serving decisions, so a miss here is harmless.
+*/
+function explainRejection(rawPathname) {
+	let pathname;
+	try {
+		pathname = decodeURIComponent(rawPathname);
+	} catch (_error) {
+		return null;
+	}
+	const m = pathname.match(/^\/([^/]+)\//);
+	if (!m) return null;
+	const authority = m[1];
+	if (authority === void 0 || authority.includes("@")) return null;
+	const colon = authority.lastIndexOf(":");
+	const host = (colon === -1 ? authority : authority.slice(0, colon)).replace(/^\[|\]$/g, "").toLowerCase();
+	const port = colon === -1 ? null : authority.slice(colon + 1);
+	if (port !== null && /^\d{1,5}$/.test(port) && Number(port) !== 443) return `refusing upstream on non-443 port :${port}`;
+	if (isIpLiteral(host)) return "refusing IP-literal upstream host (DNS names only)";
+	if (host === "localhost" || host.endsWith(".localhost")) return "refusing localhost upstream";
+	if (!host.includes(".")) return "refusing single-label upstream host";
+	return null;
+}
+function validateMethod(req, operation) {
+	if (operation === "info/refs") return req.method === "GET";
+	if (operation === "git-upload-pack") return req.method === "POST";
+	return false;
+}
+/**
+* How long a held lock may go untouched before another writer may break it.
+* A live holder refreshes its lock every LOCK_HEARTBEAT_MS, so only a crashed
+* or wedged process falls this far behind.
+*/
+const LOCK_STALE_MS = 180 * 1e3;
+const LOCK_HEARTBEAT_MS = 20 * 1e3;
+/** Read a filesystem or stream error's `code` without asserting a type. */
+function errnoCode(error) {
+	if (typeof error === "object" && error !== null && "code" in error) {
+		const { code } = error;
+		return typeof code === "string" ? code : void 0;
+	}
+}
+function lockPath(repo, name) {
+	return path.join(config.cacheDir, "locks", `${repo.replace(/\//g, "__")}.${name}.lock`);
+}
+/**
+* Run `fn` while holding a named lock for `repo`, or return `null` without
+* running it if another writer holds that lock.
+*
+* The in-memory guards elsewhere in this file (`inflightRefresh`,
+* `coldLeaders`, `backfilling`) only serialize writers inside ONE process,
+* which is the whole story when each process owns its own disk. On a mirror
+* store shared between tasks they are blind to each other, so two tasks will
+* happily fetch into, publish over, or evict the same mirror at the same
+* time. This lock is what makes those operations mutually exclusive across
+* every writer of the store.
+*
+* `mkdir` is the primitive because its create-or-fail is atomic on a single
+* disk and over NFS alike. A lock whose mtime has stopped advancing is
+* assumed abandoned and broken, so a task that dies mid-operation cannot
+* wedge a repo forever.
+*/
+async function withRepoLock(repo, name, fn) {
+	const dir = lockPath(repo, name);
+	await mkdir(path.dirname(dir), { recursive: true });
+	const acquire = async () => {
+		try {
+			await mkdir(dir);
+			return true;
+		} catch (error) {
+			if (errnoCode(error) !== "EEXIST") throw error;
+			return false;
+		}
+	};
+	let held = await acquire();
+	if (!held) try {
+		const info = await stat(dir);
+		if (Date.now() - info.mtimeMs > LOCK_STALE_MS) {
+			log("warn", "lock_broken", {
+				repo,
+				name
+			});
+			await rm(dir, {
+				recursive: true,
+				force: true
+			});
+			held = await acquire();
+		}
+	} catch (_error) {
+		held = await acquire();
+	}
+	if (!held) return null;
+	await writeFile(path.join(dir, "owner"), INSTANCE_ID, "utf8").catch((_error) => log("debug", "lock_owner_write_failed", {
+		repo,
+		name
+	}));
+	const heartbeat = setInterval(() => {
+		const now = /* @__PURE__ */ new Date();
+		utimes(dir, now, now).catch((error) => log("debug", "lock_heartbeat_failed", {
+			repo,
+			name,
+			error: String(error)
+		}));
+	}, LOCK_HEARTBEAT_MS);
+	heartbeat.unref?.();
+	try {
+		return await fn();
+	} finally {
+		clearInterval(heartbeat);
+		await rm(dir, {
+			recursive: true,
+			force: true
+		}).catch((_error) => log("debug", "lock_release_failed", {
+			repo,
+			name
+		}));
+	}
+}
+/**
+* Identifies this process among every writer sharing the mirror store.
+*
+* When the store is a shared filesystem, several tasks write to it at once and
+* a pid is no longer unique — two tasks routinely run the same pid. Temp paths
+* and lock ownership records mix in the host and a random suffix so they
+* cannot collide.
+*/
+const INSTANCE_ID = `${hostname()}-${process.pid}-${randomBytes(4).toString("hex")}`;
+function localPath(repo) {
+	return path.join(config.cacheDir, "mirrors", `${repo}.git`);
+}
+const metaPath = (local) => `${local}.meta.json`;
+const servedMarkerPath = (local) => `${local}.served`;
+/**
+* How recently a mirror must have been served to be exempt from eviction.
+*
+* Eviction orders by last upstream fetch, which says nothing about whether
+* clients are reading a mirror right now. A busy repo whose refreshes are all
+* cheap no-ops can therefore sort to the front of the LRU list while it is
+* actively streaming.
+*/
+const EVICTION_QUIET_MS = 900 * 1e3;
+/**
+* Record that this mirror just served a client.
+*
+* A marker file rather than an in-memory timestamp because the reader and the
+* evictor can be different tasks. Best-effort on purpose: failing to record a
+* serve must never fail the serve itself, and the cost of missing one is a
+* mirror that becomes eligible for eviction slightly early.
+*/
+function markServed(local) {
+	const now = /* @__PURE__ */ new Date();
+	writeFile(servedMarkerPath(local), "", "utf8").then(() => utimes(servedMarkerPath(local), now, now)).catch((error) => log("debug", "served_mark_failed", {
+		local,
+		error: String(error)
+	}));
+}
+async function readLastServedMs(local) {
+	try {
+		return (await stat(servedMarkerPath(local))).mtimeMs;
+	} catch (_error) {
+		return 0;
+	}
+}
+async function pathExists(p) {
+	try {
+		await stat(p);
+		return true;
+	} catch (_error) {
+		return false;
+	}
+}
+function copyRequestHeaders(headers) {
+	const result = {};
+	for (const [name, value] of Object.entries(headers)) {
+		const lower = name.toLowerCase();
+		if ([
+			"host",
+			"connection",
+			"authorization",
+			"proxy-authorization",
+			"transfer-encoding",
+			"content-length",
+			"content-encoding"
+		].includes(lower)) continue;
+		result[name] = value;
+	}
+	return result;
+}
+/** Merge copied client headers with the cache's own upstream credential. */
+function withCredential(headers, credHeader) {
+	const merged = { ...headers };
+	if (credHeader) merged["authorization"] = credHeader;
+	return merged;
+}
+/**
+* Scheme-aware upstream request: https in production, http only for the
+* test-origin override (config.testOriginBase). Everything else is identical.
+*/
+function requestUpstream(target, options, callback) {
+	return (target.protocol === "http:" ? http : https).request(target, options, callback);
+}
+function openUpstream(req, upstreamUrl, operation, callback, credHeader) {
+	const up = requestUpstream(new URL(upstreamUrl + (operation === "info/refs" ? "/info/refs?service=git-upload-pack" : "/git-upload-pack")), {
+		method: req.method,
+		headers: withCredential(copyRequestHeaders(req.headers), credHeader)
+	}, (res) => callback(res, null));
+	up.on("error", (error) => callback(null, error));
+	if (req.method === "POST") req.pipe(up);
+	else up.end();
+	return up;
+}
+function parseAdvertisement(buffer) {
+	const refs = [];
+	let offset = 0;
+	let sha256 = false;
+	while (offset + 4 <= buffer.length) {
+		const header = buffer.subarray(offset, offset + 4).toString("ascii");
+		if (!/^[0-9a-f]{4}$/i.test(header)) break;
+		const size = Number.parseInt(header, 16);
+		offset += 4;
+		if (size === 0 || size === 1 || size === 2) continue;
+		if (size < 4 || offset + size - 4 > buffer.length) break;
+		let line = buffer.subarray(offset, offset + size - 4);
+		offset += size - 4;
+		const nul = line.indexOf(0);
+		if (nul >= 0 && line.includes(Buffer.from("object-format=sha256"))) sha256 = true;
+		if (nul >= 0) line = line.subarray(0, nul);
+		const [, oid, ref] = line.toString("utf8").trim().match(/^([0-9a-f]{40}) (refs\/[A-Za-z0-9._/-]+|HEAD)$/) ?? [];
+		if (oid && ref && !ref.endsWith("^{}")) refs.push({
+			oid,
+			ref
+		});
+	}
+	return {
+		refs,
+		sha256
+	};
+}
+/**
+* Inspect a client's git-upload-pack request body to decide cache eligibility.
+* We only ingest packs that can form a COMPLETE standalone mirror: no filter,
+* no shallow/deepen, and no client-provided `have` lines (which would make the
+* server omit objects the client already had). Everything else is passed
+* through with ingestion disabled — correctness over coverage.
+*
+* Returns { eligible, reason }.
+*/
+/**
+* True when a `git-upload-pack` POST body speaks protocol v2.
+*
+* v2 replaces v0's bare want/have lines with a leading `command=<verb>` line,
+* so the first pkt-line identifies the dialect unambiguously.
+*/
+function isProtocolV2Request(buffer) {
+	if (buffer.length < 4) return false;
+	const header = buffer.subarray(0, 4).toString("ascii");
+	if (!/^[0-9a-f]{4}$/i.test(header)) return false;
+	const size = Number.parseInt(header, 16);
+	if (size < 4 || size > buffer.length) return false;
+	return buffer.subarray(4, size).toString("utf8").startsWith("command=");
+}
+function classifyUploadRequest(buffer) {
+	const protocolV2 = isProtocolV2Request(buffer);
+	let offset = 0;
+	let sawWant = false;
+	const reasons = [];
+	const wants = [];
+	while (offset + 4 <= buffer.length) {
+		const header = buffer.subarray(offset, offset + 4).toString("ascii");
+		if (!/^[0-9a-f]{4}$/i.test(header)) break;
+		const size = Number.parseInt(header, 16);
+		offset += 4;
+		if (size === 0 || size === 1 || size === 2) continue;
+		if (size < 4 || offset + size - 4 > buffer.length) break;
+		const line = buffer.subarray(offset, offset + size - 4).toString("utf8");
+		offset += size - 4;
+		const token = line.trim();
+		if (token.startsWith("want ")) {
+			sawWant = true;
+			const oid = token.slice(5).split(" ")[0].split("\0")[0];
+			if (/^[0-9a-f]{40}$/i.test(oid)) wants.push(oid.toLowerCase());
+			const caps = line.includes("\0") ? line.split("\0")[1] || "" : "";
+			if (/(^|\s)filter(\s|=|$)/.test(caps)) reasons.push("filter-cap");
+			if (/(^|\s)deepen/.test(caps)) reasons.push("deepen-cap");
+		} else if (token.startsWith("have ")) reasons.push("have");
+		else if (token.startsWith("shallow ")) reasons.push("shallow");
+		else if (token.startsWith("deepen")) reasons.push("deepen");
+		else if (token.startsWith("filter ")) reasons.push("filter");
+	}
+	if (protocolV2) return {
+		eligible: false,
+		reason: "protocol-v2",
+		wants
+	};
+	if (!sawWant) return {
+		eligible: false,
+		reason: "no-want",
+		wants
+	};
+	if (reasons.length) return {
+		eligible: false,
+		reason: [...new Set(reasons)].join(","),
+		wants
+	};
+	return {
+		eligible: true,
+		reason: "full-clone",
+		wants
+	};
+}
+var SidebandPackExtractor = class {
+	writable;
+	buffer;
+	sawPack;
+	inPackSection;
+	needsDrain;
+	errored;
+	constructor(writable) {
+		this.writable = writable;
+		this.buffer = Buffer.alloc(0);
+		this.sawPack = false;
+		this.inPackSection = false;
+		this.needsDrain = false;
+		this.errored = false;
+	}
+	push(chunk) {
+		this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk;
+		while (this.buffer.length >= 4) {
+			const header = this.buffer.subarray(0, 4).toString("ascii");
+			if (!/^[0-9a-f]{4}$/i.test(header)) throw new Error("invalid upload-pack pkt-line header");
+			const size = Number.parseInt(header, 16);
+			if (size === 0 || size === 1 || size === 2) {
+				this.buffer = this.buffer.subarray(4);
+				continue;
+			}
+			if (size < 5 || this.buffer.length < size) return;
+			const packet = this.buffer.subarray(4, size);
+			this.buffer = this.buffer.subarray(size);
+			if (packet.toString("utf8") === "packfile\n") {
+				this.inPackSection = true;
+				continue;
+			}
+			if (packet[0] === 1 && (this.inPackSection || packet.subarray(1, 5).toString("ascii") === "PACK")) {
+				this.inPackSection = true;
+				this.sawPack = true;
+				if (!this.writable.write(packet.subarray(1))) this.needsDrain = true;
+			}
+		}
+		return !this.needsDrain;
+	}
+	drained() {
+		this.needsDrain = false;
+	}
+	end() {
+		if (!this.errored) this.writable.end();
+	}
+};
+async function writeMeta(local, extra = {}) {
+	const tmp = `${metaPath(local)}.tmp.${INSTANCE_ID}`;
+	await writeFile(tmp, JSON.stringify({
+		lastFetchMs: Date.now(),
+		...extra
+	}), "utf8");
+	await rename(tmp, metaPath(local));
+}
+async function readMeta(local) {
+	try {
+		return JSON.parse(await readFile(metaPath(local), "utf8"));
+	} catch (_error) {
+		return null;
+	}
+}
+/**
+* Stop git from repacking or pruning this mirror on its own.
+*
+* `git fetch` runs auto-maintenance afterwards, which repacks and then
+* DELETES the packfiles it superseded. On one machine that is invisible:
+* a reader already holding the file keeps reading it after the unlink. When
+* the store is shared between tasks that guarantee is gone — the deleting
+* task and the reading task are different NFS clients, and the reader's next
+* read of a file deleted underneath it fails with a stale handle mid-stream.
+*
+* Packfiles are only immutable while they exist; maintenance is what removes
+* them. Turning it off here keeps mirror contents append-only, which is what
+* makes concurrent readers safe. Repacking still has to happen eventually,
+* but as a deliberate operation under the mirror lock rather than as a side
+* effect of whichever task happened to fetch.
+*/
+async function disableAutoMaintenance(dir) {
+	await runGit([
+		"--git-dir",
+		dir,
+		"config",
+		"gc.auto",
+		"0"
+	]);
+	await runGit([
+		"--git-dir",
+		dir,
+		"config",
+		"maintenance.auto",
+		"false"
+	]);
+}
+async function configureMirror(dir, upstreamUrl) {
+	await runGit([
+		"--git-dir",
+		dir,
+		"config",
+		"uploadpack.allowFilter",
+		"true"
+	]);
+	await runGit([
+		"--git-dir",
+		dir,
+		"config",
+		"uploadpack.allowAnySHA1InWant",
+		"true"
+	]);
+	await disableAutoMaintenance(dir);
+	await runGit([
+		"--git-dir",
+		dir,
+		"config",
+		"remote.origin.url",
+		upstreamUrl
+	]);
+	await runGit([
+		"--git-dir",
+		dir,
+		"config",
+		"--replace-all",
+		"remote.origin.fetch",
+		"+refs/heads/*:refs/heads/*"
+	]);
+	await runGit([
+		"--git-dir",
+		dir,
+		"config",
+		"--add",
+		"remote.origin.fetch",
+		"+refs/tags/*:refs/tags/*"
+	]);
+	await runGit([
+		"--git-dir",
+		dir,
+		"config",
+		"remote.origin.tagOpt",
+		"--tags"
+	]);
+}
+async function completeCapturedMirror(dir, upstreamUrl, refs, credHeader = null) {
+	await configureMirror(dir, upstreamUrl);
+	await runGit(upstreamGitArgs([
+		"--git-dir",
+		dir,
+		"fetch",
+		"--quiet",
+		"--prune",
+		"--prune-tags",
+		"origin"
+	]), { env: {
+		...GIT_ENV,
+		...upstreamGitCredentialEnv(credHeader)
+	} });
+	const advertisedHead = (refs || []).find((r) => r.ref === "HEAD")?.oid;
+	const candidates = advertisedHead ? (refs || []).filter((r) => r.ref.startsWith("refs/heads/") && r.oid === advertisedHead) : [];
+	if (candidates.length === 1) await runGit([
+		"--git-dir",
+		dir,
+		"symbolic-ref",
+		"HEAD",
+		candidates[0].ref
+	]);
+	else try {
+		const { stdout } = await runGit(upstreamGitArgs([
+			"--git-dir",
+			dir,
+			"ls-remote",
+			"--symref",
+			"origin",
+			"HEAD"
+		]), { env: {
+			...GIT_ENV,
+			...upstreamGitCredentialEnv(credHeader)
+		} });
+		const match = stdout.match(/^ref:\s+(refs\/heads\/\S+)\s+HEAD$/m);
+		if (match) await runGit([
+			"--git-dir",
+			dir,
+			"symbolic-ref",
+			"HEAD",
+			match[1]
+		]);
+	} catch (_error) {}
+	await runGit([
+		"--git-dir",
+		dir,
+		"fsck",
+		"--connectivity-only",
+		"--no-dangling"
+	]);
+}
+/** Repos with a background backfill in flight, so two never race. */
+const backfilling = /* @__PURE__ */ new Set();
+/**
+* Whether a request that could NOT be cached is worth building a mirror for
+* out-of-band. Only uncacheable requests need it — a cacheable one already
+* populated the cache — and a sha256 repo is excluded because the
+* advertisement parser cannot read its 64-hex OIDs, so no correct mirror can
+* be completed for it at all.
+*/
+function shouldBackfillAfterPassthrough({ cacheable, sha256 }) {
+	return !cacheable && !sha256;
+}
+/**
+* Build a mirror for a repo whose client request could not seed one.
+*
+* A filtered / shallow / incremental fetch receives a deliberately incomplete
+* pack, so it passes through and populates nothing. Left there it is a dead
+* end, and the worst kind: the agent prompt steers LARGE repos toward
+* `--filter=blob:none`, so the repos the cache would help most are exactly the
+* ones that would never get a mirror. Fetch our own complete copy instead,
+* independently of what the client asked for.
+*
+* Runs AFTER the client's passthrough has finished, so this fetch never
+* competes for bandwidth with the clone an agent is waiting on. Once published,
+* later clones are served locally — filtered ones included, since a complete
+* mirror can satisfy any request shape (`uploadpack.allowFilter` is set on it).
+*/
+async function backfillMirror(repo, upstreamUrl, credHeader = null) {
+	if (backfilling.has(repo) || coldLeaders.has(repo)) return;
+	const local = localPath(repo);
+	if (await pathExists(local)) return;
+	backfilling.add(repo);
+	const temp = `${config.cacheDir}/quarantine/${repo.replace(/\//g, "__")}.backfill-${INSTANCE_ID}-${Date.now()}`;
+	const startedMs = Date.now();
+	try {
+		log("info", "backfill_start", { repo });
+		await mkdir(path.dirname(local), { recursive: true });
+		await mkdir(path.dirname(temp), { recursive: true });
+		await rm(temp, {
+			recursive: true,
+			force: true
+		});
+		await runGit([
+			"init",
+			"--bare",
+			"--quiet",
+			temp
+		]);
+		await completeCapturedMirror(temp, upstreamUrl, null, credHeader);
+		const published = await withRepoLock(repo, "write", async () => {
+			if (await pathExists(local)) return false;
+			await rename(temp, local);
+			await writeMeta(local, { publishedMs: Date.now() });
+			return true;
+		});
+		if (published !== true) {
+			if (published === null) {
+				metrics.publish_deferred++;
+				log("info", "publish_deferred", { repo });
+			}
+			await rm(temp, {
+				recursive: true,
+				force: true
+			});
+			return;
+		}
+		metrics.publications++;
+		metrics.backfills++;
+		log("info", "backfill_ready", {
+			repo,
+			ms: Date.now() - startedMs
+		});
+		await maybeEvict();
+	} catch (error) {
+		metrics.backfill_failures++;
+		log("error", "backfill_failed", {
+			repo,
+			error: String(error)
+		});
+		await rm(temp, {
+			recursive: true,
+			force: true
+		}).catch((_error) => log("debug", "cleanup_failed", { path: temp }));
+	} finally {
+		backfilling.delete(repo);
+	}
+}
+function startColdStream(req, res, upstreamUrl, repo, requestBody, credHeader) {
+	const local = localPath(repo);
+	const temp = `${config.cacheDir}/quarantine/${repo.replace(/\//g, "__")}.stream-${INSTANCE_ID}-${Date.now()}`;
+	metrics.cold_requests++;
+	coldLeaders.add(repo);
+	log("info", "cold_start", { repo });
+	const eligibility = classifyUploadRequest(requestBody);
+	const isSha256 = advertisements.get(repo)?.sha256 === true;
+	const wantCache = eligibility.eligible && !isSha256;
+	if (!wantCache) {
+		metrics.passthrough_ineligible++;
+		log("info", "cold_ineligible", {
+			repo,
+			reason: isSha256 ? "sha256-object-format" : eligibility.reason
+		});
+	}
+	let settle;
+	const done = new Promise((resolve, reject) => {
+		settle = {
+			resolve,
+			reject
+		};
+	});
+	(async () => {
+		await mkdir(path.dirname(local), { recursive: true });
+		await mkdir(path.dirname(temp), { recursive: true });
+		if (wantCache) {
+			await rm(temp, {
+				recursive: true,
+				force: true
+			});
+			await runGit([
+				"init",
+				"--bare",
+				"--quiet",
+				temp
+			]);
+		}
+		const up = requestUpstream(new URL(upstreamUrl + "/git-upload-pack"), {
+			method: "POST",
+			headers: withCredential(copyRequestHeaders(req.headers), credHeader)
+		}, (upRes) => {
+			res.writeHead(upRes.statusCode, upRes.headers);
+			if (upRes.statusCode !== 200) {
+				if (upRes.statusCode === 401 || upRes.statusCode === 403) dropCredential(repo.split("/")[0]);
+				metrics.upstream_errors++;
+				upRes.pipe(res);
+				upRes.on("end", () => settle.reject(/* @__PURE__ */ new Error(`upstream HTTP ${upRes.statusCode}`)));
+				return;
+			}
+			if (!wantCache) {
+				upRes.on("data", (c) => {
+					metrics.cold_proxy_bytes += c.length;
+				});
+				upRes.pipe(res);
+				upRes.on("end", () => settle.resolve(null));
+				upRes.on("error", (e) => settle.reject(e));
+				return;
+			}
+			const index = spawn("git", [
+				"--git-dir",
+				temp,
+				"index-pack",
+				"--stdin",
+				"--fix-thin",
+				"--keep=git-cache-cold"
+			], {
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				],
+				env: GIT_ENV
+			});
+			let indexOut = "";
+			let indexErr = "";
+			index.stdout.on("data", (d) => indexOut += d);
+			index.stderr.on("data", (d) => {
+				if (indexErr.length < 256 * 1024) indexErr += d;
+			});
+			const extractor = new SidebandPackExtractor(index.stdin);
+			let streamError = null;
+			let responseNeedsDrain = false;
+			let capturedBytes = 0;
+			let queuedBytes = 0;
+			let abandoned = false;
+			let clientGone = false;
+			const abandonCache = (reason, metric) => {
+				if (abandoned) return;
+				abandoned = true;
+				extractor.errored = true;
+				metrics[metric]++;
+				log("warn", "cold_abandon", {
+					repo,
+					reason
+				});
+				try {
+					index.stdin.destroy();
+				} catch (_error) {}
+				try {
+					index.kill("SIGTERM");
+				} catch (_error) {}
+			};
+			const resumeUpstream = () => {
+				if (!responseNeedsDrain && !extractor.needsDrain) upRes.resume();
+			};
+			res.on("drain", () => {
+				responseNeedsDrain = false;
+				resumeUpstream();
+			});
+			index.stdin.on("drain", () => {
+				queuedBytes = 0;
+				extractor.drained();
+				resumeUpstream();
+			});
+			index.stdin.on("error", () => {});
+			upRes.on("data", (chunk) => {
+				metrics.cold_proxy_bytes += chunk.length;
+				if (!clientGone && !res.write(chunk)) responseNeedsDrain = true;
+				if (!abandoned) {
+					capturedBytes += chunk.length;
+					if (config.maxPackBytes && capturedBytes > config.maxPackBytes) abandonCache("oversize", "abandoned_oversize");
+					else try {
+						if (!extractor.push(chunk)) {
+							queuedBytes += chunk.length;
+							if (queuedBytes > config.maxImporterQueueBytes) abandonCache("queue-overflow", "abandoned_queue_overflow");
+						}
+					} catch (error) {
+						streamError = error instanceof Error ? error : new Error(String(error));
+						abandonCache("parse-error", "abandoned_import_error");
+					}
+				}
+				if (responseNeedsDrain) upRes.pause();
+			});
+			upRes.on("end", () => {
+				if (!clientGone) res.end();
+				if (!abandoned) extractor.end();
+			});
+			upRes.on("error", (error) => {
+				streamError = error;
+				res.destroy(error);
+				abandonCache("upstream-error", "abandoned_import_error");
+			});
+			res.on("close", () => {
+				if (!res.writableEnded) {
+					clientGone = true;
+					responseNeedsDrain = false;
+					resumeUpstream();
+					log("debug", "client_disconnect_continue_warm", { repo });
+				}
+			});
+			index.on("close", async (code) => {
+				try {
+					if (abandoned) {
+						await rm(temp, {
+							recursive: true,
+							force: true
+						});
+						settle.resolve(null);
+						return;
+					}
+					if (streamError) throw streamError instanceof Error ? streamError : new Error(String(streamError));
+					if (!extractor.sawPack) {
+						await rm(temp, {
+							recursive: true,
+							force: true
+						});
+						settle.resolve(null);
+						return;
+					}
+					if (code !== 0) throw new Error(`index-pack exited ${code}: ${indexErr.trim()}`);
+					metrics.captured_pack_bytes += capturedBytes;
+					await completeCapturedMirror(temp, upstreamUrl, advertisements.get(repo)?.refs, credHeader);
+					const published = await withRepoLock(repo, "write", async () => {
+						if (await pathExists(local)) return false;
+						await rename(temp, local);
+						await writeMeta(local, { publishedMs: Date.now() });
+						return true;
+					});
+					if (published === true) {
+						metrics.publications++;
+						log("info", "cold_ready", {
+							repo,
+							pack: indexOut.trim()
+						});
+						await maybeEvict();
+					} else {
+						if (published === null) {
+							metrics.publish_deferred++;
+							log("info", "publish_deferred", { repo });
+						}
+						await rm(temp, {
+							recursive: true,
+							force: true
+						});
+					}
+					settle.resolve(local);
+				} catch (error) {
+					settle.reject(error);
+				}
+			});
+		});
+		up.on("error", (error) => settle.reject(error));
+		up.end(requestBody);
+	})().catch(settle.reject);
+	done.catch(async (error) => {
+		recordColdBuildOutcome(error);
+		if (error) log("error", "cold_build_failed", {
+			repo,
+			error: String(error)
+		});
+		await rm(temp, {
+			recursive: true,
+			force: true
+		}).catch((_error) => log("debug", "cleanup_failed", { path: temp }));
+	}).finally(() => {
+		coldLeaders.delete(repo);
+		advertisements.delete(repo);
+		if (shouldBackfillAfterPassthrough({
+			cacheable: wantCache,
+			sha256: isSha256
+		})) backfillMirror(repo, upstreamUrl, credHeader);
+	});
+}
+async function refreshMirror(repo, local, credHeader = null) {
+	await runGit([
+		"--git-dir",
+		local,
+		"config",
+		"uploadpack.allowFilter",
+		"true"
+	]);
+	await runGit([
+		"--git-dir",
+		local,
+		"config",
+		"uploadpack.allowAnySHA1InWant",
+		"true"
+	]);
+	await disableAutoMaintenance(local);
+	await runGit(upstreamGitArgs([
+		"--git-dir",
+		local,
+		"fetch",
+		"--quiet",
+		"--prune",
+		"--prune-tags",
+		"origin"
+	]), { env: {
+		...GIT_ENV,
+		...upstreamGitCredentialEnv(credHeader)
+	} });
+	await writeMeta(local);
+	metrics.refreshes++;
+	log("info", "refresh", { repo });
+	return local;
+}
+async function ensureWarm(repo, credHeader = null) {
+	const local = localPath(repo);
+	const lastFetchMs = (await readMeta(local))?.lastFetchMs ?? 0;
+	if (!((Date.now() - lastFetchMs) / 1e3 >= config.ttlSeconds || lastFetchMs < invalidateBeforeMs)) {
+		metrics.warm_hits++;
+		return {
+			local,
+			cacheState: "HIT"
+		};
+	}
+	const mustBlock = lastFetchMs < invalidateBeforeMs;
+	if (!inflightRefresh.has(repo)) inflightRefresh.set(repo, withRepoLock(repo, "write", () => refreshMirror(repo, local, credHeader)).then((result) => {
+		if (result === null) {
+			metrics.refresh_deferred++;
+			log("info", "refresh_deferred", { repo });
+		}
+	}).catch((error) => {
+		metrics.refresh_failures++;
+		log("warn", "refresh_failed", {
+			repo,
+			error: String(error)
+		});
+	}).finally(() => inflightRefresh.delete(repo)));
+	if (mustBlock) {
+		await inflightRefresh.get(repo);
+		if (((await readMeta(local))?.lastFetchMs ?? 0) < invalidateBeforeMs) throw new Error("mirror refresh failed after push invalidation");
+		return {
+			local,
+			cacheState: "REFRESH"
+		};
+	}
+	return {
+		local,
+		cacheState: "STALE"
+	};
+}
+/**
+* Translate the client's `Git-Protocol` header into the environment variable
+* `git-upload-pack` reads it from. Absent header means v0, which is git's own
+* default, so nothing is set.
+*/
+function gitProtocolEnv(headers) {
+	const raw = headers["git-protocol"];
+	const value = Array.isArray(raw) ? raw[0] : raw;
+	return value ? { GIT_PROTOCOL: value } : {};
+}
+/**
+* True when every OID is already present in the mirror.
+*
+* `git-upload-pack` refuses the whole request with `not our ref <oid>` if a
+* single wanted object is missing, so this is the difference between serving
+* a fetch and failing it. A mirror can legitimately lack a wanted object: the
+* client negotiated against a fresher advertisement — from a sibling task
+* holding its own mirror set, or from the sandbox-local cache tier — and asks
+* for a commit this mirror has not fetched yet.
+*/
+async function mirrorHasObjects(local, oids) {
+	if (oids.length === 0) return true;
+	const unique = [...new Set(oids)];
+	try {
+		const { stdout } = await runGitWithInput([
+			"--git-dir",
+			local,
+			"cat-file",
+			"--batch-check=%(objectname) %(objecttype)"
+		], unique.map((oid) => `${oid}\n`).join(""));
+		return !/\bmissing\b/.test(stdout);
+	} catch (_error) {
+		return false;
+	}
+}
+/** runGit, but with a body written to the child's stdin. */
+function runGitWithInput(args, input) {
+	return new Promise((resolve, reject) => {
+		const child = spawn("git", args, {
+			env: GIT_ENV,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (d) => {
+			if (stdout.length < 256 * 1024) stdout += d;
+		});
+		child.stderr.on("data", (d) => {
+			if (stderr.length < 256 * 1024) stderr += d;
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) resolve({
+				stdout,
+				stderr
+			});
+			else reject(/* @__PURE__ */ new Error(`git exited ${code}: ${stderr.trim()}`));
+		});
+		child.stdin.on("error", (error) => {
+			if (errnoCode(error) !== "EPIPE") reject(error);
+		});
+		child.stdin.end(input);
+	});
+}
+/**
+* Forward an already-buffered `git-upload-pack` POST to origin and stream the
+* response straight back, for a fetch this cache cannot serve itself.
+*/
+function proxyUploadPackWithBody(res, upstreamUrl, reqHeaders, body, credHeader) {
+	const up = requestUpstream(new URL(upstreamUrl + "/git-upload-pack"), {
+		method: "POST",
+		headers: withCredential(copyRequestHeaders(reqHeaders), credHeader)
+	}, (upRes) => {
+		res.writeHead(upRes.statusCode, upRes.headers);
+		upRes.pipe(res);
+	});
+	up.on("error", () => {
+		metrics.upstream_errors++;
+		if (!res.headersSent) res.writeHead(502);
+		res.end();
+	});
+	up.end(body);
+}
+function serveUploadPack(req, res, local, advertise, cacheState, body = null) {
+	const args = ["--stateless-rpc"];
+	if (advertise) args.push("--advertise-refs");
+	args.push(local);
+	const child = spawn("git-upload-pack", args, {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		env: {
+			...GIT_ENV,
+			...gitProtocolEnv(req.headers)
+		}
+	});
+	res.statusCode = 200;
+	res.setHeader("Cache-Control", "no-store");
+	res.setHeader("X-Git-Cache", cacheState);
+	res.setHeader("Content-Type", advertise ? "application/x-git-upload-pack-advertisement" : "application/x-git-upload-pack-result");
+	if (advertise) {
+		res.write("001e# service=git-upload-pack\n0000");
+		child.stdin.end();
+	} else if (body !== null) child.stdin.end(body);
+	else if ((req.headers["content-encoding"] || "").toLowerCase() === "gzip") {
+		const gunzip = createGunzip();
+		req.pipe(gunzip).pipe(child.stdin);
+	} else req.pipe(child.stdin);
+	child.stdout.pipe(res);
+	let stderr = "";
+	let finished = false;
+	child.stderr.on("data", (d) => {
+		if (stderr.length < 64 * 1024) stderr += d;
+	});
+	child.on("close", (code) => {
+		finished = true;
+		if (code !== 0) log("error", "upload_pack_failed", {
+			local,
+			code,
+			stderr: stderr.trim()
+		});
+		if (!res.writableEnded) res.end();
+	});
+	res.on("close", () => {
+		if (!finished && !child.killed) child.kill("SIGTERM");
+	});
+}
+async function dirSize(dir) {
+	let total = 0;
+	const stack = [dir];
+	while (stack.length) {
+		const cur = stack.pop();
+		if (cur === void 0) continue;
+		let entries;
+		try {
+			entries = await readdir(cur, { withFileTypes: true });
+		} catch (_error) {
+			continue;
+		}
+		for (const e of entries) {
+			const p = path.join(cur, e.name);
+			if (e.isDirectory()) stack.push(p);
+			else try {
+				total += (await stat(p)).size;
+			} catch (_error) {}
+		}
+	}
+	return total;
+}
+/**
+* Invert localPath(): recover the cache's repo key ("host/owner/repo") from a
+* mirror's filesystem path. coldLeaders/inflightRefresh are keyed by repo, so
+* eviction must compare in repo-space — comparing the raw path against those
+* sets silently never matches, and eviction could rm a mirror that is mid-cold
+* publication or mid-refresh.
+*/
+function repoFromMirrorPath(mirrorPath) {
+	const root = path.join(config.cacheDir, "mirrors");
+	return path.relative(root, mirrorPath).replace(/\.git$/, "");
+}
+async function listMirrors() {
+	const root = path.join(config.cacheDir, "mirrors");
+	const out = [];
+	const stack = [root];
+	while (stack.length) {
+		const cur = stack.pop();
+		if (cur === void 0) continue;
+		let entries;
+		try {
+			entries = await readdir(cur, { withFileTypes: true });
+		} catch (_error) {
+			continue;
+		}
+		for (const e of entries) {
+			const p = path.join(cur, e.name);
+			if (e.isDirectory() && e.name.endsWith(".git")) out.push(p);
+			else if (e.isDirectory()) stack.push(p);
+		}
+	}
+	return out;
+}
+let evicting = false;
+async function maybeEvict() {
+	if (!config.maxCacheBytes || evicting) return;
+	evicting = true;
+	try {
+		const mirrors = await listMirrors();
+		let total = 0;
+		const sized = [];
+		for (const m of mirrors) {
+			const size = await dirSize(m);
+			const meta = await readMeta(m);
+			total += size;
+			sized.push({
+				m,
+				size,
+				lastFetchMs: meta?.lastFetchMs ?? 0,
+				lastServedMs: await readLastServedMs(m)
+			});
+		}
+		if (total <= config.maxCacheBytes) return;
+		sized.sort((a, b) => a.lastFetchMs - b.lastFetchMs);
+		for (const entry of sized) {
+			if (total <= config.maxCacheBytes) break;
+			const repo = repoFromMirrorPath(entry.m);
+			if (coldLeaders.has(repo) || inflightRefresh.has(repo)) continue;
+			if (Date.now() - entry.lastServedMs < EVICTION_QUIET_MS) continue;
+			if (await withRepoLock(repo, "write", async () => {
+				await rm(entry.m, {
+					recursive: true,
+					force: true
+				});
+				await rm(metaPath(entry.m), { force: true }).catch((_error) => log("debug", "meta_cleanup_failed", {}));
+				await rm(servedMarkerPath(entry.m), { force: true }).catch((_error) => log("debug", "served_cleanup_failed", {}));
+				return true;
+			}) === null) continue;
+			total -= entry.size;
+			metrics.evictions++;
+			log("info", "evict", {
+				mirror: entry.m,
+				freed: entry.size
+			});
+		}
+	} finally {
+		evicting = false;
+	}
+}
+async function cleanupQuarantine() {
+	const q = path.join(config.cacheDir, "quarantine");
+	await rm(q, {
+		recursive: true,
+		force: true
+	}).catch((_error) => log("debug", "quarantine_clear_failed", {}));
+	await mkdir(q, { recursive: true }).catch((_error) => log("debug", "quarantine_mkdir_failed", {}));
+}
+function readBody(req, limit) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (c) => {
+			size += c.length;
+			if (size > limit) {
+				reject(/* @__PURE__ */ new Error("request body too large"));
+				req.destroy();
+				return;
+			}
+			chunks.push(c);
+		});
+		req.on("end", () => resolve(Buffer.concat(chunks)));
+		req.on("error", reject);
+	});
+}
+/** True when the TCP peer of this request is the local machine itself. */
+function isLoopbackPeer(req) {
+	const addr = req.socket.remoteAddress;
+	return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
+}
+async function handle(req, res) {
+	const parsed = new URL(req.url, "http://git-cache.local");
+	if (parsed.pathname === "/healthz") {
+		res.writeHead(200, { "Content-Type": "application/json" });
+		return res.end(JSON.stringify({
+			ok: true,
+			bind: config.bindHost,
+			cacheDir: config.cacheDir,
+			ttlSeconds: config.ttlSeconds,
+			privateRepos: Boolean(config.credentialHelper),
+			authMode: config.authMode,
+			coldMode: "stream-through",
+			invalidateBeforeMs
+		}));
+	}
+	if (parsed.pathname === "/metrics") {
+		res.writeHead(200, { "Content-Type": "application/json" });
+		return res.end(JSON.stringify(metricsSnapshot()));
+	}
+	if (parsed.pathname === "/invalidate-all" && req.method === "POST") {
+		if (config.authMode === "check-through" && !isLoopbackPeer(req)) {
+			metrics.auth_denials++;
+			log("info", "invalidate_all_denied", { peer: req.socket.remoteAddress ?? null });
+			res.writeHead(403, { "Content-Type": "text/plain" });
+			return res.end("invalidate-all is operator-only on a shared cache\n");
+		}
+		invalidateBeforeMs = Date.now();
+		metrics.invalidations++;
+		log("info", "invalidate_all", {});
+		res.writeHead(204);
+		return res.end();
+	}
+	const up = parseUpstream(parsed.pathname, parsed.search);
+	if (up && up.redirect !== void 0) {
+		if (up.operation === "lfs") metrics.lfs_redirects++;
+		else metrics.credential_url_redirects++;
+		log("info", "upstream_redirect", { op: up.operation });
+		res.writeHead(307, { Location: up.redirect });
+		return res.end();
+	}
+	if (!up || !("repo" in up) || !validateMethod(req, up.operation)) {
+		metrics.bad_requests++;
+		log("debug", "bad_request", {
+			pathname: parsed.pathname,
+			method: req.method,
+			parsed: up ? up.operation : null
+		});
+		const hint = up ? null : explainRejection(parsed.pathname);
+		res.writeHead(404, { "Content-Type": "text/plain" });
+		return res.end(hint ? `git-cache: ${hint}; this remote cannot be proxied — run \`git-cache disable\` to have git talk to it directly\n` : "git cache endpoint\n");
+	}
+	try {
+		let clientCred = null;
+		if (config.authMode === "check-through") {
+			const header = req.headers["authorization"];
+			const raw = Array.isArray(header) ? header[0] : header;
+			if (!raw) {
+				metrics.auth_denials++;
+				res.writeHead(401, {
+					"Content-Type": "text/plain",
+					"WWW-Authenticate": "Basic realm=\"git-cache\""
+				});
+				return res.end("authentication required\n");
+			}
+			const verdict = await authorizeCheckThrough(raw, up.repo, up.upstreamUrl);
+			if (!verdict.allowed) {
+				log("info", "auth_denied", {
+					repo: up.repo,
+					status: verdict.status
+				});
+				res.writeHead(verdict.status, { "Content-Type": "text/plain" });
+				return res.end("not authorized for this repository\n");
+			}
+			clientCred = raw;
+		}
+		const host = up.repo.split("/")[0];
+		let uploadBody = null;
+		let uploadWants = [];
+		if (up.operation === "git-upload-pack") {
+			try {
+				uploadBody = await readBody(req, 16 * 1024 * 1024);
+			} catch (_error) {
+				metrics.bad_requests++;
+				if (!res.headersSent) res.writeHead(413);
+				return res.end("request too large\n");
+			}
+			if ((req.headers["content-encoding"] || "").toLowerCase() === "gzip") try {
+				uploadBody = Buffer.from(await gunzip$1(uploadBody));
+			} catch (_error) {
+				metrics.bad_requests++;
+				if (!res.headersSent) res.writeHead(400);
+				return res.end("bad gzip body\n");
+			}
+			uploadWants = classifyUploadRequest(uploadBody).wants;
+		}
+		if (await pathExists(localPath(up.repo))) {
+			const warm = await ensureWarm(up.repo, clientCred);
+			markServed(warm.local);
+			if (up.operation === "git-upload-pack" && !await mirrorHasObjects(warm.local, uploadWants)) {
+				await refreshMirror(up.repo, warm.local, clientCred).catch((error) => {
+					metrics.refresh_failures++;
+					log("warn", "refresh_failed", {
+						repo: up.repo,
+						error: String(error)
+					});
+				});
+				if (!await mirrorHasObjects(warm.local, uploadWants)) {
+					metrics.passthrough_missing_want++;
+					log("info", "passthrough_missing_want", { repo: up.repo });
+					const credHeader = clientCred ?? await fetchCredentialHeader(host);
+					return proxyUploadPackWithBody(res, up.upstreamUrl, req.headers, uploadBody, credHeader);
+				}
+			}
+			log("info", "serve", {
+				repo: up.repo,
+				op: up.operation,
+				state: warm.cacheState
+			});
+			return serveUploadPack(req, res, warm.local, up.operation === "info/refs", warm.cacheState, uploadBody);
+		}
+		if (up.operation === "info/refs") {
+			const credHeader = clientCred ?? await fetchCredentialHeader(host);
+			return await new Promise((resolve, reject) => {
+				openUpstream(req, up.upstreamUrl, up.operation, (upRes, error) => {
+					if (error) {
+						reject(error);
+						return;
+					}
+					if (upRes.statusCode === 401 || upRes.statusCode === 403) dropCredential(host);
+					res.writeHead(upRes.statusCode, upRes.headers);
+					const chunks = [];
+					let bytes = 0;
+					const CAP = 32 * 1024 * 1024;
+					upRes.on("data", (chunk) => {
+						res.write(chunk);
+						if (bytes < CAP) {
+							chunks.push(chunk);
+							bytes += chunk.length;
+						}
+					});
+					upRes.on("end", () => {
+						res.end();
+						if (upRes.statusCode === 200 && bytes < CAP && gitProtocolEnv(req.headers).GIT_PROTOCOL === void 0) advertisements.set(up.repo, parseAdvertisement(Buffer.concat(chunks)));
+						resolve(void 0);
+					});
+					upRes.on("error", reject);
+				}, credHeader);
+			});
+		}
+		const body = uploadBody ?? Buffer.alloc(0);
+		const credHeader = clientCred ?? await fetchCredentialHeader(host);
+		if (coldLeaders.has(up.repo)) return proxyColdFollowerWithBody(res, up.upstreamUrl, req.headers, body, up.repo, credHeader);
+		return startColdStream(req, res, up.upstreamUrl, up.repo, body, credHeader);
+	} catch (error) {
+		metrics.upstream_errors++;
+		log("error", "request_failed", { error: String(error) });
+		if (!res.headersSent) res.writeHead(502, { "Content-Type": "text/plain" });
+		res.end("unable to serve repository\n");
+	}
+}
+/** A follower whose body we already buffered (leader path buffers too). */
+function proxyColdFollowerWithBody(res, upstreamUrl, reqHeaders, body, repo, credHeader) {
+	metrics.cold_followers++;
+	log("info", "cold_follower", { repo });
+	const up = requestUpstream(new URL(upstreamUrl + "/git-upload-pack"), {
+		method: "POST",
+		headers: withCredential(copyRequestHeaders(reqHeaders), credHeader)
+	}, (upRes) => {
+		res.writeHead(upRes.statusCode, upRes.headers);
+		upRes.pipe(res);
+	});
+	up.on("error", () => {
+		metrics.upstream_errors++;
+		if (!res.headersSent) res.writeHead(502);
+		res.end();
+	});
+	up.end(body);
+}
+async function startServer(options = {}) {
+	if (options.authMode !== void 0) config.authMode = options.authMode;
+	if (options.bindHost !== void 0) config.bindHost = options.bindHost;
+	if (options.port !== void 0) config.port = options.port;
+	if (options.cacheDir !== void 0) config.cacheDir = options.cacheDir;
+	if (options.maxCacheBytes !== void 0) config.maxCacheBytes = options.maxCacheBytes;
+	if (options.credentialHelper !== void 0) config.credentialHelper = options.credentialHelper;
+	if (!(config.bindHost === "127.0.0.1" || config.bindHost === "::1" || config.bindHost === "localhost") && config.authMode !== "check-through") throw new Error(`git-cache: refusing to bind ${config.bindHost} without check-through authorization — a non-loopback trusted-client cache would serve every mirrored repo to anyone who can reach it. Set authMode: 'check-through' (or GIT_CACHE_AUTH_MODE=check-through), or bind loopback.`);
+	if (config.authMode === "check-through" && config.credentialHelper) throw new Error("git-cache: credentialHelper is incompatible with check-through authorization — upstream requests authenticate with each client's own credential.");
+	await mkdir(path.join(config.cacheDir, "mirrors"), { recursive: true });
+	await cleanupQuarantine();
+	const server = http.createServer((req, res) => {
+		handle(req, res).catch((error) => {
+			log("error", "unhandled", { error: String(error) });
+			if (!res.headersSent) res.writeHead(500);
+			res.end();
+		});
+	});
+	server.requestTimeout = 360 * 60 * 1e3;
+	server.headersTimeout = 60 * 1e3;
+	server.keepAliveTimeout = 65 * 1e3;
+	await new Promise((resolve) => server.listen(config.port, config.bindHost, () => resolve(void 0)));
+	log("info", "listening", {
+		bind: `${config.bindHost}:${config.port}`,
+		cacheDir: config.cacheDir,
+		ttlSeconds: config.ttlSeconds,
+		private: Boolean(config.credentialHelper),
+		authMode: config.authMode
+	});
+	const shutdown = () => {
+		log("info", "shutdown", {});
+		server.close(() => process.exit(0));
+		setTimeout(() => process.exit(0), 5e3).unref();
+	};
+	process.on("SIGTERM", shutdown);
+	process.on("SIGINT", shutdown);
+}
+//#endregion
+export { isProtocolV2Request as a, parseAdvertisement as c, shouldBackfillAfterPassthrough as d, startServer as f, explainRejection as i, parseUpstream as l, classifyUploadRequest as n, metricsSnapshot as o, copyRequestHeaders as r, mirrorHasObjects as s, SidebandPackExtractor as t, recordColdBuildOutcome as u };