## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Paperclip Runner package needs one provider-neutral session loop
> - Native execution contracts now define the accepted input and output
> - Backends still need bounded execution, recovery, and control-plane
ports
> - This pull request adds that package-local session runtime
> - It does not change server runtime selection or start the
experimental runner
> - The benefit is a tested execution core for later provider and server
layers
## Linked Issues or Issue Description
**Subsystem affected**
packages/paperclip-runner
**Problem or motivation**
The runner contracts do not yet have a shared session loop. Each backend
would otherwise duplicate event handoff, terminal handling, recovery
cursors, timeouts, and checkpoint behavior.
**Proposed solution**
Add the native session runtime, backend interfaces, control-plane port,
harness driver contract, deterministic conformance helpers, and bounded
tests.
**Alternatives considered**
The server could own this loop. That would mix provider process behavior
with server persistence and authority logic.
**Roadmap alignment**
This is part of the existing experimental Paperclip Runner rollout. It
does not enable a production adapter.
## What Changed
- Add a provider-neutral native session execution loop.
- Add recovery cursor reconciliation and checkpoint hooks.
- Add bounded timeout and governed-wait behavior.
- Add harness driver and control-plane conformance helpers.
- Add deterministic backend and session runtime tests.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm --filter @paperclipai/paperclip-runner typecheck:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- Protocol generation and manifest checks pass.
- The branch changes 14 files relative to its declared base.
## Risks
The main risk is a session that hangs, duplicates an event, or restores
the wrong cursor after reconnect. Tests cover terminal events, timeouts,
durable handoff, duplicate receipts, recovery, continuity breaks, and
checkpoint updates. The change remains package-local.
> 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
OpenAI Codex, `gpt-5`, with agentic reasoning, tool use, and code
execution.
## 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 and contains no internal
Paperclip ticket id
- [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
Dotta