Capture bounded workspace base-ref failure diagnostics (#15719)

## Thinking Path

> - Paperclip manages AI agents and their work.
> - A run can prepare a Git worktree before an adapter starts.
> - That preparation must resolve the configured base ref.
> - The same unresolved-ref error can follow a missing ref, failed
fetch, or failed credential lookup.
> - Current failure reports do not distinguish these paths.
> - This PR records bounded outcomes from the operations that already
run.
> - Maintainers can use this evidence without changing task recovery or
hiding failures.

## Linked Issues or Issue Description

Related: #11892 established remote-only base-ref resolution and
pre-adapter recovery. I found no open PR for these diagnostics.

**What happened?**

A fresh worktree can fail with `UnresolvedWorkspaceBaseRefError`. Its
failure report has no closed fields that distinguish remote lookup,
credential lookup, fetch, and local ref-probe outcomes. An empty warning
list does not prove that a fetch ran or that a remote ref is absent.

**Expected behavior**

Keep the task-visible failure and owner recovery action. Report bounded
observations from the existing operations. Keep unknown causes
reportable.

**Steps to reproduce**

Use a local Git repository with a configured base branch that is absent.
Repeat with no origin, an inaccessible local origin, or a rejected
credential resolver. Start fresh workspace preparation. Before this
change, each path lacks the new typed observations in the failure
report. Tests use local repositories and intercepted fetch commands;
they require no external Git service.

**Paperclip version or commit**

Reproduced against source commit `1602512820`, built from source. This
affects core workspace preparation before adapter dispatch.

## What Changed

- Record closed remote lookup, credential lookup, fetch, and local
ref-probe outcomes. Limit new output parsing to 8 KiB.
- Attach evidence privately to the resolver's own error. Reject copied,
forged, inherited, accessor, and malformed evidence.
- Persist allowed values in the existing setup result and export them
through run-failure diagnostics.
- Preserve Git commands, credential fallback, warning text, recovery
actions, and Sentry reporting.
- Add real Git, heartbeat, reporter, and real Sentry envelope tests.
Document the fields and their limits.

## Verification

- Current head: `015b2737df004e971eeeb134ebc9a1024e244494`, based on
`be1bc5d494d`. The only rebase conflict was in heartbeat test imports.
All three imports were retained; `git range-diff` confirms no other
patch change.
- Full `pnpm -r typecheck` and `pnpm build` passed on the current head.
- Fresh focused tests passed: 13 real-Git producer cases, 279 complete
collector/reporter cases, two actual heartbeat recovery cases, and all
nine real Sentry SDK cases. The required-SDK gate used version 10.71.0.
Actual envelopes contain only allowed fields, with no private fixture
text or cross-event leakage.
- Independent review passed all 16 combined heartbeat cases from both
integrated changes and five real-Git probes with identical baseline
command sequences and outcomes. The original producer negative control
failed on the absent receipt; the candidate passed. No review findings
remain.
- Current-head CI is complete: 54 successful checks and two intentional
Storybook skips. Greptile is 5/5 on this exact head, with no unresolved
threads or merge conflicts.
- Local aggregate limitation: the earlier full run reported one failure
in an unchanged tool-access case and was stopped with SIGINT (exit 130)
to isolate it. Vitest did not print the deferred assertion summary. The
unchanged complete file passed 420/420 alone. That aggregate is not
claimed as a pass. Before the mechanical rebase, the complete
workspace-runtime file also passed 172/172. The fresh full CI result
covers the integrated head.
- An initial independent combined reporter run hit its database setup
timeout; the unchanged complete reporter file then passed 186/186 alone.
Earlier-head CI lost four runners and recovered on one verification
retry; current-head CI passed separately.

## Risks

- These observations do not prove that a remote ref is absent. All
affected failures remain reportable, including resumed and
provider-started runs.
- The new fields include no repository URL, ref text, customer path, raw
command output, or credential. Existing task-visible details are
unchanged.
- No migration, dependency, authorization, retry, or deployment change.

## Model Used

OpenAI GPT-6 through Codex, with tool execution and parallel independent
review. The exact serving variant and context-window size are not
exposed in this session.

## Checklist

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

Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Devin FoleyandPaperclip authored and GitHub committed 2026-10-09 12:50:03 -07:00
1 parent be1bc5d494
commit 7333e4eba8
10 files changed
+390 -19

No files matched your search

+84 -1
View File
@@ -42,6 +42,7 @@ import {
refreshRemoteTrackingBaseRef,
releaseRuntimeServicesForRun,
UnresolvedWorkspaceBaseRefError,
readUnresolvedWorkspaceBaseRefDiagnostic,
resetRuntimeServicesForTests,
resetRuntimeServicePortReservationsForTests,
MANAGED_RUNTIME_PUBLIC_URL_ENV,
@@ -291,8 +292,9 @@ async function pushRemoteOnlyBranch(
return sha;
}
function realizeWorktreeForTest(repoRoot: string, repoRef: string | null) {
function realizeWorktreeForTest(repoRoot: string, repoRef: string | null, resolveGitAuth?: Parameters<typeof realizeExecutionWorkspace>[0]["resolveGitAuth"]) {
return realizeExecutionWorkspace({
resolveGitAuth,
base: {
baseCwd: repoRoot,
source: "project_primary",
@@ -1239,6 +1241,15 @@ describe("realizeExecutionWorkspace", () => {
expect(unresolved.requestedRef).toBe("fix/does-not-exist");
expect(unresolved.recoveryIdentityRef).toBe("origin/fix/does-not-exist");
expect(unresolved.attemptedRefs).toEqual(["origin/fix/does-not-exist"]);
const diagnostic = readUnresolvedWorkspaceBaseRefDiagnostic(Object.freeze(unresolved));
expect(diagnostic).toEqual({ schemaVersion: 1, remoteLookup: "resolved", authLookup: "not_requested",
fetch: "failed", fetchExitCode: 128, fetchFailureKind: "remote_ref_not_found", refResolution: "failed", refExitCode: 128 });
diagnostic!.fetch = "succeeded";
expect(readUnresolvedWorkspaceBaseRefDiagnostic(unresolved)?.fetch).toBe("failed");
expect(JSON.stringify(readUnresolvedWorkspaceBaseRefDiagnostic(unresolved))).not.toContain("fix/");
const forged = Object.assign(new UnresolvedWorkspaceBaseRefError({ requestedRef: "private-ref",
recoveryIdentityRef: "private-ref", attemptedRefs: [] }), { baseRefDiagnostic: diagnostic });
expect(readUnresolvedWorkspaceBaseRefDiagnostic(forged)).toBeNull();
// No worktree directory was created for the fresh-create path.
await expect(
fs.stat(path.join(repoRoot, ".paperclip", "worktrees", "PAP-447-add-worktree-support")),
@@ -1299,6 +1310,78 @@ describe("realizeExecutionWorkspace", () => {
expect(unresolved.fetchError).toEqual(
expect.stringContaining("Could not refresh base ref origin/fix/unreachable"),
);
expect(readUnresolvedWorkspaceBaseRefDiagnostic(unresolved)).toEqual({ schemaVersion: 1,
remoteLookup: "resolved", authLookup: "not_requested", fetch: "failed", fetchExitCode: 128,
fetchFailureKind: "unknown", refResolution: "failed", refExitCode: 128 });
});
it.each(["missing", "empty"] as const)("records the actual lookup and fetch outcome for a %s origin", async (mode) => {
const { repoRoot } = await createClonedRepoWithRemote();
await runGit(repoRoot, mode === "missing" ? ["remote", "remove", "origin"] : ["config", "remote.origin.url", ""]);
let authCalls = 0;
const error = await realizeWorktreeForTest(repoRoot, "absent-fixture", async () => { authCalls++; return null; }).catch(error => error);
expect(error).toBeInstanceOf(UnresolvedWorkspaceBaseRefError);
if (mode === "missing") {
expect(error.fetchError).toBeNull();
expect(authCalls).toBe(0);
expect(readUnresolvedWorkspaceBaseRefDiagnostic(error)).toEqual({ schemaVersion: 1,
remoteLookup: "failed", authLookup: "not_requested", fetch: "not_attempted", refResolution: "failed", refExitCode: 128 });
} else {
// Git returns the remote name when its URL is empty, then the fetch fails.
expect(error.fetchError).toBeTruthy();
expect(authCalls).toBe(1);
expect(readUnresolvedWorkspaceBaseRefDiagnostic(error)).toEqual({ schemaVersion: 1,
remoteLookup: "resolved", authLookup: "unavailable", fetch: "failed", fetchExitCode: 128,
fetchFailureKind: "unknown", refResolution: "failed", refExitCode: 128 });
}
});
it("isolates rejected and unavailable auth lookup evidence during concurrent real Git failures", async () => {
const results = await Promise.all(["failed", "unavailable"].map(async authLookup => {
const { repoRoot } = await createClonedRepoWithRemote();
const error = await realizeWorktreeForTest(repoRoot, "absent-fixture", async () => {
if (authLookup === "failed") throw new Error("private-auth-lookup-failure");
return null;
}).catch(error => error);
expect(error).toBeInstanceOf(UnresolvedWorkspaceBaseRefError);
expect(error.fetchError).not.toContain("private-auth-");
return { authLookup, diagnostic: readUnresolvedWorkspaceBaseRefDiagnostic(error) };
}));
for (const { authLookup, diagnostic } of results) expect(diagnostic).toEqual({ schemaVersion: 1,
remoteLookup: "resolved", authLookup, fetch: "failed", fetchExitCode: 128,
fetchFailureKind: "remote_ref_not_found", refResolution: "failed", refExitCode: 128 });
});
it.each([
["authentication_failed", "fatal: Authentication failed for 'https://fixture.example.invalid/private-repo'\n", 128],
["dns_failure", "fatal: unable to access 'https://fixture.example.invalid/private-repo': Could not resolve host: fixture.example.invalid\n", 128],
["unknown", "fatal: Authentication failed for 'https://fixture.example.invalid/private-repo'\nfatal: unable to create local lock\n", 128],
["unknown", "fatal: Authentication failed for 'https://fixture.example.invalid/private-repo'\n" + "private-output".repeat(700), 128],
[undefined, "", 0],
] as const)("records only bounded fetch process evidence (%s)", async (kind, stderr, code) => {
const { repoRoot } = await createClonedRepoWithRemote();
await runGit(repoRoot, ["remote", "set-url", "origin", "https://fixture.example.invalid/private-repo"]);
const bin = path.join(repoRoot, "fixture-bin"), calls = path.join(repoRoot, "fixture-calls.jsonl");
await fs.mkdir(bin);
await fs.writeFile(path.join(bin, "git"), `#!${process.execPath}
const fs = require("node:fs");
fs.appendFileSync(${JSON.stringify(calls)}, JSON.stringify(process.argv.slice(2)) + "\\n");
process.stderr.write(${JSON.stringify(stderr)}, () => { process.exitCode = ${code}; });
`);
await fs.chmod(path.join(bin, "git"), 0o700);
const error = await realizeWorktreeForTest(repoRoot, "absent-fixture", async () => ({
configArgs: [], env: { PATH: `${bin}:${process.env.PATH}` }, source: "server_env",
})).catch(error => error);
expect(error).toBeInstanceOf(UnresolvedWorkspaceBaseRefError);
const diagnostic = readUnresolvedWorkspaceBaseRefDiagnostic(error);
expect(diagnostic).toEqual({ schemaVersion: 1, remoteLookup: "resolved", authLookup: "resolved",
fetch: code === 0 ? "succeeded" : "failed", fetchExitCode: code,
...(kind ? { fetchFailureKind: kind } : {}), refResolution: "failed", refExitCode: 128 });
expect(JSON.stringify(diagnostic)).not.toContain("private-");
expect(JSON.stringify(diagnostic)).not.toContain("example.invalid");
expect((await fs.readFile(calls, "utf8")).trim().split("\n").map(line => JSON.parse(line))).toEqual([
["fetch", "--prune", "origin", "+refs/heads/absent-fixture:refs/remotes/origin/absent-fixture"],
]);
});
it("rejects reusing an empty directory that only looks like a worktree because it sits inside the repo", async () => {