0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-07 16:11:46 +02:00

Files

T

Nicky LeachandPaperclip e628cf35da fix(adapter-utils): harden the wrapper birth-time probe with exclusive create and identity-aware cleanup (#12248 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Adapter utilities run process sessions in local and remote
environments.
> - The remote process-session wrapper uses a probe file to verify
directory creation time.
> - A peer could pre-create the probe path or replace it before cleanup.
> - This pull request uses exclusive create and file-descriptor identity
checks to protect the probe.
> - The benefit is safer cleanup and fail-closed behavior at the sandbox
boundary.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The remote process-session wrapper creates and removes a birth-time
probe file. The old path-based flow did not prove that the wrapper
created the path or that the path still named the same file.

**Current behavior**

A sandbox peer can race with the probe path. The peer can pre-create a
symbolic link or replace the probe before cleanup. The wrapper can then
inspect or remove an object that it did not create.

**Proposed behavior**

The wrapper creates the probe with exclusive create. It reads `(dev,
ino, ctimeMs)` from the open file descriptor. It removes the path only
when a final identity read matches the created file.

**Reason and benefit**

This change prevents symlink-following during creation and avoids
removal of a peer's replacement object. The wrapper still fails closed
when it cannot prove a real creation time.

**Breaking changes**

None. The wrapper keeps its existing fail-closed capture behavior.

## What Changed

- Create the birth-time probe with `fs.open(path, "wx")`.
- Read probe identity with `fstat` from the open descriptor.
- Remove the probe only after a matching final identity read.
- Add focused race tests for ordinary cleanup and file, directory, and
symbolic-link replacement.

## Verification

- Run `pnpm --filter @paperclipai/adapter-utils exec tsc --noEmit`.
- Run the focused suite
`packages/adapter-utils/src/execution-target-stdin-race.test.ts`.
- Confirm that the focused suite passes all 33 tests.

## Risks

The change affects shared wrapper source for local and remote process
sessions. An identity read or cleanup failure leaves the probe in place
and stops capture. The focused tests cover the new race paths.

## Model Used

OpenAI Codex, GPT-5, tool use and code execution. The model reviewed and
prepared this pull request from the supplied implementation and test
results.

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

2026-08-26 17:51:36 -07:00

src

fix(adapter-utils): harden the wrapper birth-time probe with exclusive create and identity-aware cleanup (#12248 )

2026-08-26 17:51:36 -07:00

CHANGELOG.md

fix: bound workspace Git scans (#11572 )

2026-08-17 22:11:30 -05:00

package.json

build(deps-dev): bump typescript from 5.9.3 to 7.0.2 (#11880 )

2026-08-25 14:49:05 -07:00

README.md

PAPA-430: workspace finalize gates + no-remote-git enforcement (#6969 )

2026-05-29 08:25:29 -07:00

tsconfig.json

Fix root TypeScript solution config

2026-03-09 14:09:30 -05:00

README.md

@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.

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.