mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 04:02:18 +01:00
Devin Foley
7a3815eb9a
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Heartbeat runs prepare an execution workspace for each issue; with
isolated workspaces (or low-trust runs), the `git_worktree` strategy
needs a real git checkout as its base
> - For repo-only project workspaces, the server materializes the
checkout with a managed `git clone`; when that clone fails, the resolver
drops the error and silently falls back to the agent home directory with
`source: "project_primary"`
> - The pre-dispatch guard then reports
`git_worktree_base_not_git_checkout`, which hides the real cause; if the
fallback directory happens to be a git checkout, the run silently builds
worktrees off the wrong repository
> - This pull request records materialization failures on the resolved
workspace, marks the fallback explicitly, and fails the guard with a
truthful `git_worktree_base_materialization_failed` reason that carries
the clone error
> - The benefit is that operators see the real cause (a failed clone) in
the run error, the blocked-issue comment, and the recovery next action,
instead of a misleading symptom
## Linked Issues or Issue Description
**What happened?**
An issue configured for isolated `git_worktree` execution on a project
whose only workspace is repo-only (a `repoUrl` with no local path) fails
every run with `workspace_validation_failed` and reason
`git_worktree_base_not_git_checkout`, pointing at the agent home
directory. The message does not mention that the managed `git clone` of
the project repository failed (for a private repository the clone can
never succeed without credentials). The recovery flow then blocks the
issue with the same misleading explanation. Run warnings claim "Project
workspace has no local cwd configured" even though the workspace is
configured and the clone failed.
**Expected behavior**
The run failure, the blocked-issue comment, and the recovery next action
should state the real cause: the project workspace checkout could not be
prepared, including the clone error, so the operator can repair the
repository URL, clone access, or configured local cwd. A fallback
directory that happens to be a git checkout must not let the run proceed
against the wrong repository.
**Steps to reproduce**
1. Create a project whose primary workspace has a `repoUrl` pointing at
a private GitHub repository and no local path.
2. Enable the Isolated Workspaces experimental setting (or use a
low-trust run, which forces isolation).
3. Run any issue in that project.
4. The run fails with `git_worktree_base_not_git_checkout` on the agent
home directory; the clone failure appears nowhere.
**Paperclip version or commit**
`master` (bd86dbe41b).
## What Changed
- `resolveAnchorWorkspaceForRun` collects every failed project-workspace
materialization attempt (previously the error was dropped unless the row
was the preferred workspace) and returns two new fields on
`ResolvedWorkspaceForRun`: `baseCwdFallback` and
`materializationFailures`. The `source` label is unchanged because
session migration keys off `source === "project_primary"`.
- `assertGitWorktreeBaseWorkspaceReady` accepts the anchor facts and
fails with the new reason `git_worktree_base_materialization_failed` —
checked before the git-checkout probe, so a fallback directory that
happens to be a git repo can no longer host worktrees for the wrong
repository. The message carries the first scrubbed clone error and
remediation, and lands in `run.error`, the persisted
`workspaceValidation` payload, and the blocked-issue comment.
- New `scrubGitCredentialText` masks URL userinfo (a `repoUrl` can
legitimately embed credentials today) before errors reach warnings or
persisted payloads.
- Fallback warning assembly moved into the pure helper
`buildAnchorFallbackWorkspaceNotes`; a clone failure now produces
"Failed to prepare the project workspace checkout: …" instead of the
false "no local cwd configured", with the existing warning texts
preserved byte-for-byte when nothing failed to materialize.
- The workspace-validation recovery comment and the recovery service's
next action explain the new reason specifically.
## Verification
- `cd server && npx vitest run
src/__tests__/heartbeat-workspace-session.test.ts` — new cases: the new
reason takes precedence over the git-checkout probe (fallback cwd is a
real git repo), payload carries the scrubbed failures, anchor-absent
legacy behavior unchanged, scrubber unit tests, and warning-assembly
unit tests that pin the existing texts.
- `cd server && npx vitest run
src/__tests__/issue-recovery-actions.test.ts
src/__tests__/heartbeat-process-recovery.test.ts
src/__tests__/heartbeat-retry-scheduling.test.ts` — recovery surfaces
still pass.
- `pnpm --filter @paperclipai/server typecheck` is clean.
## Risks
- Additive persisted-payload fields and a new reason string; recovery
reason handling falls through to generic text for unknown reasons, and
no UI consumes the `git_worktree_base_*` strings.
- Intentional behavior change: a repo-only project whose clone fails and
whose agent-home fallback happened to be a git checkout previously ran
in that unrelated repository; it now fails with the truthful reason. A
test locks this.
- Runs without isolated workspaces (the default) never reach the guard;
their fallback behavior is unchanged.
## Model Used
Claude Fable 5 (`claude-fable-5`, extended thinking, agentic tool use
via Claude Code CLI).
## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge