Files
PaperClipAI/packages/adapter-utils
414abc2dbf fix(execution-target): give a failed Git context probe a stable error code (#22093)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Before an agent run starts on a remote execution target (sandbox or
SSH), Paperclip runs a small probe that reads the Git context of the
remote workspace
> - When that probe fails, it throws a plain `Error` with one fixed
message and no code
> - Run-failure reporting groups failures by error code, never by
message. So these failures share one Sentry group with every other setup
failure that has no code
> - The thrown error also drops the exit facts of the probe. Nobody can
see from the run why the probe failed
> - This pull request gives the probe failure a stable code and a
bounded reason
> - The benefit is a separate, correctly named Sentry group for this
failure, and run records that show why the probe failed

## Linked Issues or Issue Description

**What happened?**
On staging, many runs failed during setup with "Could not read
execution-target Git context". The burst occurred during a sandbox
provider outage. These failures had no error code. The Sentry
fingerprint for run failures uses the error code, the adapter, the phase
and the root error code or class name. Because the message is
deliberately not in the fingerprint, these failures went into the same
group as unrelated setup failures. The probe also discarded its exit
code, timeout and signal, so the cause of each failure was not recorded.

**Expected behavior**
A failed Git context probe has a stable error code, so it gets its own
Sentry group. The error message names a bounded reason (exit code,
timeout, signal, or incomplete or invalid output), so the run record
shows why the probe failed. The probe output is never included, because
it can contain credentials and paths.

**Steps to reproduce**
Run `prepareGitHubExecutionEnvironment` with a remote target whose
command runner returns a non-zero exit code, a timeout, a signal, or
output without the probe frame. On current master the error has no
`code` and no reason.

## What Changed

- `packages/adapter-utils/src/execution-target.ts`: add
`EXECUTION_TARGET_GIT_CONTEXT_UNAVAILABLE_CODE`
(`execution_target_git_context_unavailable`). The three probe failure
paths now throw an `Error` with this code. The message keeps the old
prefix and adds a bounded reason: exit code, timeout, signal, or
incomplete or invalid output.
- The probe output is never put in the message.
- An error that the command runner throws itself (for example a provider
HTTP error) is not changed. It keeps its own code and status.
- The success condition is not changed.
- `packages/adapter-utils/src/github-launcher-environment.test.ts`: add
tests for each failure reason, a test that the probe output does not
leak into the message, and a test that a runner error passes through
unchanged.

## Verification

- `vitest run
packages/adapter-utils/src/github-launcher-environment.test.ts
packages/adapter-utils/src/execution-target*`: 273 tests pass, including
the 6 new tests.
- Red/green: on the unfixed source, 5 of the 6 new tests fail. The
runner-error test passes on both, as intended, because it checks
behavior that must not change.
- `tsc --noEmit -p packages/adapter-utils/tsconfig.json` passes (sources
and tests).
- One existing test, "preserves local host credential helpers and
validates worktree metadata", fails in my local sandbox on unmodified
master too. It depends on the local Git configuration. CI covers it.

## Risks

- Low risk. Only the error that the probe throws changes. The success
path and the conditions for failure do not change.
- `resultJson.failureCause` for these runs becomes
`execution_target_git_context_unavailable` instead of `Error`. No code
compares `failureCause` with `Error`.
- New Sentry events for this failure go to a new group. The old shared
group stops receiving them.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used as an agent with
tool use and code execution (shell, Git, Vitest).

## 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
- [ ] 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

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

---------

Co-authored-by: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 02:18:15 -08:00
..

@paperclipai/adapter-utils

Shared utilities for Paperclip adapters: process spawning, environment injection, sandbox/SSH transport, workspace sync, and the round-trip helpers that move code between the local execution-workspace cwd and wherever the agent actually runs.

For the adapter-author guide see docs/adapters/creating-an-adapter.md and the in-repo notes at packages/adapters/AUTHORING.md.

Sandbox bridge deadlines

Command-managed bridge control operations (queue reads, input delivery, setup, and cleanup) have a host-enforced deadline of at most 30 seconds per shell command. A shorter configured timeout still applies. These operations cannot inherit the agent run's hours-long lifetime or wait forever on a provider that ignores its timeout. Long-lived agent session commands keep their own limits.

A control timeout reports a transport failure. It does not prove that the remote command stopped and does not replay an uncertain write. The process session closes failed input delivery and uses its existing shutdown path; normal execution settlement must still verify termination.

Native archive transfer deadlines

Native syncIn and syncOut calls accept an optional minimumTimeoutMs budget. The server validates this budget and extends the worker RPC deadline. Providers can honor this field for file transfers without changing their configuration. Daytona uses the larger of this minimum and its configured timeout. Other providers keep their existing behavior. The minimum is limited to 30 minutes and does not change sandbox lifetimes, stored settings or the timeout for other commands.

The remote-workspace archive path uses the verified capture size for downloads and the local archive size for uploads. Large archives get one second per MiB plus 60 seconds, capped at 30 minutes. Small archives keep the existing provider timeout when that calculation is no greater than five minutes. Archive size, checksum, confinement and host space checks still apply.

An exact retained-sandbox resume keeps its recorded provider timeout and RPC overhead. It uses the normal one-minute fallback only when no timeout was recorded. A five-minute cold restore must not be cut off by that fallback. Resume still targets the recorded allocation and does not acquire a replacement.

No-remote-git contract

The local execution-workspace cwd is the only persistence boundary across runs. No adapter may depend on a git remote for cross-run state.

Adapters that run the agent on a different host should use the SSH round-trip helpers in src/ssh.ts:

  • prepareWorkspaceForSshExecution({ spec, localDir, remoteDir }) — bundles the local cwd (tracked files, dirty edits, untracked additions, and the git history needed to reconstruct it) to remoteDir before the run starts. Runs with no git remote configured.
  • restoreWorkspaceFromSshExecution({ spec, localDir, remoteDir, ... }) — syncs the remote cwd back into localDir after the run, including any new commits the agent created. Also runs with no git remote configured.

prepareRemoteManagedRuntime in src/remote-managed-runtime.ts wraps both calls for adapters that want a per-run remote workspace and an automatic restoreWorkspace() finally hook.

The invariant is pinned by the no-remote-git contract case in src/ssh-fixture.test.ts, which asserts that a remote-only commit propagates to the local worktree through the prepare → restore round-trip with no git remote configured at any point. Do not regress that test.