Files
PaperClipAI/packages/adapter-utils/src/github-launcher.test.ts
T
DottaandClaude Opus 5.5 57e85d0d10 fix(adapter-utils): wait for a replacement GitHub broker after a controller restart (#22209)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Agents in sandbox tasks use managed `git` and `gh` launchers. Each launcher gets a GitHub credential from a broker for each command.
> - A controller restart stops the broker of a task. The provider in the sandbox continues to run. The restored controller then writes a replacement broker location to `broker.json`.
> - The launcher read `broker.json` one time only. It retried a transport failure for about 1.5 seconds. Then it ran the command without credentials.
> - Thus, commands in the restart window failed with "You are not logged into any GitHub hosts" or "could not read Username". Agents lost pull-request checks and pushes, but the GitHub connection was healthy.
> - This pull request makes broker-file launchers wait for a bounded time and read `broker.json` again before each retry.
> - The benefit is that GitHub commands continue with managed credentials through a controller restart.

## Linked Issues or Issue Description

No public issue exists. This is the bug description.

**What happened?**

A sandbox task ran `gh` or `git` while the controller restarted. The launcher wrote `Paperclip: GitHub broker_transport_unavailable; continuing without managed credentials.` Then `gh` wrote "You are not logged into any GitHub hosts", and `git` wrote "could not read Username". Private reads, pushes and pull-request commands failed. Failures occurred in many tasks at the same time, for some minutes.

**Expected behavior**

The launcher waits for the replacement broker for a bounded time. Then it uses the managed credential. If the broker does not return, the launcher continues without credentials and shows the same diagnostic as before.

**Steps to reproduce**

1. Write a broker-file launcher. Set `broker.json` to a closed local port.
2. Run `gh` through the launcher.
3. After 3 seconds, write a reachable broker location to `broker.json`.
4. The command ran without credentials before the replacement was written.

**Relevant logs or output**

`Paperclip: GitHub broker_transport_unavailable; continuing without managed credentials.` followed by `You are not logged into any GitHub hosts. To log in, run: gh auth login`.

## What Changed

- `packages/adapter-utils/src/github-launcher.ts`: Broker-file launchers retry for up to 60 seconds. Before each retry, they read `broker.json` again. A replacement broker is used when the restored controller publishes it.
- The launcher retries two failure types in this wait: a refused or failed connection, and an HTTP 503 answer. With HTTP/2, the sandbox gateway can continue to listen after its controller connection closes. It then answers `503 {"error":"bridge_unavailable"}`.
- HTTP 401 and 403 answers are real denials. The launcher does not wait for them.
- If `broker.json` cannot be read or parsed (for example during a rewrite), the launcher keeps the last broker location and continues the wait. If `broker.json` is missing, has no broker, or has an empty URL or token, the launcher stops the wait at once, because the access of the task ended. (When a replacement bridge cannot start, the controller writes empty values.)
- After the third failure, the launcher writes one line to stderr: it waits for the credential service to return.
- Launchers with an inherited broker URL keep the old short retry budget and the old 503 behavior. Their URL cannot change, so a longer wait cannot help.
- `packages/adapter-utils/src/github-launcher.test.ts`: Regression tests for three outage types (a closed port, a 503 `bridge_unavailable` gateway, and a partly written `broker.json`). Other tests remove `broker.json` or write empty values to it during the wait, and check that 401 and 403 answers do not wait.
- `doc/execution-github-identity.md`: One sentence describes the wait.

## Verification

- Failing before the first fix: `waits for a replacement task broker instead of running without credentials (closed port)` failed with `expected 'anonymous' to be 'reattached-run-credential'`.
- Failing before the second fix: the `(bridge unavailable)` and `(partly written broker file)` cases failed with `expected 'anonymous' to be 'reattached-run-credential'`. The `(closed port)` case passed.
- Failing before the third fix: `stops waiting for an unreachable task broker once its broker file is emptied` timed out after 20 seconds, because the launcher continued to wait. The `removed` case passed.
- Passing after the fixes: `npx vitest run packages/adapter-utils/src/github-launcher.test.ts packages/adapter-utils/src/execution-target.test.ts packages/adapter-utils/src/github-launcher-environment.test.ts server/src/services/heartbeat-github-launchers.test.ts server/src/services/native-runtime/native-github-access.test.ts` passed 138 of 138 tests in 5 files. `native-github-access.test.ts` includes the controller restart and launcher re-arm tests.
- `npx tsc --noEmit -p packages/adapter-utils` passed.
- I did not run the full `pnpm verify`. The local disk was too small for a full install.
- Note: Run these tests outside a managed sandbox, or remove the sandbox GitHub launcher from `PATH` and unset the sandbox broker variables. The sandbox values otherwise leak into the tests on `master` too.

## Risks

- If the broker does not return, a GitHub command that needs credentials now waits up to about 60 seconds (plus one 10-second request timeout) before it continues without credentials. Before, it waited about 1.5 seconds. Local Git commands do not ask the broker, so they do not wait.
- A broker that answers 503 for a long time (for example, when its credential lookup fails) also causes this 60-second wait. Then the launcher continues without credentials, as before.
- The launcher sends no credential in the new stderr line. The tests check that broker tokens do not appear in stderr.
- Low risk otherwise. The change is in the generated launcher source only.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution.

## Checklist

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

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





Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:24:11 -06:00

529 lines
35 KiB
TypeScript

import { execFile } from "node:child_process";
import { createServer } from "node:http";
import { mkdtemp, mkdir, readFile, writeFile, rm } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { promisify } from "node:util";
import { afterEach, describe, expect, it } from "vitest";
import { githubBrokerEnvironment, githubLauncherSource } from "./github-launcher.js";
const exec = promisify(execFile);
const cleanups: Array<() => Promise<unknown>> = [];
afterEach(async () => { for (const cleanup of cleanups.splice(0).reverse()) await cleanup(); });
describe("managed GitHub launchers", () => {
it("uses a private interpreter without selecting Node from PATH", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-interpreter-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const managed = path.join(root, "managed"), real = path.join(root, "real");
await mkdir(managed); await mkdir(real);
const source = githubLauncherSource({ interpreterPath: process.execPath });
const defaultSource = githubLauncherSource();
expect(defaultSource.split("\n")[0]).toBe("#!/usr/bin/env node");
expect(source.split("\n")[0]).toBe(`#!${process.execPath}`);
expect(source.slice(source.indexOf("\n"))).toBe(defaultSource.slice(defaultSource.indexOf("\n")));
const launcher = path.join(managed, "git");
await writeFile(launcher, source, { mode: 0o700 });
await writeFile(path.join(real, "node"), "#!/bin/sh\nexit 126\n", { mode: 0o700 });
await writeFile(path.join(real, "git"), "#!/bin/sh\nprintf 'private interpreter works'\n", { mode: 0o700 });
const env = { ...githubBrokerEnvironment({}, { url: "", token: "" }), HOME: root,
GH_CONFIG_DIR: path.join(root, "config"), PATH: `${managed}${path.delimiter}${real}` };
expect((await exec(launcher, ["--version"], { env })).stdout).toBe("private interpreter works");
});
it.each(["", "relative/node", "/runtime/node --flag", "/runtime/node\nexit 1", "/runtime/node\0"])(
"rejects an invalid interpreter path %j", interpreterPath => {
expect(() => githubLauncherSource({ interpreterPath })).toThrow("absolute path without whitespace");
},
);
it.each([false, true])("rejects a PATH shim that re-enters the same helper before it can recurse (broker file: %s)", async brokerFile => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-recursion-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const managed = path.join(root, "managed"), shim = path.join(root, "shim"), calls = path.join(root, "calls");
await mkdir(managed); await mkdir(shim);
const launcher = path.join(managed, "git");
await writeFile(launcher, githubLauncherSource({ brokerFile }), { mode: 0o700 });
// Bound the pre-fix reproduction: the fixture stops at three invocations.
await writeFile(path.join(shim, "git"), `#!${process.execPath}
const fs = require("node:fs"), {spawnSync} = require("node:child_process");
fs.appendFileSync(${JSON.stringify(calls)}, "call\\n");
if (fs.readFileSync(${JSON.stringify(calls)}, "utf8").trim().split("\\n").length >= 3) process.exit(99);
const result = spawnSync(${JSON.stringify(launcher)}, process.argv.slice(2), {env: process.env, stdio: "inherit"});
process.exit(result.status ?? 98);
`, { mode: 0o700 });
const env = { ...process.env, ...githubBrokerEnvironment({}, {url: "", token: ""}),
PATH: `${managed}${path.delimiter}${shim}${path.delimiter}${path.dirname(process.execPath)}${path.delimiter}/usr/bin${path.delimiter}/bin` };
await expect(exec(launcher, ["--version"], {env, timeout: 5000})).rejects.toMatchObject({
code: 126, stderr: expect.stringContaining("launcher_recursion_rejected"),
});
expect((await readFile(calls, "utf8")).trim().split("\n")).toEqual(["call"]);
});
it("snapshots a staged tree and reports unstaged files without capturing GitHub credentials", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-snapshot-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed"), repo = path.join(root, "repo");
await mkdir(bin); await mkdir(repo);
await exec("git", ["init", "-q", repo]);
await writeFile(path.join(repo, "tracked.txt"), "staged contents\n");
await exec("git", ["-C", repo, "add", "tracked.txt"]);
const expectedTree = (await exec("git", ["-C", repo, "write-tree"])).stdout;
await writeFile(path.join(repo, "tracked.txt"), "unstaged contents\n");
await writeFile(path.join(bin, "git"), githubLauncherSource(), { mode: 0o700 });
let captures = 0;
const server = createServer((_req, res) => {
captures++;
res.setHeader("content-type", "application/json");
res.end(JSON.stringify({ status: "unavailable", reason: "No GitHub connection" }));
});
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
cleanups.push(() => new Promise<void>(resolve => server.close(() => resolve())));
const { port } = server.address() as { port: number };
const env = { ...process.env, ...githubBrokerEnvironment({}, { url: `http://127.0.0.1:${port}`, token: "run-capability" }), PATH: `${bin}:${process.env.PATH}` };
const git = (...args: string[]) => exec(path.join(bin, "git"), args, { cwd: root, env });
const tree = await git("--git-dir", path.join(repo, ".git"), "--work-tree", repo, "write-tree");
const diff = await git("-C", repo, "-c", "core.quotepath=false", "diff-files", "--name-only", "-z", "--", ".");
expect(tree.stdout).toBe(expectedTree);
expect(diff.stdout).toBe("tracked.txt\0");
expect(captures).toBe(0);
});
it.each(["missing", "absent", "unavailable", "rejected"])("commits local work without an identity when GitHub access is %s", async (access) => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-default-author-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed");
await mkdir(bin);
await exec("git", ["init", root]);
await writeFile(path.join(bin, "git"), githubLauncherSource(), { mode: 0o700 });
const server = createServer((_req, res) => {
res.writeHead(access === "rejected" ? 403 : 200, { "content-type": "application/json" });
res.end(JSON.stringify({ status: access, env: {
GH_TOKEN: "rejected-token", GIT_AUTHOR_NAME: "Rejected", GIT_AUTHOR_EMAIL: "rejected@example.test",
GIT_COMMITTER_NAME: "Rejected", GIT_COMMITTER_EMAIL: "rejected@example.test",
} }));
});
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
cleanups.push(() => new Promise<void>(resolve => server.close(() => resolve())));
const { port } = server.address() as { port: number };
const env = { ...process.env, ...githubBrokerEnvironment({
GH_TOKEN: "host-token", GIT_AUTHOR_NAME: "Host", GIT_AUTHOR_EMAIL: "host@example.test",
GIT_COMMITTER_NAME: "Host", GIT_COMMITTER_EMAIL: "host@example.test",
}, { url: `http://127.0.0.1:${port}`, token: access === "missing" ? "" : "run-capability" }),
PATH: `${bin}:${process.env.PATH}` };
await writeFile(path.join(root, "work.txt"), "saved work\n");
await exec(path.join(bin, "git"), ["add", "work.txt"], { cwd: root, env });
await exec(path.join(bin, "git"), ["commit", "-m", "Save local work"], { cwd: root, env });
expect((await exec("git", ["-C", root, "log", "-1", "--format=%an <%ae>|%cn <%ce>"])).stdout.trim())
.toBe("Paperclip <noreply@paperclip.ing>|Paperclip <noreply@paperclip.ing>");
expect((await exec("git", ["-C", root, "show", "HEAD:work.txt"])).stdout).toBe("saved work\n");
await expect(exec("git", ["-C", root, "config", "--local", "--get", "user.name"])).rejects.toThrow();
await expect(exec("git", ["-C", root, "config", "--local", "--get", "user.email"])).rejects.toThrow();
});
it.each(["repository", "command"])("uses explicit %s identity for local commits without managed credentials", async (identitySource) => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-local-identity-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed");
await mkdir(bin);
await exec("git", ["init", root]);
await writeFile(path.join(bin, "git"), githubLauncherSource(), { mode: 0o700 });
const env = { ...process.env, ...githubBrokerEnvironment({
GH_TOKEN: "host-token", GIT_AUTHOR_NAME: "Host", GIT_COMMITTER_NAME: "Host",
}, { url: "", token: "" }), PATH: `${bin}:${process.env.PATH}` };
const git = async (...args: string[]) => (await exec(path.join(bin, "git"), args, { cwd: root, env })).stdout.trim();
expect(await git("var", "GIT_AUTHOR_IDENT")).toMatch(/^Paperclip <noreply@paperclip.ing>/);
expect(await git("var", "GIT_COMMITTER_IDENT")).toMatch(/^Paperclip <noreply@paperclip.ing>/);
if (identitySource === "repository") {
await git("config", "user.name", "Local Author");
await git("config", "user.email", "local@example.test");
}
await git(...(identitySource === "command" ? ["-c", "user.name=Local Author", "-c", "user.email=local@example.test"] : []),
"commit", "--allow-empty", "-m", "Local work");
expect(await git("log", "-1", "--format=%an <%ae>|%cn <%ce>"))
.toBe("Local Author <local@example.test>|Local Author <local@example.test>");
});
it.each(["broker-offline", "config-unwritable", "capability-rejected"])("keeps real local Git usable when %s", async (failure) => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-failure-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed");
await mkdir(bin);
await exec("git", ["init", root]);
await exec("git", ["-C", root, "config", "user.name", "Local Author"]);
await exec("git", ["-C", root, "config", "user.email", "local@example.test"]);
await writeFile(path.join(bin, "git"), githubLauncherSource(), { mode: 0o700 });
const server = createServer((_req, res) => { res.writeHead(403); res.end(); });
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
const { port } = server.address() as { port: number };
if (failure === "broker-offline") await new Promise<void>(resolve => server.close(() => resolve()));
else cleanups.push(() => new Promise<void>(resolve => server.close(() => resolve())));
const configRoot = path.join(root, "config");
if (failure === "config-unwritable") await writeFile(configRoot, "not a directory");
const result = await exec(path.join(bin, "git"), ["remote"], { cwd: root, env: {
...process.env, ...githubBrokerEnvironment({ GH_TOKEN: "host-must-not-leak" }, { url: `http://127.0.0.1:${port}`, token: "private-capability" }),
GH_CONFIG_DIR: configRoot, PATH: `${bin}:${process.env.PATH}`,
} });
expect(result.stderr).toContain(failure === "broker-offline" ? "broker_transport_unavailable" : failure === "config-unwritable" ? "configuration_directory_unavailable" : "capability_rejected");
expect(result.stderr).not.toMatch(/host-must-not-leak|private-capability/);
await exec(path.join(bin, "git"), ["commit", "--allow-empty", "-m", "Offline work"], { cwd: root, env: {
...process.env, ...githubBrokerEnvironment({}, { url: `http://127.0.0.1:${port}`, token: "private-capability" }),
GH_CONFIG_DIR: configRoot, PATH: `${bin}:${process.env.PATH}`,
} });
}, 15_000); // broker-offline retries the transport twice per command before it falls back
it("explains unavailable access while allowing local work without credentials", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-diagnostic-"));
cleanups.push(() => rm(root, {recursive:true,force:true}));
const bin = path.join(root,"managed"), realBin = path.join(root,"real");
await mkdir(bin); await mkdir(realBin);
await writeFile(path.join(bin,"gh"), githubLauncherSource(), {mode:0o700});
await writeFile(path.join(realBin,"gh"), '#!/usr/bin/env node\nprocess.stdout.write(JSON.stringify({token:process.env.GH_TOKEN ?? null}));', {mode:0o700});
const server = createServer((_req,res) => {
res.setHeader("content-type","application/json");
res.end(JSON.stringify({status:"unavailable",reason:"More than one managed GitHub identity matches this run",env:{GH_TOKEN:"must-not-be-used"}}));
});
await new Promise<void>(resolve => server.listen(0,"127.0.0.1",resolve));
cleanups.push(() => new Promise<void>((resolve,reject) => server.close(error => error ? reject(error) : resolve())));
const {port} = server.address() as {port:number};
const result = await exec(path.join(bin,"gh"), [], {env:{...process.env,...githubBrokerEnvironment({GH_TOKEN:"host-token"},{url:`http://127.0.0.1:${port}`,token:"run-capability"}),PATH:`${bin}:${realBin}:${process.env.PATH}`}});
expect(JSON.parse(result.stdout)).toEqual({token:null});
expect(result.stderr).toContain("More than one managed GitHub identity matches this run");
expect(result.stderr).not.toMatch(/host-token|must-not-be-used|run-capability/);
});
it("sends repository creation and forks to the connection's tools when a connection is in use", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-repository-tools-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed"), realBin = path.join(root, "real");
await mkdir(bin); await mkdir(realBin);
await writeFile(path.join(bin, "gh"), githubLauncherSource(), { mode: 0o700 });
await writeFile(path.join(realBin, "gh"), '#!/usr/bin/env node\nprocess.stdout.write(JSON.stringify({args:process.argv.slice(2),token:process.env.GH_TOKEN ?? null}));', { mode: 0o700 });
let status = "available";
const server = createServer((_req, res) => {
res.setHeader("content-type", "application/json");
res.end(JSON.stringify({ status, env: { GH_TOKEN: "managed-token" } }));
});
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
cleanups.push(() => new Promise<void>(resolve => server.close(() => resolve())));
const { port } = server.address() as { port: number };
const env = { ...process.env, ...githubBrokerEnvironment({}, { url: `http://127.0.0.1:${port}`, token: "run-capability" }),
PATH: `${bin}:${realBin}:${process.env.PATH}` };
const gh = (...args: string[]) => exec(path.join(bin, "gh"), args, { env });
for (const [args, tool] of [
[["repo", "create", "demo", "--private"], "create_repository"],
[["repo", "new", "demo"], "create_repository"],
[["repo", "fork", "octo-org/tools", "--org", "acme"], "fork_repository"],
] as const) {
const failure = await gh(...args).catch((error: { code?: number; stdout?: string; stderr?: string }) => error);
expect(failure).toMatchObject({ code: 1, stdout: "" });
expect(failure.stderr).toContain(`GitHub connection's ${tool} tool`);
expect(failure.stderr).not.toContain("managed-token");
}
expect(JSON.parse((await gh("repo", "create", "--help")).stdout))
.toEqual({ args: ["repo", "create", "--help"], token: "managed-token" });
expect(JSON.parse((await gh("repo", "view", "octo-org/tools")).stdout))
.toEqual({ args: ["repo", "view", "octo-org/tools"], token: "managed-token" });
// Without a connection there are no connection tools; gh runs unchanged.
status = "absent";
expect(JSON.parse((await gh("repo", "create", "demo")).stdout)).toEqual({ args: ["repo", "create", "demo"], token: null });
});
it.each(["before-write", "partial-write"])("keeps Git and managed credentials available after a %s failure", async (failure) => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-default-write-failure-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed"), realBin = path.join(root, "real");
await mkdir(bin); await mkdir(realBin);
await exec("git", ["init", root]);
for (const name of ["git", "gh"]) await writeFile(path.join(bin, name), githubLauncherSource(), { mode: 0o700 });
await writeFile(path.join(realBin, "gh"), '#!/usr/bin/env node\nprocess.stdout.write(process.env.GH_TOKEN || "anonymous");', { mode: 0o700 });
const fault = path.join(root, "write-fault.cjs");
await writeFile(fault, `const fs = require('node:fs'); const write = fs.writeFileSync;
fs.writeFileSync = (file, ...args) => {
if (String(file).endsWith('/gitconfig')) {
if (${failure === "partial-write"}) write(file, '[user', { mode: 0o600 });
throw new Error('fixture disk full');
}
return write(file, ...args);
};`);
const server = createServer((_req, res) => {
res.setHeader("content-type", "application/json");
res.end(JSON.stringify({ status: "available", env: { GH_TOKEN: "managed-token" } }));
});
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
cleanups.push(() => new Promise<void>(resolve => server.close(() => resolve())));
const { port } = server.address() as { port: number };
const env = {
...process.env, ...githubBrokerEnvironment({}, { url: `http://127.0.0.1:${port}`, token: "run-capability" }),
PATH: `${bin}:${realBin}:${process.env.PATH}`,
};
const result = await exec(process.execPath, ["--require", fault, path.join(bin, "gh")], { cwd: root, env });
expect(result.stdout).toBe("managed-token");
expect(result.stderr).toContain("configuration_directory_unavailable");
const git = (...args: string[]) => exec(process.execPath, ["--require", fault, path.join(bin, "git"), ...args], { cwd: root, env });
expect((await git("status", "--porcelain", "--untracked-files=no")).stdout).toBe("");
await expect(git("commit", "--allow-empty", "-m", "No default")).rejects.toMatchObject({ stderr: expect.stringContaining("Author identity unknown") });
await git("-c", "user.name=Explicit", "-c", "user.email=explicit@example.test", "commit", "--allow-empty", "-m", "Explicit identity");
expect((await exec("git", ["-C", root, "log", "-1", "--format=%an <%ae>|%cn <%ce>"])).stdout.trim())
.toBe("Explicit <explicit@example.test>|Explicit <explicit@example.test>");
});
// The first broker request fails, the second succeeds: the managed token must still reach gh.
it.each([
["connection drops before the response", (res: import("node:http").ServerResponse) => { res.socket?.destroy(); }],
["body read fails mid-response", (res: import("node:http").ServerResponse) => {
res.writeHead(200, {"content-type":"application/json"}); res.write('{"status":'); setTimeout(() => res.socket?.destroy(), 20);
}],
])("retries when the %s and still uses managed credentials", async (_label, fail) => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-retry-"));
cleanups.push(() => rm(root, {recursive:true,force:true}));
const bin = path.join(root,"managed"), realBin = path.join(root,"real");
await mkdir(bin); await mkdir(realBin);
await writeFile(path.join(bin,"gh"), githubLauncherSource(), {mode:0o700});
await writeFile(path.join(realBin,"gh"), '#!/usr/bin/env node\nprocess.stdout.write(JSON.stringify({token:process.env.GH_TOKEN ?? null}));', {mode:0o700});
let requests = 0;
const server = createServer((_req,res) => {
requests++;
if (requests === 1) return fail(res);
res.setHeader("content-type","application/json");
res.end(JSON.stringify({status:"available",env:{GH_TOKEN:"managed-token"}}));
});
await new Promise<void>(resolve => server.listen(0,"127.0.0.1",resolve));
cleanups.push(() => new Promise<void>(resolve => server.close(() => resolve())));
const {port} = server.address() as {port:number};
const result = await exec(path.join(bin,"gh"), [], {env:{...process.env,...githubBrokerEnvironment({GH_TOKEN:"host-token"},{url:`http://127.0.0.1:${port}`,token:"run-capability"}),PATH:`${bin}:${realBin}:${process.env.PATH}`}});
expect(JSON.parse(result.stdout)).toEqual({token:"managed-token"});
expect(requests).toBe(2);
expect(result.stderr).not.toContain("broker_transport_unavailable");
expect(result.stderr).not.toMatch(/host-token|run-capability/);
});
it("captures each command's identity and clears host credentials when the next person has none", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-launcher-test-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed"), realBin = path.join(root, "real"), repo = path.join(root, "repo");
for (const dir of [bin, realBin, repo, path.join(bin, "gh-config")]) await mkdir(dir, { recursive: true });
for (const name of ["git", "gh"]) await writeFile(path.join(bin, name), githubLauncherSource(), { mode: 0o700 });
await writeFile(path.join(realBin, "gh"), `#!/usr/bin/env node
const {execFileSync}=require('node:child_process');
const identity=execFileSync('git',['var','GIT_AUTHOR_IDENT'],{encoding:'utf8'}).trim();
process.stdout.write(JSON.stringify({identity, token:process.env.GH_TOKEN ?? null, global:process.env.GIT_CONFIG_GLOBAL, config:process.env.GH_CONFIG_DIR}));
`, { mode: 0o700 });
let user: string | null = "A", captures = 0;
let heldCapture: (() => void) | null = null;
let releaseCapture: (() => void) | null = null;
const server = createServer((req, res) => {
captures++;
expect(req.headers.authorization).toBe("Bearer run-capability");
const selected = user;
res.setHeader("content-type", "application/json");
const finish = () => res.end(JSON.stringify(selected ? { status: "available", env: {
GH_TOKEN: `credential-${selected}`, GITHUB_TOKEN: `credential-${selected}`,
GIT_AUTHOR_NAME: selected, GIT_AUTHOR_EMAIL: `${selected}@example.test`,
GIT_COMMITTER_NAME: selected, GIT_COMMITTER_EMAIL: `${selected}@example.test`,
} } : { status: "absent", env: {} }));
if (heldCapture) { const captured = heldCapture; heldCapture = null; releaseCapture = finish; captured(); }
else finish();
});
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
cleanups.push(() => new Promise<void>((resolve, reject) => server.close(error => error ? reject(error) : resolve())));
const address = server.address() as { port: number };
const env: NodeJS.ProcessEnv = { ...process.env, ...githubBrokerEnvironment({
GH_TOKEN: "ambient-host-token", GIT_AUTHOR_NAME: "Host", GIT_AUTHOR_EMAIL: "host@example.test",
}, { url: `http://127.0.0.1:${address.port}`, token: "run-capability" }), PATH: `${bin}:${realBin}:${process.env.PATH}` };
const git = async (...args: string[]) => (await exec(path.join(bin, "git"), args, { cwd: repo, env })).stdout.trim();
await git("init");
await git("config", "user.name", "Repository Author");
await git("config", "user.email", "repository@example.test");
await git("commit", "--allow-empty", "-m", "A");
user = "B";
await git("commit", "--allow-empty", "-m", "B");
user = "A";
await git("commit", "--allow-empty", "-m", "A again");
expect(await git("log", "--format=%an <%ae>|%cn <%ce>" )).toBe("A <A@example.test>|A <A@example.test>\nB <B@example.test>|B <B@example.test>\nA <A@example.test>|A <A@example.test>");
const before = captures;
const gh = JSON.parse((await exec(path.join(bin, "gh"), [], { cwd: repo, env })).stdout);
expect(gh.identity).toContain("A <A@example.test>");
expect(gh.token).toBe("credential-A");
expect(captures - before).toBe(1); // gh's child Git retains the same capture.
const captured = new Promise<void>(resolve => { heldCapture = resolve; });
const operationA = exec(path.join(bin, "gh"), [], { cwd: repo, env });
await captured;
user = "B";
const operationB = JSON.parse((await exec(path.join(bin, "gh"), [], { cwd: repo, env })).stdout);
releaseCapture!();
const completedA = JSON.parse((await operationA).stdout);
expect(completedA.token).toBe("credential-A");
expect(operationB.token).toBe("credential-B");
expect(completedA.config).not.toBe(operationB.config);
user = null;
await git("commit", "--allow-empty", "-m", "Local identity");
expect(await git("log", "-1", "--format=%an <%ae>|%cn <%ce>"))
.toBe("Repository Author <repository@example.test>|Repository Author <repository@example.test>");
const anonymous = JSON.parse((await exec(path.join(bin, "gh"), [], { cwd: repo, env })).stdout);
expect(anonymous.token).toBeNull();
await git("config", "--unset", "user.name");
await git("config", "--unset", "user.email");
await git("commit", "--allow-empty", "-m", "Default identity after revocation");
expect(await git("log", "-1", "--format=%an <%ae>|%cn <%ce>"))
.toBe("Paperclip <noreply@paperclip.ing>|Paperclip <noreply@paperclip.ing>");
expect(await git("status", "--porcelain")).toBe(""); // unrelated public/local Git still works
expect(env.GH_TOKEN).toBe("");
expect(env.GIT_AUTHOR_NAME).toBe("");
});
it("keeps local Git commands off the broker and still asks for the rest", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-github-local-skip-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed");
await mkdir(bin);
await writeFile(path.join(bin, "git"), githubLauncherSource(), { mode: 0o700 });
let posts = 0;
const server = createServer((_req, res) => {
posts++;
res.setHeader("content-type", "application/json");
res.end(JSON.stringify({ status: "available", env: {
GH_TOKEN: "managed-token", GIT_AUTHOR_NAME: "Managed", GIT_AUTHOR_EMAIL: "managed@example.test",
GIT_COMMITTER_NAME: "Managed", GIT_COMMITTER_EMAIL: "managed@example.test",
} }));
});
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
cleanups.push(() => new Promise<void>(resolve => server.close(() => resolve())));
const { port } = server.address() as { port: number };
const env = { ...process.env, ...githubBrokerEnvironment({}, { url: `http://127.0.0.1:${port}`, token: "run-capability" }), PATH: `${bin}:${process.env.PATH}` };
const git = async (...args: string[]) => {
const before = posts;
const { stdout } = await exec(path.join(bin, "git"), args, { cwd: root, env }).catch(() => ({ stdout: "" }));
return { stdout: stdout.trim(), posts: posts - before };
};
for (const args of [
["init", "-q", "repo"],
["-C", "repo", "status", "--short"],
["-C", "repo", "-c", "core.quotepath=off", "--no-pager", "diff"],
["--git-dir=repo/.git", "rev-parse", "--git-dir"],
["--git-dir", "repo/.git", "--work-tree", "repo", "status"],
["-C", "repo", "config", "user.useConfigOnly"],
["--version"],
]) expect((await git(...args)).posts, args.join(" ")).toBe(0);
expect((await git("-C", "repo", "config", "user.useConfigOnly")).stdout).toBe("true");
for (const args of [
["-C", "repo", "remote"],
["-C", "repo", "var", "GIT_AUTHOR_IDENT"],
["-C", "repo", "fetch", "--dry-run"],
["-C", "repo", "-c", "alias.noop=!true", "noop"],
["-C", "repo", "--unknown-option", "status"],
["-C"],
]) expect((await git(...args)).posts, args.join(" ")).toBe(1);
expect((await git("-C", "repo", "var", "GIT_AUTHOR_IDENT")).stdout).toMatch(/^Managed <managed@example.test>/);
expect((await git("-C", "repo", "commit", "--allow-empty", "-m", "Managed work")).posts).toBe(1);
expect((await git("-C", "repo", "log", "-1", "--format=%an <%ae>")).stdout).toBe("Managed <managed@example.test>");
}, 20_000);
});
it("captures the current task broker file once per invocation and never falls back to inherited authority", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-task-github-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed"), real = path.join(root, "real");
await mkdir(bin); await mkdir(real);
await writeFile(path.join(bin, "gh"), githubLauncherSource({ brokerFile: true }), { mode: 0o700 });
await writeFile(path.join(real, "gh"), '#!/usr/bin/env node\nprocess.stdout.write(process.env.GH_TOKEN || "anonymous");\n', { mode: 0o700 });
const captured: string[] = [];
const server = createServer((req, res) => {
captured.push(req.headers.authorization!);
res.writeHead(200, { "content-type": "application/json" });
res.end(JSON.stringify({ status: "available", env: { GH_TOKEN: req.headers.authorization!.slice(7) + "-credential" } }));
});
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
cleanups.push(() => new Promise<void>(resolve => server.close(() => resolve())));
const url = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
const env = { ...process.env, PATH: `${bin}:${real}:${process.env.PATH}`, GH_TOKEN: "ambient-secret",
PAPERCLIP_GITHUB_BROKER_URL: url, PAPERCLIP_GITHUB_BROKER_TOKEN: "stale-capability", PAPERCLIP_API_KEY: "unrelated-api-key" };
const run = () => exec(path.join(bin, "gh"), [], { env });
for (const token of ["first-run", "next-run"]) {
await writeFile(path.join(bin, "broker.json"), JSON.stringify({ url, token }));
expect((await run()).stdout).toBe(token + "-credential");
}
await rm(path.join(bin, "broker.json"));
expect((await run()).stdout).toBe("anonymous");
expect(captured).toEqual(["Bearer first-run", "Bearer next-run"]);
});
// A control-plane restart stops the task's broker while its provider keeps
// running. The replacement broker is published to broker.json a few seconds later.
// An HTTP/2 gateway can outlive its controller and answer 503 instead of refusing.
// The replacement file can also be read while it is only partly written.
it.each(["closed port", "bridge unavailable", "partly written broker file"])(
"waits for a replacement task broker instead of running without credentials (%s)", async (outage) => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-task-github-outage-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed"), real = path.join(root, "real");
await mkdir(bin); await mkdir(real);
await writeFile(path.join(bin, "gh"), githubLauncherSource({ brokerFile: true }), { mode: 0o700 });
await writeFile(path.join(real, "gh"), '#!/usr/bin/env node\nprocess.stdout.write(process.env.GH_TOKEN || "anonymous");\n', { mode: 0o700 });
const stopped = createServer((_req, res) => {
res.writeHead(503, { "content-type": "application/json" });
res.end(JSON.stringify({ error: "bridge_unavailable" }));
});
await new Promise<void>(resolve => stopped.listen(0, "127.0.0.1", resolve));
const stoppedUrl = `http://127.0.0.1:${(stopped.address() as { port: number }).port}`;
if (outage === "bridge unavailable") cleanups.push(() => new Promise<void>(resolve => stopped.close(() => resolve())));
else await new Promise<void>(resolve => stopped.close(() => resolve()));
const replacement = createServer((req, res) => {
res.writeHead(200, { "content-type": "application/json" });
res.end(JSON.stringify({ status: "available", env: { GH_TOKEN: req.headers.authorization!.slice(7) + "-credential" } }));
});
await new Promise<void>(resolve => replacement.listen(0, "127.0.0.1", resolve));
cleanups.push(() => new Promise<void>(resolve => replacement.close(() => resolve())));
const replacementUrl = `http://127.0.0.1:${(replacement.address() as { port: number }).port}`;
await writeFile(path.join(bin, "broker.json"), JSON.stringify({ url: stoppedUrl, token: "stopped-run" }));
const operation = exec(path.join(bin, "gh"), [], { env: { ...process.env, PATH: `${bin}:${real}:${process.env.PATH}` } });
if (outage === "partly written broker file") {
await new Promise(resolve => setTimeout(resolve, 1000));
await writeFile(path.join(bin, "broker.json"), '{"url":');
}
await new Promise(resolve => setTimeout(resolve, outage === "partly written broker file" ? 2000 : 3000));
await writeFile(path.join(bin, "broker.json"), JSON.stringify({ url: replacementUrl, token: "reattached-run" }));
const result = await operation;
expect(result.stdout).toBe("reattached-run-credential");
expect(result.stderr).not.toContain("continuing without managed credentials");
expect(result.stderr).not.toMatch(/stopped-run|reattached-run/);
}, 20_000);
// A failed replacement bridge publishes empty broker values instead of removing the file.
it.each(["removed", "emptied"])("stops waiting for an unreachable task broker once its broker file is %s", async (ending) => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-task-github-ended-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed"), real = path.join(root, "real");
await mkdir(bin); await mkdir(real);
await writeFile(path.join(bin, "gh"), githubLauncherSource({ brokerFile: true }), { mode: 0o700 });
await writeFile(path.join(real, "gh"), '#!/usr/bin/env node\nprocess.stdout.write(process.env.GH_TOKEN || "anonymous");\n', { mode: 0o700 });
const stopped = createServer();
await new Promise<void>(resolve => stopped.listen(0, "127.0.0.1", resolve));
const stoppedUrl = `http://127.0.0.1:${(stopped.address() as { port: number }).port}`;
await new Promise<void>(resolve => stopped.close(() => resolve()));
await writeFile(path.join(bin, "broker.json"), JSON.stringify({ url: stoppedUrl, token: "ended-run" }));
const started = Date.now();
const operation = exec(path.join(bin, "gh"), [], { env: { ...process.env, PATH: `${bin}:${real}:${process.env.PATH}` } });
await new Promise(resolve => setTimeout(resolve, 2500));
if (ending === "removed") await rm(path.join(bin, "broker.json"));
else await writeFile(path.join(bin, "broker.json"), JSON.stringify({ url: "", token: "" }));
const result = await operation;
expect(result.stdout).toBe("anonymous");
expect(result.stderr).toContain("broker_transport_unavailable");
expect(Date.now() - started).toBeLessThan(10_000);
}, 20_000);
it.each([401, 403])("does not wait when the task broker denies the capability (%s)", async (status) => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-task-github-denied-"));
cleanups.push(() => rm(root, { recursive: true, force: true }));
const bin = path.join(root, "managed"), real = path.join(root, "real");
await mkdir(bin); await mkdir(real);
await writeFile(path.join(bin, "gh"), githubLauncherSource({ brokerFile: true }), { mode: 0o700 });
await writeFile(path.join(real, "gh"), '#!/usr/bin/env node\nprocess.stdout.write(process.env.GH_TOKEN || "anonymous");\n', { mode: 0o700 });
let requests = 0;
const server = createServer((_req, res) => { requests++; res.writeHead(status); res.end(); });
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
cleanups.push(() => new Promise<void>(resolve => server.close(() => resolve())));
const url = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
await writeFile(path.join(bin, "broker.json"), JSON.stringify({ url, token: "denied-run" }));
const started = Date.now();
const result = await exec(path.join(bin, "gh"), [], { env: { ...process.env, PATH: `${bin}:${real}:${process.env.PATH}` } });
expect(result.stdout).toBe("anonymous");
expect(result.stderr).toContain("capability_rejected");
expect(requests).toBe(1);
expect(Date.now() - started).toBeLessThan(3000);
});