RomanNum3ral
/
paperclip
mirror of https://github.com/paperclipai/paperclip.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
paperclip/packages/adapter-utils
History
Dotta 3369c0dab7
fix(prompt): render exact branch name with backtick-safe fence in wake branch guard (#9326) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents run heartbeats inside execution workspaces pinned to a
specific git branch; the wake prompt now carries a one-time "stay on
this branch" guard (#9319)
> - Greptile's final review round on #9319 landed after the PR merged:
the guard sanitized the branch name by stripping backticks, which
mutates the ref, so the prompt could tell the agent to stay on a branch
name that does not exist
> - A guard that names the wrong branch defeats its purpose and still
leaves the workspace contract breakable
> - This pull request keeps the pinned ref name exact and instead
escapes it at render time with a backtick fence longer than any backtick
run inside the name (standard Markdown inline-code escaping)
> - The benefit is the guard always names the real branch while a
hostile ref name still cannot close the code span or inject prompt text

## Linked Issues or Issue Description

Refs #9319 — follow-up addressing the final Greptile review round that
arrived after that PR merged.

## What Changed

- `normalizePaperclipWakeExecutionWorkspace` no longer strips backticks
from the branch name; it removes only control characters (illegal in git
ref names, and the newline route into the prompt), trims, and caps
length.
- Added a `markdownInlineCode` helper that wraps a value in an
inline-code span whose backtick fence is one longer than the longest
backtick run in the value, and used it when rendering the branch guard
line.
- Updated the hostile-branch-name test to assert the exact ref is
preserved and fenced, and control characters are removed.

## Verification

- `pnpm vitest run packages/adapter-utils/src/server-utils.test.ts` — 58
tests pass, including the updated hostile-branch-name case.
- `npx tsc --noEmit` in `packages/adapter-utils` — clean.
- Manual: render a wake payload with `branchName: "evil` + backtick +
`name"` and confirm the guard line reads ``` `` evil`name `` ``` and the
span does not break.

## Risks

- Low risk: prompt-rendering-only change; the normalized payload shape
is unchanged. Branch names containing backticks (extremely rare) now
render exactly instead of mutated.

## Model Used

- Claude Fable 5 (`claude-fable-5`, Anthropic) with extended thinking
and tool use, via Claude Code / Paperclip agent harness.

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

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

Co-authored-by: Paperclip <noreply@paperclip.ing>
 		2026-07-09 18:23:54 -05:00
..
src fix(prompt): render exact branch name with backtick-safe fence in wake branch guard (#9326) 2026-07-09 18:23:54 -05:00
CHANGELOG.md
…
README.md
…
package.json Make ACP the default engine for local adapters (#9238) 2026-07-08 19:05:03 -07:00
tsconfig.json
…

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.