The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(server): authenticate server-side git clone and fetch with a company-secret GitHub token (#10720)
Devin Foleye0c244826772
diff --git a/docs/deploy/secrets.md b/docs/deploy/secrets.mdindex 0d6591574a..e557086ebf 100644--- a/docs/deploy/secrets.md+++ b/docs/deploy/secrets.md@@ -51,6 +51,13 @@ Project env applies to every issue run in that project. When a project env keymatches an agent env key, the project value wins before Paperclip injects itsown `PAPERCLIP_*` runtime variables.+Separately from env bindings, the **server itself** consumes a company secret+named `GITHUB_TOKEN`, `GH_TOKEN`, or `PAPERCLIP_GITHUB_TOKEN` (by name, no+binding needed) to authenticate server-side git operations — cloning private+GitHub repos for repo-only project workspaces and refreshing worktree base+refs. See+[Execution workspaces](../guides/board-operator/execution-workspaces-and-runtime-services.md#private-repositories-and-repo-only-project-workspaces).+## User-Specific SecretsUser-specific secrets let a shared agent or project declare a slot such asdiff --git a/docs/guides/board-operator/execution-workspaces-and-runtime-services.md b/docs/guides/board-operator/execution-workspaces-and-runtime-services.mdindex 1b0394d52f..6d4e927400 100644--- a/docs/guides/board-operator/execution-workspaces-and-runtime-services.md+++ b/docs/guides/board-operator/execution-workspaces-and-runtime-services.md@@ -77,6 +77,32 @@ Some workspaces need heavy one-time setup — seeding a database, warming caches- **Provisioning failed** — the command failed; the workspace detail links to the runtime logs for the failing operation.- While the command runs, the runtime service shows a **Provisioning…** state before it transitions to starting/running.+## Private repositories and repo-only project workspaces++A project workspace can be **repo-only**: a `Repo URL` with no local path. The server then+materializes a managed checkout on demand (`git clone` into a managed directory) and, for+isolated `git_worktree` runs, refreshes the base ref (`git fetch`) before preparing each+worktree. Both operations run on the server, outside any agent process — so agent-scoped+credential env bindings do not apply to them.++For **private GitHub repositories**, store a token as a **company secret** named one of+`GITHUB_TOKEN`, `GH_TOKEN`, or `PAPERCLIP_GITHUB_TOKEN` (checked in that order; Settings →+Secrets). The server resolves it per run and authenticates managed clones and base-ref+fetches with it. Details and caveats:++- Scope: only `https://github.com/...` repo URLs are authenticated this way. SSH URLs, GitHub+ Enterprise hosts, and other providers keep ambient behavior (system git config/credential+ helpers on the server host). URLs that embed their own credentials are never overridden.+- Fallback: with no matching company secret, the server falls back to a `GITHUB_TOKEN` or+ `GH_TOKEN` variable in the **server process environment** (useful for self-hosted single-tenant+ deployments), then to unauthenticated access — public repos keep working with no setup.+- The token never appears in command lines, URLs, or on disk; it is passed to git through an+ ephemeral credential helper. Each resolution is recorded as a secret access event.+- This is separate from the **agent push credential**: agents pushing branches/PRs still need+ `GH_TOKEN`/`GITHUB_TOKEN` bound at agent or project scope (see+ [deploy/secrets](../../deploy/secrets.md)) so the token reaches the agent process env. The+ same company secret can back both uses via a binding.+## Cross-run persistence (no-remote-git contract)Code state moves between runs through the local execution-workspace cwd alone — not through a git remote.diff --git a/server/src/__tests__/git-credentials.test.ts b/server/src/__tests__/git-credentials.test.tsnew file mode 100644index 0000000000..17fed11736--- /dev/null+++ b/server/src/__tests__/git-credentials.test.ts@@ -0,0 +1,285 @@+import { spawn } from "node:child_process";+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { describe, expect, it, vi } from "vitest";+import type { Db } from "@paperclipai/db";+import {+ DEFAULT_GITHUB_TOKEN_SECRET_NAMES,+ GIT_CREDENTIAL_TOKEN_ENV_KEY,+ buildGitAuthInvocation,+ createGitRemoteAuthProvider,+ describeGitAuthFailure,+ isGitHubHttpsRemoteUrl,+ scrubGitCredentialText,+} from "../services/git-credentials.ts";++const fakeDb = null as unknown as Db;++function buildSecretsFake(byName: Record<string, string | Error>) {+ const getByName = vi.fn(async (_companyId: string, name: string) => {+ if (!(name in byName)) return null;+ return { id: `secret-${name}` };+ });+ const resolveSecretValue = vi.fn(async (_companyId: string, secretId: string) => {+ const name = secretId.replace(/^secret-/, "");+ const value = byName[name];+ if (value instanceof Error) throw value;+ return value ?? "";+ });+ return { getByName, resolveSecretValue };+}++describe("isGitHubHttpsRemoteUrl", () => {+ it("accepts https github.com and www.github.com URLs", () => {+ expect(isGitHubHttpsRemoteUrl("https://github.com/example/repo.git")).toBe(true);+ expect(isGitHubHttpsRemoteUrl("https://www.github.com/example/repo.git")).toBe(true);+ });++ it("rejects ssh, http, enterprise hosts, other providers, userinfo URLs, and non-URLs", () => {+ expect(isGitHubHttpsRemoteUrl("[email protected]:example/repo.git")).toBe(false);+ expect(isGitHubHttpsRemoteUrl("ssh://[email protected]/example/repo.git")).toBe(false);+ expect(isGitHubHttpsRemoteUrl("http://github.com/example/repo.git")).toBe(false);+ expect(isGitHubHttpsRemoteUrl("https://github.enterprise.example/org/repo.git")).toBe(false);+ expect(isGitHubHttpsRemoteUrl("https://gitlab.com/example/repo.git")).toBe(false);+ expect(isGitHubHttpsRemoteUrl("https://alice:[email protected]/example/repo.git")).toBe(false);+ expect(isGitHubHttpsRemoteUrl("/local/path/repo.git")).toBe(false);+ });+});++describe("createGitRemoteAuthProvider", () => {+ const githubUrl = "https://github.com/example/repo.git";++ it("prefers company secrets in declared order", async () => {+ const secrets = buildSecretsFake({ GH_TOKEN: "gh-token", PAPERCLIP_GITHUB_TOKEN: "pc-token" });+ const provider = createGitRemoteAuthProvider(fakeDb, "company-1", undefined, {+ secrets,+ env: { GITHUB_TOKEN: "env-token" },+ });+ const invocation = await provider(githubUrl);+ expect(invocation?.env[GIT_CREDENTIAL_TOKEN_ENV_KEY]).toBe("gh-token");+ expect(invocation?.source).toBe("company_secret");+ expect(invocation?.secretName).toBe("GH_TOKEN");+ // GITHUB_TOKEN is probed first even though only GH_TOKEN exists.+ expect(secrets.getByName.mock.calls.map((call) => call[1])).toEqual(["GITHUB_TOKEN", "GH_TOKEN"]);+ });++ it("falls back to the server env, GITHUB_TOKEN before GH_TOKEN", async () => {+ const provider = createGitRemoteAuthProvider(fakeDb, "company-1", undefined, {+ secrets: buildSecretsFake({}),+ env: { GITHUB_TOKEN: "env-github", GH_TOKEN: "env-gh" },+ });+ const invocation = await provider(githubUrl);+ expect(invocation?.env[GIT_CREDENTIAL_TOKEN_ENV_KEY]).toBe("env-github");+ expect(invocation?.source).toBe("server_env");+ expect(invocation?.secretName).toBeNull();+ });++ it("returns null when no token is available anywhere", async () => {+ const provider = createGitRemoteAuthProvider(fakeDb, "company-1", undefined, {+ secrets: buildSecretsFake({}),+ env: {},+ });+ await expect(provider(githubUrl)).resolves.toBeNull();+ });++ it("returns null for out-of-scope URLs without touching the secret store", async () => {+ const secrets = buildSecretsFake({ GITHUB_TOKEN: "token" });+ const provider = createGitRemoteAuthProvider(fakeDb, "company-1", undefined, {+ secrets,+ env: {},+ });+ await expect(provider("[email protected]:example/repo.git")).resolves.toBeNull();+ await expect(provider("https://gitlab.com/example/repo.git")).resolves.toBeNull();+ expect(secrets.getByName).not.toHaveBeenCalled();+ });++ it("memoizes the credential lookup across calls", async () => {+ const secrets = buildSecretsFake({ GITHUB_TOKEN: "token" });+ const provider = createGitRemoteAuthProvider(fakeDb, "company-1", undefined, {+ secrets,+ env: {},+ });+ await provider(githubUrl);+ await provider(githubUrl);+ await provider("https://github.com/example/another.git");+ expect(secrets.getByName).toHaveBeenCalledTimes(1);+ expect(secrets.resolveSecretValue).toHaveBeenCalledTimes(1);+ });++ it("passes a system access context so resolution is audited", async () => {+ const secrets = buildSecretsFake({ GITHUB_TOKEN: "token" });+ const provider = createGitRemoteAuthProvider(+ fakeDb,+ "company-1",+ { issueId: "issue-1", heartbeatRunId: "run-1" },+ { secrets, env: {} },+ );+ await provider(githubUrl);+ expect(secrets.resolveSecretValue).toHaveBeenCalledWith("company-1", "secret-GITHUB_TOKEN", "latest", {+ accessContext: expect.objectContaining({+ consumerType: "system",+ consumerId: "workspace-git-credential",+ actorType: "system",+ issueId: "issue-1",+ heartbeatRunId: "run-1",+ }),+ });+ });++ it("continues down the chain when one secret fails to resolve", async () => {+ const secrets = buildSecretsFake({+ GITHUB_TOKEN: new Error("provider outage"),+ GH_TOKEN: "gh-token",+ });+ const provider = createGitRemoteAuthProvider(fakeDb, "company-1", undefined, {+ secrets,+ env: {},+ });+ const invocation = await provider(githubUrl);+ expect(invocation?.secretName).toBe("GH_TOKEN");+ });+});++describe("buildGitAuthInvocation", () => {+ it("keeps the token out of argv and installs the helper URL-scoped to github.com", () => {+ const invocation = buildGitAuthInvocation({+ token: "super-secret-token",+ source: "company_secret",+ secretName: "GITHUB_TOKEN",+ });+ expect(invocation.configArgs.join(" ")).not.toContain("super-secret-token");+ expect(invocation.configArgs[0]).toBe("-c");+ expect(invocation.configArgs[1]).toBe("credential.helper=");+ expect(invocation.configArgs[3]).toContain("credential.https://github.com.helper=");+ expect(invocation.configArgs[3]).toContain("x-access-token");+ expect(invocation.configArgs[5]).toContain("credential.https://www.github.com.helper=");+ expect(invocation.env[GIT_CREDENTIAL_TOKEN_ENV_KEY]).toBe("super-secret-token");+ expect(invocation.env.GIT_TERMINAL_PROMPT).toBe("0");+ });+});++describe("credential helper execution (real git, no network)", () => {+ async function runCredentialFill(description: string) {+ const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-git-cred-fill-"));+ try {+ const invocation = buildGitAuthInvocation({+ token: "abc123",+ source: "company_secret",+ secretName: "GITHUB_TOKEN",+ });+ return await new Promise<{ code: number | null; stdout: string; stderr: string }>(+ (resolve, reject) => {+ const child = spawn("git", [...invocation.configArgs, "credential", "fill"], {+ cwd,+ env: { ...process.env, ...invocation.env },+ stdio: ["pipe", "pipe", "pipe"],+ });+ let stdout = "";+ let stderr = "";+ child.stdout.on("data", (chunk) => { stdout += String(chunk); });+ child.stderr.on("data", (chunk) => { stderr += String(chunk); });+ child.on("error", reject);+ child.on("close", (code) => resolve({ code, stdout, stderr }));+ child.stdin.write(description);+ child.stdin.end();+ },+ );+ } finally {+ await fs.rm(cwd, { recursive: true, force: true });+ }+ }++ it("answers a github.com https request with the env-carried token", async () => {+ const result = await runCredentialFill("protocol=https\nhost=github.com\n\n");+ expect(result.code).toBe(0);+ expect(result.stdout).toContain("username=x-access-token");+ expect(result.stdout).toContain("password=abc123");+ });++ it("never hands the token to another host, even if git asks", async () => {+ // Simulates a request whose effective host changed after our pre-invocation URL check+ // (for example a repository-local url.<base>.insteadOf rewrite): the URL-scoped helper+ // config keeps git from consulting the helper, prompts are disabled, so the fill fails+ // and the token is never emitted.+ const result = await runCredentialFill("protocol=https\nhost=evil.example\n\n");+ expect(result.code).not.toBe(0);+ expect(result.stdout).not.toContain("abc123");+ });++ it("never answers plain-http requests for github.com", async () => {+ const result = await runCredentialFill("protocol=http\nhost=github.com\n\n");+ expect(result.code).not.toBe(0);+ expect(result.stdout).not.toContain("abc123");+ });+});++describe("scrubGitCredentialText", () => {+ it("masks URL userinfo", () => {+ expect(scrubGitCredentialText("https://x-access-token:[email protected]/a/b.git")).toBe(+ "https://***@github.com/a/b.git",+ );+ });++ it("masks userinfo on non-HTTP schemes, leaving scp-style remotes alone", () => {+ expect(scrubGitCredentialText("ssh://deploy:[email protected]/repo.git")).toBe(+ "ssh://***@internal.example/repo.git",+ );+ expect(scrubGitCredentialText("[email protected]:example/repo.git")).toBe(+ "[email protected]:example/repo.git",+ );+ });++ it("masks entire URL query strings regardless of parameter names", () => {+ expect(scrubGitCredentialText("https://github.com/a/b.git?access_token=ghs_secret&ref=main")).toBe(+ "https://github.com/a/b.git?***",+ );+ expect(scrubGitCredentialText("https://host.example/r.git?obscure_cred_name=secret")).toBe(+ "https://host.example/r.git?***",+ );+ });++ it("leaves credential-free text unchanged", () => {+ expect(scrubGitCredentialText("fatal: repository not found")).toBe("fatal: repository not found");+ });+});++describe("describeGitAuthFailure", () => {+ it("names the company secret when a stored credential was used", () => {+ expect(describeGitAuthFailure({+ error: "fatal: Authentication failed",+ used: { source: "company_secret", secretName: "GH_TOKEN" },+ })).toContain("the GH_TOKEN company-secret GitHub credential");+ });++ it("names the server environment when an env credential was used", () => {+ expect(describeGitAuthFailure({+ error: "fatal: Authentication failed",+ used: { source: "server_env", secretName: null },+ })).toContain("server-environment GitHub credential");+ });++ it("points at Settings → Secrets for auth-looking failures without a credential", () => {+ expect(describeGitAuthFailure({+ error: "fatal: could not read Username for 'https://github.com': terminal prompts disabled",+ used: null,+ })).toContain("add a GITHUB_TOKEN or GH_TOKEN company secret");+ });++ it("stays silent for non-auth failures without a credential", () => {+ expect(describeGitAuthFailure({+ error: "fatal: unable to resolve host example.invalid",+ used: null,+ })).toBeNull();+ });+});++describe("DEFAULT_GITHUB_TOKEN_SECRET_NAMES", () => {+ it("keeps the shared name order stable", () => {+ expect([...DEFAULT_GITHUB_TOKEN_SECRET_NAMES]).toEqual([+ "GITHUB_TOKEN",+ "GH_TOKEN",+ "PAPERCLIP_GITHUB_TOKEN",+ ]);+ });+});diff --git a/server/src/__tests__/heartbeat-managed-clone-credentials.test.ts b/server/src/__tests__/heartbeat-managed-clone-credentials.test.tsnew file mode 100644index 0000000000..146a11df50--- /dev/null+++ b/server/src/__tests__/heartbeat-managed-clone-credentials.test.ts@@ -0,0 +1,161 @@+import { execFile as execFileCallback } from "node:child_process";+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { promisify } from "node:util";+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";+import { ensureManagedProjectWorkspace } from "../services/heartbeat.ts";+import { buildGitAuthInvocation, GIT_CREDENTIAL_TOKEN_ENV_KEY } from "../services/git-credentials.ts";+import { sanitizeRuntimeServiceBaseEnv } from "../services/workspace-runtime.ts";+import { resolveManagedProjectWorkspaceDir } from "../home-paths.ts";++const execFile = promisify(execFileCallback);++let tempHome: string;+let originalHome: string | undefined;++beforeAll(async () => {+ originalHome = process.env.PAPERCLIP_HOME;+ tempHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-managed-clone-"));+ process.env.PAPERCLIP_HOME = tempHome;+});++afterAll(async () => {+ if (originalHome === undefined) delete process.env.PAPERCLIP_HOME;+ else process.env.PAPERCLIP_HOME = originalHome;+ await fs.rm(tempHome, { recursive: true, force: true });+});++async function createLocalSourceRepo() {+ const sourceRepo = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-clone-source-"));+ await execFile("git", ["init"], { cwd: sourceRepo });+ await execFile("git", ["config", "user.email", "[email protected]"], { cwd: sourceRepo });+ await execFile("git", ["config", "user.name", "Paperclip Test"], { cwd: sourceRepo });+ await fs.writeFile(path.join(sourceRepo, "README.md"), "hello\n", "utf8");+ await execFile("git", ["add", "README.md"], { cwd: sourceRepo });+ await execFile("git", ["commit", "-m", "init"], { cwd: sourceRepo });+ return sourceRepo;+}++describe("ensureManagedProjectWorkspace clone credentials", () => {+ it("clones exactly as before when no auth provider is configured", async () => {+ const sourceRepo = await createLocalSourceRepo();+ try {+ const result = await ensureManagedProjectWorkspace({+ companyId: "company-noauth",+ projectId: "project-1",+ repoUrl: sourceRepo,+ });+ expect(result.warning).toBeNull();+ const gitDir = await fs.stat(path.join(result.cwd, ".git"));+ expect(gitDir.isDirectory()).toBe(true);+ } finally {+ await fs.rm(sourceRepo, { recursive: true, force: true });+ }+ });++ it("consults the provider with the repo URL and clones normally when it returns null", async () => {+ const sourceRepo = await createLocalSourceRepo();+ const resolveGitAuth = vi.fn(async () => null);+ try {+ const result = await ensureManagedProjectWorkspace({+ companyId: "company-nullauth",+ projectId: "project-1",+ repoUrl: sourceRepo,+ resolveGitAuth,+ });+ expect(resolveGitAuth).toHaveBeenCalledWith(sourceRepo);+ const gitDir = await fs.stat(path.join(result.cwd, ".git"));+ expect(gitDir.isDirectory()).toBe(true);+ } finally {+ await fs.rm(sourceRepo, { recursive: true, force: true });+ }+ });++ it("names the company-secret credential when an authenticated clone fails", async () => {+ const missingRepo = path.join(os.tmpdir(), "paperclip-definitely-missing", "repo.git");+ const resolveGitAuth = vi.fn(async () => ({+ // Empty configArgs keep this offline: the failure comes from the missing local path,+ // the message must still attribute the credential that was in play.+ configArgs: [],+ env: { [GIT_CREDENTIAL_TOKEN_ENV_KEY]: "token", GIT_TERMINAL_PROMPT: "0" },+ source: "company_secret" as const,+ secretName: "GH_TOKEN",+ }));+ await expect(ensureManagedProjectWorkspace({+ companyId: "company-authfail",+ projectId: "project-1",+ repoUrl: missingRepo,+ resolveGitAuth,+ })).rejects.toThrow(/the GH_TOKEN company-secret GitHub credential/);+ });++ it("does not mention credentials when an unauthenticated clone fails for non-auth reasons", async () => {+ // The Settings → Secrets hint is reserved for auth-shaped failures (covered in+ // git-credentials.test.ts); a plain missing-repo failure must not suggest credentials.+ const missingRepo = path.join(os.tmpdir(), "paperclip-definitely-missing", "repo.git");+ const error = await ensureManagedProjectWorkspace({+ companyId: "company-noauthfail",+ projectId: "project-1",+ repoUrl: missingRepo,+ }).then(+ () => { throw new Error("expected the clone to fail"); },+ (err: unknown) => err as Error,+ );+ expect(error.message).toContain("Failed to prepare managed checkout");+ expect(error.message).not.toContain("company secret");+ });++ it("removes the partially created directory when the clone fails", async () => {+ const missingRepo = path.join(os.tmpdir(), "paperclip-definitely-missing", "repo.git");+ const companyId = "company-cleanup";+ const projectId = "project-1";+ await expect(ensureManagedProjectWorkspace({+ companyId,+ projectId,+ repoUrl: missingRepo,+ })).rejects.toThrow();+ // Filesystem-path repo "URLs" derive no repo name, so the managed dir is the _default slot.+ const cwd = resolveManagedProjectWorkspaceDir({ companyId, projectId });+ await expect(fs.stat(cwd)).rejects.toMatchObject({ code: "ENOENT" });+ });++ it("keeps using a pre-existing non-git directory as-is without attempting a clone", async () => {+ const companyId = "company-existing";+ const projectId = "project-1";+ const sourceRepo = await createLocalSourceRepo();+ try {+ const cwd = resolveManagedProjectWorkspaceDir({ companyId, projectId });+ await fs.mkdir(cwd, { recursive: true });+ await fs.writeFile(path.join(cwd, "keep.txt"), "operator data\n", "utf8");+ const result = await ensureManagedProjectWorkspace({+ companyId,+ projectId,+ repoUrl: sourceRepo,+ });+ expect(result.cwd).toBe(cwd);+ expect(result.warning).toContain("Using it as-is");+ await expect(fs.readFile(path.join(cwd, "keep.txt"), "utf8")).resolves.toBe("operator data\n");+ } finally {+ await fs.rm(sourceRepo, { recursive: true, force: true });+ }+ });++ it("keeps the credential env alive through the sanitizer spread order", () => {+ // The clone env is `{ ...sanitize(process.env), GIT_TERMINAL_PROMPT, ...auth.env }`. The+ // sanitizer strips every PAPERCLIP_* key, so the token env must be spread after it.+ const invocation = buildGitAuthInvocation({+ token: "tok",+ source: "company_secret",+ secretName: "GITHUB_TOKEN",+ });+ const cloneEnv = {+ ...sanitizeRuntimeServiceBaseEnv({ ...process.env, [GIT_CREDENTIAL_TOKEN_ENV_KEY]: "stale" }),+ GIT_TERMINAL_PROMPT: "0",+ ...invocation.env,+ };+ expect(cloneEnv[GIT_CREDENTIAL_TOKEN_ENV_KEY]).toBe("tok");+ expect(sanitizeRuntimeServiceBaseEnv({ [GIT_CREDENTIAL_TOKEN_ENV_KEY]: "stale" })[GIT_CREDENTIAL_TOKEN_ENV_KEY])+ .toBeUndefined();+ });+});diff --git a/server/src/__tests__/workspace-runtime.test.ts b/server/src/__tests__/workspace-runtime.test.tsindex 5543fc1526..447583fff7 100644--- a/server/src/__tests__/workspace-runtime.test.ts+++ b/server/src/__tests__/workspace-runtime.test.ts@@ -34,6 +34,7 @@ import {normalizeAdapterManagedRuntimeServices,reconcilePersistedRuntimeServicesOnStartup,realizeExecutionWorkspace,+ refreshRemoteTrackingBaseRef,releaseRuntimeServicesForRun,resetRuntimeServicesForTests,resolveWorkspaceRuntimeReadinessTimeoutSec,@@ -379,6 +380,42 @@ describe("sanitizeRuntimeServiceBaseEnv", () => {});});+describe("refreshRemoteTrackingBaseRef git auth", () => {+ it("offers the remote URL to the provider and keeps ambient behavior when it returns null", async () => {+ const { remotePath, repoRoot } = await createClonedRepoWithRemote();+ const offeredUrls: string[] = [];+ const warnings = await refreshRemoteTrackingBaseRef(repoRoot, "origin/master", async (remoteUrl) => {+ offeredUrls.push(remoteUrl);+ return null;+ });+ expect(warnings).toEqual([]);+ expect(offeredUrls).toEqual([remotePath]);+ });++ it("attributes a failed authenticated fetch to the credential that was used", async () => {+ const { repoRoot } = await createClonedRepoWithRemote();+ await runGit(repoRoot, ["remote", "set-url", "origin", path.join(os.tmpdir(), "paperclip-missing-remote", "repo.git")]);+ const warnings = await refreshRemoteTrackingBaseRef(repoRoot, "origin/master", async () => ({+ configArgs: [],+ env: { GIT_TERMINAL_PROMPT: "0" },+ source: "company_secret",+ secretName: "GH_TOKEN",+ }));+ expect(warnings).toHaveLength(1);+ expect(warnings[0]).toContain("Could not refresh base ref origin/master");+ expect(warnings[0]).toContain("the GH_TOKEN company-secret GitHub credential");+ });++ it("keeps the unauthenticated failure warning credential-free without a provider", async () => {+ const { repoRoot } = await createClonedRepoWithRemote();+ await runGit(repoRoot, ["remote", "set-url", "origin", path.join(os.tmpdir(), "paperclip-missing-remote", "repo.git")]);+ const warnings = await refreshRemoteTrackingBaseRef(repoRoot, "origin/master");+ expect(warnings).toHaveLength(1);+ expect(warnings[0]).toContain("Could not refresh base ref origin/master");+ expect(warnings[0]).not.toContain("GitHub credential");+ });+});+describe("ensureServerWorkspaceLinksCurrent", () => {it("relinks stale server workspace dependencies inside the current repo root", async () => {const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-links-"));diff --git a/server/src/services/git-credentials.ts b/server/src/services/git-credentials.tsnew file mode 100644index 0000000000..4675103fd0--- /dev/null+++ b/server/src/services/git-credentials.ts@@ -0,0 +1,202 @@+import type { Db } from "@paperclipai/db";+import { isGitHubDotCom } from "./github-fetch.js";+import { secretService } from "./secrets.js";++/**+ * Server-side git credentials for managed project checkouts and execution-workspace base+ * refreshes. Operators store a GitHub token as a company secret under one of the well-known+ * names below (the same convention the GitHub external-object provider reads); this module+ * resolves it and turns it into a git invocation that authenticates clone/fetch against+ * github.com over HTTPS without ever placing the token in argv, URLs, or on disk.+ *+ * The provider factory is deliberately the single seam for future credential sources (for+ * example a brokered GitHub connection): swap the factory, keep every call site unchanged.+ */++/** Company-secret names probed for a GitHub token, in priority order. */+export const DEFAULT_GITHUB_TOKEN_SECRET_NAMES = ["GITHUB_TOKEN", "GH_TOKEN", "PAPERCLIP_GITHUB_TOKEN"] as const;++/** Env var the credential helper reads the token from; never appears in argv. */+export const GIT_CREDENTIAL_TOKEN_ENV_KEY = "PAPERCLIP_GIT_TOKEN";++// `!`-prefixed helpers run via `sh -c` with the credential action appended as "$1". Only the+// `get` action answers; store/erase drain stdin and exit 0 silently. `x-access-token`+// authenticates classic PATs, fine-grained PATs, and GitHub App installation tokens alike.+//+// The helper re-validates the credential request from its stdin description and answers only+// for `protocol=https` + `host=github.com`/`www.github.com`. The pre-invocation URL check+// runs before git applies configuration like repository-local `url.<base>.insteadOf`+// rewrites, so a rewritten remote could otherwise request the token for an arbitrary host.+// The helper is additionally installed URL-scoped (`credential.https://github.com.helper`)+// so git does not consult it for other hosts in the first place — two independent gates.+const GIT_CREDENTIAL_HELPER =+ `!f() { ok=; proto=; while IFS= read -r l && [ -n "$l" ]; do case "$l" in host=github.com|host=www.github.com) ok=1;; protocol=https) proto=1;; esac; done; if [ "$1" = get ] && [ -n "$ok" ] && [ -n "$proto" ]; then printf 'username=x-access-token\\npassword=%s\\n' "$PAPERCLIP_GIT_TOKEN"; fi; }; f`;++export type GitCredential = {+ token: string;+ source: "company_secret" | "server_env";+ /** The company-secret name the token came from; null for a server-environment token. */+ secretName: string | null;+};++/** A prepared, credential-bearing git invocation: config args plus the env that carries the token. */+export type GitAuthInvocation = {+ configArgs: string[];+ env: Record<string, string>;+ source: GitCredential["source"];+ secretName: string | null;+};++/**+ * Resolve auth for one remote URL. Returns null when the URL is out of scope (non-GitHub,+ * ssh, or already credentialed) or when no token is available — callers then run git with+ * ambient behavior, exactly as before this module existed.+ */+export type GitRemoteAuthProvider = (remoteUrl: string) => Promise<GitAuthInvocation | null>;++/**+ * True only for `https://github.com/...` (or `www.`) URLs without inline userinfo. GHES and+ * other hosts are out of scope for now — sending a github.com token to an arbitrary host+ * would leak it, and an operator's inline URL credential must never be overridden.+ */+export function isGitHubHttpsRemoteUrl(remoteUrl: string): boolean {+ let parsed: URL;+ try {+ parsed = new URL(remoteUrl);+ } catch {+ return false;+ }+ if (parsed.protocol !== "https:") return false;+ if (parsed.username || parsed.password) return false;+ return isGitHubDotCom(parsed.hostname);+}++/**+ * Mask credential material embedded in URLs so it never reaches warnings, run errors, or+ * persisted payloads: userinfo on any scheme (`https://user:token@host`,+ * `ssh://user:pass@host`) and the entire query string of any URL (`?access_token=…` and+ * every other parameter — masked wholesale rather than by an inevitably incomplete+ * parameter-name list). Scp-style remotes (`git@host:path`) carry no password and are left+ * alone.+ */+export function scrubGitCredentialText(text: string): string {+ return text+ .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]+@/gi, "$1***@")+ .replace(/([a-z][a-z0-9+.-]*:\/\/[^\s"'?]*)\?[^\s"']*/gi, "$1?***");+}++export function buildGitAuthInvocation(credential: GitCredential): GitAuthInvocation {+ return {+ // The leading empty helper clears ambient helpers (gh, osxkeychain, credential-store) so+ // they neither outrank the resolved token nor receive store/erase callbacks for it. The+ // token helper is installed URL-scoped: git consults it only for credential requests+ // whose context matches github.com over https, so an `insteadOf`-rewritten remote never+ // reaches it (and the helper itself re-checks the request host — see above).+ configArgs: [+ "-c", "credential.helper=",+ "-c", `credential.https://github.com.helper=${GIT_CREDENTIAL_HELPER}`,+ "-c", `credential.https://www.github.com.helper=${GIT_CREDENTIAL_HELPER}`,+ ],+ env: {+ [GIT_CREDENTIAL_TOKEN_ENV_KEY]: credential.token,+ GIT_TERMINAL_PROMPT: "0",+ },+ source: credential.source,+ secretName: credential.secretName,+ };+}++const GIT_AUTH_FAILURE_PATTERN =+ /authentication failed|could not read username|could not read password|invalid username or password|terminal prompts disabled|repository not found|not accessible|permission denied|HTTP 40[13]|The requested URL returned error: 40[13]/i;++/**+ * Turn a failed authenticated (or unauthenticated) git network operation into an actionable+ * suffix for the error message. Returns null when the failure does not look auth-related and+ * no credential was in play.+ */+export function describeGitAuthFailure(input: {+ error: string;+ used: { source: GitCredential["source"]; secretName: string | null } | null;+}): string | null {+ if (input.used) {+ const label = input.used.secretName+ ? `the ${input.used.secretName} company-secret GitHub credential`+ : "the server-environment GitHub credential";+ return `The operation authenticated with ${label}, which was rejected or lacks access to this repository.`;+ }+ if (GIT_AUTH_FAILURE_PATTERN.test(input.error)) {+ return "No GitHub credential is configured — add a GITHUB_TOKEN or GH_TOKEN company secret in Settings → Secrets, or configure a local checkout cwd for this project workspace.";+ }+ return null;+}++type SecretServiceLike = ReturnType<typeof secretService>;++type GitCredentialSecretsDeps = {+ getByName: (+ companyId: string,+ name: string,+ ) => Promise<{ id: string } | null | undefined> | ReturnType<SecretServiceLike["getByName"]>;+ resolveSecretValue: SecretServiceLike["resolveSecretValue"];+};++/**+ * Build the credential provider for one run. Resolution order: company secret by well-known+ * name, then the server process env (`GITHUB_TOKEN`/`GH_TOKEN`) for self-hosted operators,+ * then null. The lookup is memoized per provider instance so one run performs at most one+ * secret resolution (and writes at most one audit event) no matter how many git operations+ * it authenticates.+ */+export function createGitRemoteAuthProvider(+ db: Db,+ companyId: string,+ context?: {+ issueId?: string | null;+ heartbeatRunId?: string | null;+ responsibleUserId?: string | null;+ },+ deps?: {+ secrets?: GitCredentialSecretsDeps;+ env?: NodeJS.ProcessEnv;+ secretNames?: readonly string[];+ },+): GitRemoteAuthProvider {+ const secrets: GitCredentialSecretsDeps = deps?.secrets ?? secretService(db);+ const env = deps?.env ?? process.env;+ const secretNames = deps?.secretNames ?? DEFAULT_GITHUB_TOKEN_SECRET_NAMES;+ let credentialPromise: Promise<GitCredential | null> | null = null;++ const resolveCredential = async (): Promise<GitCredential | null> => {+ for (const secretName of secretNames) {+ const secret = await Promise.resolve(secrets.getByName(companyId, secretName)).catch(() => null);+ if (!secret) continue;+ // A resolution failure (inactive secret, provider outage) records its own failure audit+ // event; fall through to the next source instead of failing the whole git operation here.+ const token = await secrets+ .resolveSecretValue(companyId, secret.id, "latest", {+ accessContext: {+ consumerType: "system",+ consumerId: "workspace-git-credential",+ actorType: "system",+ issueId: context?.issueId ?? null,+ heartbeatRunId: context?.heartbeatRunId ?? null,+ responsibleUserId: context?.responsibleUserId ?? null,+ },+ })+ .then((value) => value.trim())+ .catch(() => "");+ if (token) return { token, source: "company_secret", secretName };+ }+ const envToken = env.GITHUB_TOKEN?.trim() || env.GH_TOKEN?.trim() || "";+ if (envToken) return { token: envToken, source: "server_env", secretName: null };+ return null;+ };++ return async (remoteUrl: string) => {+ if (!isGitHubHttpsRemoteUrl(remoteUrl)) return null;+ credentialPromise ??= resolveCredential();+ const credential = await credentialPromise;+ if (!credential) return null;+ return buildGitAuthInvocation(credential);+ };+}diff --git a/server/src/services/github-external-object-provider.ts b/server/src/services/github-external-object-provider.tsindex f434b24b41..6664b6c7cf 100644--- a/server/src/services/github-external-object-provider.ts+++ b/server/src/services/github-external-object-provider.ts@@ -1,5 +1,6 @@import type { Db } from "@paperclipai/db";import type { ExternalObjectCanonicalUrl } from "@paperclipai/shared";+import { DEFAULT_GITHUB_TOKEN_SECRET_NAMES } from "./git-credentials.js";import { ghFetch, gitHubApiBase } from "./github-fetch.js";import { secretService } from "./secrets.js";import type {@@ -27,7 +28,6 @@ interface GitHubObjectIdentity {pathKind: "pull" | "issues";}-const DEFAULT_GITHUB_TOKEN_SECRET_NAMES = ["GITHUB_TOKEN", "GH_TOKEN", "PAPERCLIP_GITHUB_TOKEN"] as const;const GITHUB_OBJECT_TTL_SECONDS = 300;function isGitHubHost(host: string) {diff --git a/server/src/services/github-fetch.ts b/server/src/services/github-fetch.tsindex 787ae0ef5d..af9fd955fd 100644--- a/server/src/services/github-fetch.ts+++ b/server/src/services/github-fetch.ts@@ -1,6 +1,6 @@import { unprocessable } from "../errors.js";-function isGitHubDotCom(hostname: string) {+export function isGitHubDotCom(hostname: string) {const h = hostname.toLowerCase();return h === "github.com" || h === "www.github.com";}diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.tsindex ab27ce02b2..38f1d66375 100644--- a/server/src/services/heartbeat.ts+++ b/server/src/services/heartbeat.ts@@ -70,6 +70,12 @@ import {import { conflict, HttpError, notFound } from "../errors.js";import { getStartupTraceContext } from "../instrumentation.js";import { logger } from "../middleware/logger.js";+import {+ createGitRemoteAuthProvider,+ describeGitAuthFailure,+ scrubGitCredentialText,+ type GitRemoteAuthProvider,+} from "./git-credentials.js";import { publishLiveEvent } from "./live-events.js";import { normalizeResponsibleUserDenialCode } from "./responsible-user-denial-run-outcomes.js";import { getRunLogStore, type RunLogHandle } from "./run-log-store.js";@@ -1489,10 +1495,12 @@ function deriveRepoNameFromRepoUrl(repoUrl: string | null): string | null {}}-async function ensureManagedProjectWorkspace(input: {+export async function ensureManagedProjectWorkspace(input: {companyId: string;projectId: string;repoUrl: string | null;+ /** Optional git credential source for cloning private repos; null/absent preserves ambient behavior. */+ resolveGitAuth?: GitRemoteAuthProvider | null;}): Promise<{ cwd: string; warning: string | null }> {const cwd = resolveManagedProjectWorkspaceDir({companyId: input.companyId,@@ -1528,15 +1536,34 @@ async function ensureManagedProjectWorkspace(input: {await fs.rm(cwd, { recursive: true, force: true });}+ const auth = input.resolveGitAuth ? await input.resolveGitAuth(input.repoUrl) : null;try {- await execFile("git", ["clone", input.repoUrl, cwd], {- env: sanitizeRuntimeServiceBaseEnv(process.env),+ await execFile("git", [...(auth?.configArgs ?? []), "clone", input.repoUrl, cwd], {+ env: {+ // Spread order matters: the sanitizer strips PAPERCLIP_*, which would remove the+ // credential-helper token env if it came first. GIT_TERMINAL_PROMPT=0 fails a+ // credential-less private clone immediately instead of hanging on a prompt until+ // the clone timeout.+ ...sanitizeRuntimeServiceBaseEnv(process.env),+ GIT_TERMINAL_PROMPT: "0",+ ...(auth?.env ?? {}),+ },timeout: MANAGED_WORKSPACE_GIT_CLONE_TIMEOUT_MS,});return { cwd, warning: null };} catch (error) {+ // The clone only ever starts from a missing or just-emptied directory, so removing it on+ // failure cannot destroy operator data — but leaving it would poison the next run: a+ // timeout-killed clone leaves a partial .git that the gitDirExists probe above adopts.+ await fs.rm(cwd, { recursive: true, force: true }).catch(() => undefined);const reason = error instanceof Error ? error.message : String(error);- throw new Error(`Failed to prepare managed checkout for "${input.repoUrl}" at "${cwd}": ${reason}`);+ const authNote = describeGitAuthFailure({+ error: reason,+ used: auth ? { source: auth.source, secretName: auth.secretName } : null,+ });+ throw new Error(scrubGitCredentialText(+ `Failed to prepare managed checkout for "${input.repoUrl}" at "${cwd}": ${reason}${authNote ? ` ${authNote}` : ""}`,+ ));}}@@ -1551,6 +1578,7 @@ async function resolveConfiguredOrManagedProjectCwd(input: {projectId: string;cwd: string | null;repoUrl: string | null;+ resolveGitAuth?: GitRemoteAuthProvider | null;}): Promise<{ cwd: string; warning: string | null }> {const configuredCwd = readNonEmptyString(input.cwd);if (configuredCwd && configuredCwd !== REPO_ONLY_CWD_SENTINEL) {@@ -1560,6 +1588,7 @@ async function resolveConfiguredOrManagedProjectCwd(input: {companyId: input.companyId,projectId: input.projectId,repoUrl: readNonEmptyString(input.repoUrl),+ resolveGitAuth: input.resolveGitAuth ?? null,});}@@ -1587,8 +1616,16 @@ function defaultAdditionalProjectWorkspaceDeps(db: Db): ResolveAdditionalProject.from(projectWorkspaces).where(and(eq(projectWorkspaces.companyId, companyId), eq(projectWorkspaces.projectId, projectId))).orderBy(asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id)),- resolveConfiguredOrManagedProjectCwd,- ensureManagedProjectWorkspace,+ resolveConfiguredOrManagedProjectCwd: (input) =>+ resolveConfiguredOrManagedProjectCwd({+ ...input,+ resolveGitAuth: input.resolveGitAuth ?? createGitRemoteAuthProvider(db, input.companyId),+ }),+ ensureManagedProjectWorkspace: (input) =>+ ensureManagedProjectWorkspace({+ ...input,+ resolveGitAuth: input.resolveGitAuth ?? createGitRemoteAuthProvider(db, input.companyId),+ }),// A realized workspace must hold real content. An empty directory gives the agent an empty// referenced workspace, so treat an empty directory the same as a missing one.directoryHasContents: async (cwd) => {@@ -8419,6 +8456,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})preferredWorkspaceWarning =`Selected project workspace "${preferredProjectWorkspaceId}" is not available on this project.`;}+ const resolveGitAuth = createGitRemoteAuthProvider(db, agent.companyId, { issueId });for (const workspace of projectWorkspaceRows) {let projectCwd: string;let managedWorkspaceWarning: string | null = null;@@ -8428,6 +8466,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})projectId: workspaceProjectId ?? resolvedProjectId ?? workspace.projectId,cwd: workspace.cwd,repoUrl: workspace.repoUrl,+ resolveGitAuth,});projectCwd = resolvedCwd.cwd;managedWorkspaceWarning = resolvedCwd.warning;@@ -14050,6 +14089,13 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {}): null,issueId,});+ // One credential provider per run: base-ref refreshes during workspace realization and+ // restore authenticate against private GitHub remotes with the same company-secret token+ // the managed clone uses.+ const workspaceGitAuthProvider = createGitRemoteAuthProvider(db, agent.companyId, {+ issueId,+ heartbeatRunId: run.id,+ });const { executionWorkspace, reusedExecutionWorkspace, policy: resolvedWorkspaceReusePolicy } =await provisionExecutionWorkspaceForFreshnessDecision<RealizedExecutionWorkspace>({requestedShouldReuseExisting,@@ -14098,6 +14144,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})enableWorkspaceDirtyQuarantineRepair:resolvedInstanceSettings.experimental.enableWorkspaceDirtyQuarantineRepair,recorder: workspaceOperationRecorder,+ resolveGitAuth: workspaceGitAuthProvider,}): null,realizeWorkspace: () => realizeExecutionWorkspace({@@ -14116,6 +14163,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})enableWorkspaceDirtyQuarantineRepair:resolvedInstanceSettings.experimental.enableWorkspaceDirtyQuarantineRepair,recorder: workspaceOperationRecorder,+ resolveGitAuth: workspaceGitAuthProvider,}),});const resolvedProjectId = executionWorkspace.projectId ?? issueRef?.projectId ?? executionProjectId ?? null;diff --git a/server/src/services/workspace-runtime.ts b/server/src/services/workspace-runtime.tsindex 288a7d8773..b7e8ea5388 100644--- a/server/src/services/workspace-runtime.ts+++ b/server/src/services/workspace-runtime.ts@@ -77,6 +77,21 @@ export interface ExecutionWorkspaceInput {additionalWorkspaces?: ExecutionWorkspaceAdditionalInput[];}+/**+ * A prepared credential-bearing git invocation for one remote URL, or null to keep ambient+ * behavior. Structurally compatible with the provider built by `git-credentials.ts` — this+ * module deliberately takes prepared invocations rather than tokens, so it never imports the+ * secrets layer and test fakes stay trivial.+ */+export type GitRemoteAuthInvocation = {+ configArgs: string[];+ env: Record<string, string>;+ source?: string;+ secretName?: string | null;+};++export type GitRemoteAuthProvider = (remoteUrl: string) => Promise<GitRemoteAuthInvocation | null>;+export interface ExecutionWorkspaceIssueRef {id: string;identifier: string | null;@@ -562,11 +577,12 @@ async function executeProcess(input: {};}-async function runGit(args: string[], cwd: string): Promise<string> {+async function runGit(args: string[], cwd: string, opts?: { env?: NodeJS.ProcessEnv }): Promise<string> {const proc = await executeProcess({command: "git",args,cwd,+ env: opts?.env,});if (proc.code !== 0) {throw new Error(proc.stderr.trim() || proc.stdout.trim() || `git ${args.join(" ")} failed`);@@ -597,26 +613,40 @@ function parseRemoteTrackingRef(ref: string): { remote: string; branch: string }return { remote, branch };}-async function refreshRemoteTrackingBaseRef(repoRoot: string, baseRef: string): Promise<string[]> {+export async function refreshRemoteTrackingBaseRef(+ repoRoot: string,+ baseRef: string,+ resolveGitAuth?: GitRemoteAuthProvider | null,+): Promise<string[]> {const remoteTracking = parseRemoteTrackingRef(baseRef);if (!remoteTracking) return [];- const remoteExists = await runGit(["remote", "get-url", remoteTracking.remote], repoRoot)- .then(() => true)- .catch(() => false);- if (!remoteExists) return [];+ const remoteUrl = await runGit(["remote", "get-url", remoteTracking.remote], repoRoot)+ .then((value) => value.trim() || null)+ .catch(() => null);+ if (!remoteUrl) return [];+ const auth = resolveGitAuth ? await resolveGitAuth(remoteUrl).catch(() => null) : null;try {await runGit([+ ...(auth?.configArgs ?? []),"fetch","--prune",remoteTracking.remote,`+refs/heads/${remoteTracking.branch}:refs/remotes/${remoteTracking.remote}/${remoteTracking.branch}`,- ], repoRoot);+ ], repoRoot, auth ? { env: { ...process.env, ...auth.env } } : undefined);return [];} catch (error) {- const message = error instanceof Error ? error.message : String(error);- return [`Could not refresh base ref ${baseRef} before preparing the execution workspace: ${message}`];+ const rawMessage = error instanceof Error ? error.message : String(error);+ // Mask URL userinfo (any scheme) and whole URL query strings before the message rides+ // warnings that reach run logs.+ const message = rawMessage+ .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]+@/gi, "$1***@")+ .replace(/([a-z][a-z0-9+.-]*:\/\/[^\s"'?]*)\?[^\s"']*/gi, "$1?***");+ const authNote = auth+ ? ` The fetch authenticated with ${auth.secretName ? `the ${auth.secretName} company-secret GitHub credential` : "the server-environment GitHub credential"}, which may have been rejected.`+ : "";+ return [`Could not refresh base ref ${baseRef} before preparing the execution workspace: ${message}${authNote}`];}}@@ -637,6 +667,7 @@ export async function inspectExecutionWorkspaceBaseDrift(input: {baseRef: string | null;recordedBaseRefSha?: string | null;skipRefresh?: boolean;+ resolveGitAuth?: GitRemoteAuthProvider | null;}): Promise<{warnings: string[];currentBaseRefSha: string | null;@@ -647,7 +678,9 @@ export async function inspectExecutionWorkspaceBaseDrift(input: {return { warnings: [], currentBaseRefSha: null, branchBaseRefSha: null };}- const warnings = input.skipRefresh ? [] : await refreshRemoteTrackingBaseRef(input.repoRoot, baseRef);+ const warnings = input.skipRefresh+ ? []+ : await refreshRemoteTrackingBaseRef(input.repoRoot, baseRef, input.resolveGitAuth);const currentBaseRefSha = await resolveBaseRefSha(input.repoRoot, baseRef);if (!currentBaseRefSha) {warnings.push(`Could not resolve base ref ${baseRef} while checking execution workspace freshness.`);@@ -1991,9 +2024,10 @@ export async function ensureGitWorktreeBranchCoherent(input: {async function resolveAuthoritativeBaseRef(repoRoot: string,configuredBaseRef: string | null,+ resolveGitAuth?: GitRemoteAuthProvider | null,): Promise<{ baseRef: string; warnings: string[]; refreshed: boolean }> {const warnings: string[] = [];- const detectOrHead = async () => (await detectDefaultBranch(repoRoot)) ?? "HEAD";+ const detectOrHead = async () => (await detectDefaultBranch(repoRoot, resolveGitAuth)) ?? "HEAD";const configured = configuredBaseRef?.trim();if (!configured || configured === "HEAD") {@@ -2008,7 +2042,7 @@ async function resolveAuthoritativeBaseRef(const remoteCandidate = `origin/${configured}`;// Refresh here and keep the warnings; the caller skips its own refresh of// the returned ref (see `refreshed`) so we never fetch the same ref twice.- warnings.push(...await refreshRemoteTrackingBaseRef(repoRoot, remoteCandidate));+ warnings.push(...await refreshRemoteTrackingBaseRef(repoRoot, remoteCandidate, resolveGitAuth));if (await resolveBaseRefSha(repoRoot, remoteCandidate)) {return { baseRef: remoteCandidate, warnings, refreshed: true };}@@ -2179,9 +2213,12 @@ async function isGitCheckout(cwd: string): Promise<boolean> {return Boolean(await runGit(["rev-parse", "--git-dir"], cwd).catch(() => null));}-async function detectDefaultBranch(repoRoot: string): Promise<string | null> {+async function detectDefaultBranch(+ repoRoot: string,+ resolveGitAuth?: GitRemoteAuthProvider | null,+): Promise<string | null> {const originMasterRef = "origin/master";- await refreshRemoteTrackingBaseRef(repoRoot, originMasterRef);+ await refreshRemoteTrackingBaseRef(repoRoot, originMasterRef, resolveGitAuth);if (await resolveBaseRefSha(repoRoot, originMasterRef)) {return originMasterRef;}@@ -2193,7 +2230,7 @@ async function detectDefaultBranch(repoRoot: string): Promise<string | null> {repoRoot,);if (remoteHead) {- await refreshRemoteTrackingBaseRef(repoRoot, remoteHead);+ await refreshRemoteTrackingBaseRef(repoRoot, remoteHead, resolveGitAuth);if (await resolveBaseRefSha(repoRoot, remoteHead)) return remoteHead;}} catch {@@ -2203,7 +2240,7 @@ async function detectDefaultBranch(repoRoot: string): Promise<string | null> {// Fallback: check for common default branch names on the remotefor (const candidate of ["origin/master", "origin/main", "main", "master"]) {try {- await refreshRemoteTrackingBaseRef(repoRoot, candidate);+ await refreshRemoteTrackingBaseRef(repoRoot, candidate, resolveGitAuth);await runGit(["rev-parse", "--verify", `${candidate}^{commit}`], repoRoot);return candidate;} catch {@@ -2689,6 +2726,7 @@ export async function realizeExecutionWorkspace(input: {enableWorkspaceBranchReconcileForward?: boolean;enableWorkspaceDirtyQuarantineRepair?: boolean;recorder?: WorkspaceOperationRecorder | null;+ resolveGitAuth?: GitRemoteAuthProvider | null;}): Promise<RealizedExecutionWorkspace> {const rawStrategy = parseObject(input.config.workspaceStrategy);const strategyType = asString(rawStrategy.type, "project_primary");@@ -2727,10 +2765,10 @@ export async function realizeExecutionWorkspace(input: {baseRef,warnings: baseRefResolutionWarnings,refreshed: baseRefAlreadyRefreshed,- } = await resolveAuthoritativeBaseRef(repoRoot, configuredBaseRef);+ } = await resolveAuthoritativeBaseRef(repoRoot, configuredBaseRef, input.resolveGitAuth);const baseRefreshWarnings = [...baseRefResolutionWarnings,- ...(baseRefAlreadyRefreshed ? [] : await refreshRemoteTrackingBaseRef(repoRoot, baseRef)),+ ...(baseRefAlreadyRefreshed ? [] : await refreshRemoteTrackingBaseRef(repoRoot, baseRef, input.resolveGitAuth)),];const currentBaseRefSha = await resolveBaseRefSha(repoRoot, baseRef);@@ -2962,6 +3000,7 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {enableWorkspaceBranchReconcileForward?: boolean;enableWorkspaceDirtyQuarantineRepair?: boolean;recorder?: WorkspaceOperationRecorder | null;+ resolveGitAuth?: GitRemoteAuthProvider | null;}): Promise<RealizedExecutionWorkspace | null> {const cwd = asString(input.workspace.cwd ?? input.workspace.providerRef, "").trim();if (!cwd) return null;@@ -3039,7 +3078,7 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {);}const baseRefreshWarnings = reuseBaseRef- ? await refreshRemoteTrackingBaseRef(repoRoot, reuseBaseRef)+ ? await refreshRemoteTrackingBaseRef(repoRoot, reuseBaseRef, input.resolveGitAuth): [];const currentBaseRefSha = reuseBaseRef ? await resolveBaseRefSha(repoRoot, reuseBaseRef) : null;const refresh = reuseBaseRef && currentBaseRefSha@@ -3090,7 +3129,9 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {await fs.mkdir(path.dirname(worktreePath), { recursive: true });await runGit(["worktree", "prune"], repoRoot).catch(() => {});const restoreBaseRef = input.workspace.baseRef ?? input.base.repoRef ?? null;- const restoreRefreshWarnings = restoreBaseRef ? await refreshRemoteTrackingBaseRef(repoRoot, restoreBaseRef) : [];+ const restoreRefreshWarnings = restoreBaseRef+ ? await refreshRemoteTrackingBaseRef(repoRoot, restoreBaseRef, input.resolveGitAuth)+ : [];const restoreCurrentBaseRefSha = restoreBaseRef ? await resolveBaseRefSha(repoRoot, restoreBaseRef) : null;let created = false;