## Thinking Path
> - Paperclip manages AI agent work and the execution state for each
task.
> - Remote agents run in sandbox environments such as Daytona.
> - Daytona keeps files while a sandbox is stopped, but deletion removes
those files.
> - Runner Codex did not copy successful remote workspace changes back
to the host workspace.
> - A warm sandbox could therefore hide data loss until Daytona replaced
or deleted the sandbox.
> - This pull request makes the host workspace durable after every
successful turn and keeps verified reusable sandboxes warm.
> - The benefit is reliable multi-turn work across warm reuse, restart,
stop, and sandbox replacement.
## Linked Issues or Issue Description
**What happened?**
A successful native Codex turn in Daytona could leave workspace changes
only in the remote sandbox. A later warm turn appeared to work because
it reused that filesystem. A replacement sandbox could start from stale
host data and lose the successful changes.
**Expected behavior**
Paperclip must merge each successful remote turn into the authoritative
host workspace before it completes the run. A verified warm lease may
reuse its remote files. A replacement lease must reconstruct the exact
durable workspace seed.
**Steps to reproduce**
1. Run Codex in a reusable Daytona environment.
2. Write a file during one successful turn.
3. Replace the Daytona sandbox before the next turn.
4. Observe that the next turn can start without the prior file on the
unpatched code.
Related remote workspace foundation: #10070.
## What Changed
- Added explicit `host_current`, `durable_seed`, and `adopt_remote`
workspace preparation modes.
- Added atomic, versioned native workspace descriptors and seed archives
under `PAPERCLIP_HOME`.
- Added real native sandbox export and three-way host merge before
terminal result completion.
- Added workspace-only recovery after a proposed result. Recovery does
not submit another provider turn or consume the provider retry budget.
- Added fail-closed handling when a sandbox with unexported changes is
gone.
- Kept healthy reusable Daytona sandboxes started for legacy Codex and
Runner Codex.
- Kept the Runner Codex process and provider session across verified
warm turns.
- Added the paid `daytona-warm-continuity` browser suite. It contains
exactly the legacy Codex and Runner Codex cells. Each cell performs
three measured turns.
- Documented `pnpm test:e2e:runner -- --suite daytona-warm-continuity`.
No package script was added.
- Added no database migration. The metadata format is backward
compatible and idempotent.
## Verification
- `pnpm typecheck`
- `pnpm test:e2e:runner:unit` — 114 passed
- Native workspace, finalizer, session, and environment tests — 232
passed
- Daytona provider tests — 150 passed
- Workspace staging and merge tests — 98 passed
- Runner transport tests — 63 passed
- Legacy Codex restore tests — 5 passed
- Rust format and compile checks pass through root typecheck
- The paid Daytona suite was not run locally because the required
Daytona, OpenAI, and immutable image credentials are not present.
## Risks
- The main risk is an incorrect workspace identity or merge after a
crash. Durable descriptors bind the run, workspace, lease, provider
lease, local root, remote root, and baseline digest. Ambiguous evidence
fails closed.
- The host merge may conflict with concurrent host edits. The existing
three-way merge and exclusion rules handle this case and surface
failures.
- A deleted sandbox cannot recover unexported bytes. Paperclip now
blocks with `workspace_sync_out_unrecoverable` instead of reporting
success or rerunning the provider.
- There is no database migration. Descriptor writes and recovery are
atomic and idempotent.
## Model Used
OpenAI Codex with GPT-5. The run used agentic reasoning, repository
inspection, code execution, test execution, Git, and GitHub CLI tools.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agent authentication uses server sessions, plugin workers, and
browser login panels.
> - A page reload loses an active login session, and one worker permits
only one login terminal.
> - These limits cause lost work and prevent two owners from logging in
through one worker.
> - This pull request lets the browser resume active sessions and lets
workers serve concurrent login terminals.
> - The benefit is reliable login recovery with a bounded process-wide
route limit.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
It improves agent credential login recovery and concurrent login
terminal handling.
**Subsystem affected**
Cross-cutting (multiple of the above).
**Current behavior**
A page reload loses the active login session. A shared plugin worker
rejects a second login terminal.
**Proposed behavior**
The browser reads and resumes the owner's active session. A worker
supports multiple login terminal routes under a process-wide ceiling.
**Reason and benefit**
Owners keep login progress after a reload. Two owners can log in through
one worker without removing the route limit.
**Breaking changes**
None. The change adds owner-scoped read routes and changes login
terminal concurrency.
## What Changed
- Replace the single worker login route with maps keyed by host route
and worker session identifiers.
- Add a process-wide login route ceiling and release each reserved slot
on every exit path.
- Add owner-scoped active-session reads with consistent negative
responses and private cache control.
- Keep the device-login prompt while the session has an active public
status.
- Add a durable setup-token cancel fallback for a lost in-memory
session.
- Resume active sessions when the agent configuration or onboarding
panel mounts.
- Remove routine unmount cancellation and keep explicit Cancel behavior.
## Verification
- `pnpm --filter @paperclip/server test` — server route, service, and
plugin-worker-manager suites.
- `pnpm --filter @paperclip/plugin-sdk test` — worker RPC host suite.
- `cd ui && npx vitest run
src/components/AgentConfigForm.render.test.tsx
src/components/OnboardingWizard.test.tsx`.
- `cd ui && npx tsc -b`.
- `tests/e2e/onboarding.spec.ts` — reload during login.
- CI must pass on this pull request.
## Risks
The change affects agent authentication and the sandbox-to-host
boundary. Route cleanup must release every reserved slot. Owner checks
must prevent cross-owner session access. Tests cover route cleanup,
owner scope, reload recovery, and concurrent worker routes.
## Model Used
Codex, OpenAI GPT-5, tool use and code review support. The
implementation author owns the exact model details for the code changes.
## 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 described the issue in-PR with the relevant issue-template
fields
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [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 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>
## Thinking Path
> - Paperclip manages AI agents and their work.
> - The runner executes agent turns on local and remote providers.
> - A remote per-turn session must save its state before Paperclip
releases its sandbox.
> - The session runtime returned after 100 milliseconds while the remote
checkpoint still ran.
> - The next turn also checked the local state path instead of the
verified remote backup.
> - This pull request waits for the bounded remote close and accepts
only a verified suspended backup.
> - The benefit is reliable multi-turn execution without weaker identity
checks.
## Linked Issues or Issue Description
**What happened?**
A successful remote agent turn released its sandbox before the runner
saved the verified continuation backup. The next turn failed with
`runner_state_identity_mismatch`.
**Expected behavior**
Paperclip must finish the bounded remote checkpoint before it releases
the sandbox. A later turn must validate and restore the digest-matched
suspended backup.
**Steps to reproduce**
1. Run a native ACPX Claude Plan test in a non-reusable Daytona sandbox.
2. Reject the first plan to start a second turn.
3. Observe that the second turn fails before provider execution.
**Paperclip version or commit**
The failure reproduced at `13775a90b078ff64872f50961ea1b83d575e7bc6`.
**Deployment mode**
GitHub Actions with a Daytona sandbox.
## What Changed
- Wait for the internally bounded remote runner close and checkpoint
before the host returns.
- Preserve the existing short cleanup bound for other providers.
- Validate remote continuation lifecycle from a complete digest-verified
backup when local runner state is absent.
- Keep corrupt, non-suspended, mismatched, and unverified state
fail-closed.
- Make native Plan completion and accepted-Plan wake prompts
deterministic.
## Verification
- A prior 45-cell local campaign passed 44 cells. The only failure was
the OpenCode Plan prompt variance fixed here.
- A focused OpenCode local Plan rerun passed.
- ACPX Claude Daytona message and question cells passed.
- Focused regressions cover delayed checkpoint close and verified remote
backup lifecycle.
- GitHub Build and the focused ACPX Claude Daytona Plan cell will
validate this exact head.
## Risks
Remote runnerd sessions now wait for their internally bounded
close/checkpoint path before returning; generic provider cleanup retains
the existing 100 millisecond bound. Durable run success still cannot be
reversed. The environment release guard still blocks sandbox destruction
when no verified backup stamp exists.
## Model Used
OpenAI Codex, GPT-5.6, extended reasoning, with code execution and
GitHub Actions inspection.
## 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 task
id
- [ ] 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 findings
- [ ] I will address all Greptile and reviewer comments before
requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents need source control access for repository work
> - A shared token cannot preserve the responsible person's identity or
an agent's dedicated identity
> - GitHub App tokens also need durable refresh, repository access
checks, and webhook delivery
> - Paperclip already has managed connections, encrypted grants, run
secret leases, and merge-confirmation behavior
> - This pull request extends those systems with GitHub identities
instead of adding a parallel credential system
> - The benefit is durable GitHub access with explicit identity,
repository, runtime, and webhook boundaries
## Linked Issues or Issue Description
No public GitHub issue describes this connection change. This
description follows the feature request template.
**Subsystem affected**
Connected Apps, connection grants, secret resolution, native Git runtime
setup, webhook processing, and the Apps UI.
**Problem or motivation**
Users need to connect GitHub once and let agents use the correct GitHub
identity. A run should use a dedicated agent account when one exists.
Otherwise, it should use the responsible person's account. The
connection must survive token expiry, repository access changes, and
temporary instance downtime.
**Proposed solution**
Add user-owned and agent-owned GitHub grants to the existing connection
model. Resolve one identity for MCP, Git, `gh`, health checks, and
webhook bindings. Store provider tokens in the existing encrypted secret
system. Refresh expiring token pairs under the existing lease and
compare-and-swap path. Register signed Cloud webhook bindings and
process normalized pull request and installation events through a
durable local inbox.
**Alternatives considered**
An organization-wide GitHub token would lose person and agent
attribution. Environment variables alone would bypass the managed
connection and grant model. A new GitHub-only credential store would
duplicate the existing secret and access systems. GitHub App
installation tokens and private-key custody remain outside this first
version.
**Roadmap alignment**
This change implements the Connected Apps direction. It also extends the
shipped MCP Tool Gateway, per-agent secret access, and
action-attribution systems. It does not add a repository catalog. The
open repository catalog work in
[#11234](https://github.com/paperclipai/paperclip/pull/11234) is related
and complementary.
## What Changed
- Added agent-owned connection grants and a per-agent credential policy
with company and subject constraints.
- Added a managed GitHub App method while keeping the personal access
token method as an advanced fallback.
- Added durable access-token and refresh-token handling with proactive
rotation and one automatic recovery after a provider `401`.
- Added GitHub identity and installation summaries without storing
repository-name lists.
- Added signed Cloud webhook binding, event lease, acknowledgement,
local idempotency, pull request merge processing, and installation
access handling.
- Added one identity resolver for MCP, native Git, `gh`, checkout,
health checks, and webhook bindings.
- Added a class-3 run projection for `GH_TOKEN`, `GITHUB_TOKEN`, a
`github.com`-only credential helper, SSH-to-HTTPS rewrite, and GitHub
noreply commit attribution.
- Added personal and dedicated-agent setup choices plus identity,
repository, continuity, and webhook status in the Apps UI.
- Added schema migrations, tests, and connection documentation.
## Verification
- The current head is fully green in GitHub CI, including build,
typecheck, all serialized/general server shards, all browser shards,
policy, canary dry run, review, and security checks.
- Live staging proof completed with a non-expiring GitHub App user
token, selected-repository installation, repository add/remove refresh,
managed MCP, native `gh`, HTTPS clone/push/delete, GitHub noreply commit
attribution, signed merged-PR webhook acceptance, durable
Cloud-to-instance delivery, and installation-access event processing.
Temporary branches and temporary repository access were removed
afterward.
- `pnpm check:token-gates` passed.
- `pnpm -r typecheck` passed before and after the rebase onto
`origin/master`.
- `pnpm build` passed.
- The focused connector suite passed 285 tests after the rebase.
- The full stable suite passed 5,790 tests and failed 22 tests across 8
general server files. The failures reproduced as shared-runner
environment issues. They included `/tmp` versus `/private/tmp`, closed
database connections, and invalid high ephemeral ports. The focused
connection tests pass in isolation.
## Risks
- Migrations add agent grant subjects and a durable connection-event
inbox. Migration numbering and safety checks pass.
- A raw GitHub user token enters the agent process for Git and `gh`.
Per-tool Ask-first controls cannot limit those shell operations. The UI
warns users about this boundary.
- GitHub App user tokens can be non-expiring. Paperclip performs a
continuity check every 30 days, but provider revocation still requires a
reconnect.
- The webhook path accepts only signed and bounded payloads. It stores a
minimal normalized record and no raw provider payload.
- GitHub repository permissions remain authoritative. Removed access can
make a cached repository count temporarily stale, but runtime access
fails immediately.
> 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.6-sol`, extended reasoning, tool use, code
execution, browser control, and multi-file repository editing. The
context window size was not provided.
## 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
- [ ] 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner owns durable provider sessions and streams their
work to the control plane.
> - Pull request #12845 added native restart recovery for live and dead
local runners.
> - A real browser test found three live-adoption gaps after that pull
request merged.
> - Lazy runner process ownership was not always stored before restart.
> - The old controller did not release its PRP authority without closing
the provider turn.
> - Reconnect events could arrive before the active provider turn was
restored.
> - This pull request closes those gaps and proves the same turn
completes after a UI hot restart.
## Linked Issues or Issue Description
Refs #12845
Related search results: #12646 covers indeterminate command results
after a runner restart. It does not cover controller adoption or
active-turn rebinding. No open duplicate pull request was found.
## What Changed
- Store lazy runnerd process ownership after provider session creation,
read, and resume.
- Detach native PRP controller authority during coordinated hot
shutdown. Keep the live provider turn running.
- Restore the exact checkpointed provider session when bounded PRP
identity events have been compacted.
- Restore the active provider turn before reconnect events are replayed.
This prevents `turn_binding_mismatch`.
- Keep exact live ownership by the current controller out of generic
orphan recovery.
- Add driver, transport, and server regression tests for these paths.
## Verification
- Ran 12 Codex driver lifecycle tests.
- Ran 53 runnerd transport tests.
- Ran 143 recovery and orphan-reaper server tests.
- Ran all 8 real-process restart recovery scenarios.
- Ran all 96 existing runner E2E unit tests.
- Ran runner TypeScript typecheck.
- Ran server TypeScript typecheck.
- Ran the migration replay test and migration safety checks.
- Tested the board UI on an isolated local instance. A real local
Codex-backed turn entered a 120-second terminal wait. The UI `Restart
now` action replaced the server and kept the same runner PID, process
start time, run ID, native session ID, runner ID, provider session ID,
and active turn. The original turn then completed.
- Confirmed one heartbeat run, no retry row, one result, one
proposed-result event, one terminal event, no protocol errors, no active
recovery state, and no surviving runner or provider process.
## Risks
- A live runner can continue provider work while no server owns the
control route. Recovery fails closed when the process fingerprint or
durable identity is ambiguous.
- Provider identity can be restored from the database only for an exact
verified adoption claim. An authenticated live `session.snapshot`
validates that identity before the driver can resume.
- The new detach path applies only to native sessions that expose
restart detachment. Other adapters keep their existing shutdown
behavior.
- This follow-up does not change the database migration or
`package.json`. The migration in #12845 remains replay-safe through `ADD
COLUMN IF NOT EXISTS` and its embedded-Postgres idempotence test. The
dedicated real-process command remains in `doc/DEVELOPING.md`.
## Model Used
- OpenAI Codex based on GPT-5. The exact serving build and
context-window size are not exposed. The run used extended reasoning,
repository tools, shell execution, and in-app browser automation.
## 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 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
## Thinking Path
> - Paperclip is the open source app that people use to manage AI agents
for work.
> - The Codex local adapter supplies model metadata to the server and
the user interface.
> - OpenAI now lists `gpt-6-astra` as a supported Codex model.
> - Paperclip did not list this model or its model-specific controls.
> - This pull request adds the model through the existing adapter
metadata path.
> - The benefit is that agents and task overrides can use the exact
model ID and supported controls.
## Linked Issues or Issue Description
**Subsystem affected**
`packages/adapters` and `ui`
**Problem or motivation**
Paperclip does not expose `gpt-6-astra` in Codex model selectors.
Operators cannot select and save the model through the normal agent and
task forms.
**Proposed solution**
Register the exact model ID in the Codex local adapter. Use the adapter
as the source for the model-specific reasoning options. Preserve the
current default model. Forward the saved model, reasoning effort, and
fast-mode controls through both Codex execution lanes.
**Alternatives considered**
A user-interface-only model list would duplicate adapter metadata. A
model alias would not match the official model ID. Both options were
rejected.
**Roadmap alignment**
This is a small adapter compatibility update. It does not duplicate a
planned item in `ROADMAP.md`.
## What Changed
- Added `gpt-6-astra` to the Codex local adapter model registry and
fast-mode support list.
- Added the official Astra reasoning efforts: `low`, `medium`, `high`,
`xhigh`, `max`, and `ultra`.
- Used the adapter metadata in agent and task model selectors.
- Preserved supported effort choices when the model changes. Cleared an
effort only when the new model does not support it.
- Added tests for registration, user-interface selection, configuration
persistence, and CLI and ACP forwarding.
## Verification
- `pnpm exec vitest run packages/adapters/codex-local/src/index.test.ts
packages/adapters/codex-local/src/server/acp.test.ts
packages/adapters/codex-local/src/server/codex-args.test.ts
packages/adapters/codex-local/src/ui/build-config.test.ts
ui/src/lib/codex-reasoning-effort.test.ts
ui/src/components/AgentConfigForm.render.test.tsx
ui/src/components/IssueProperties.test.tsx
ui/src/components/NewIssueDialog.test.tsx
ui/src/lib/issue-assignee-overrides.test.ts` passed 245 tests.
- `pnpm -r typecheck` passed.
- `pnpm check:token-gates` passed all four gates across 939 files.
- `pnpm --filter @paperclipai/ui build` passed and supplied isolated
user-interface build proof.
- `pnpm build` passed.
- `pnpm test:run` passed 5,812 tests and failed 24 workspace-runtime
tests in this isolated host. The failures use invalid generated ports
above 65,535, incomplete nested-worktree fixture configuration, or
`/tmp` path aliases. The focused tests for this change all pass. GitHub
CI must pass before review handoff.
- GitHub CI run `33918372718` passed all required checks and the
aggregate verify gate on exact head
`6ac6be2cee0a5996c82bdf674fcb7f46cb4c5fde`.
- Independent engineering review approved the exact remediation head
after 170/170 reviewer tests passed.
- Greptile reported 5/5 with no open review threads on exact head
`6ac6be2cee0a5996c82bdf674fcb7f46cb4c5fde`.
- The model ID and capabilities were checked against the [official
OpenAI Codex model list](https://developers.openai.com/codex/models).
## Risks
- Low risk. The change adds one model and model-specific selector
options. It does not change the default model.
- OpenAI can change model capabilities later. The adapter metadata must
stay aligned with the official Codex metadata.
> 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 with model ID `gpt-5.6-sol`, a 272,000-token context
window, 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 (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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The Paperclip Runner keeps durable run and provider state outside
one server process.
> - A server restart can leave that runner alive or can interrupt it
after a provider checkpoint.
> - The old startup path used handoff intent and PID evidence, but it
did not reconstruct native ownership.
> - That gap could block the issue, create a replacement run, or start
duplicate provider work.
> - This pull request adds durable same-run recovery for coordinated and
uncoordinated restarts.
> - The benefit is exact recovery of the run, runner, session, provider,
steering, and finalization state.
## Linked Issues or Issue Description
Refs #9628. That pull request added earlier local-adapter hot-restart
work. This change adds native PRP authority reconstruction and same-run
provider resume.
Refs #10935. That pull request handles missing hot-restart snapshots.
This change also supports hard restarts with no snapshot.
Refs #11624. That pull request prevents unsafe retry after an adopted
legacy process exits. This change reconciles native terminal evidence
before provider recovery.
Refs #12070. That pull request improves process liveness checks. This
change also binds recovery to a process-start fingerprint and fails
closed on ambiguity.
**What happened?**
The server could record hot-restart intent, but startup did not rebuild
native runner ownership. A live runner could not re-register its PRP
authority. A dead runner could not resume the exact native and provider
session on the same heartbeat run. Generic recovery could then block the
issue or create replacement work.
**Expected behavior**
A live native runner must reconnect with the same PID and logical
identities. A dead runner must resume the same durable session and
heartbeat run with only a new operating-system PID. A proposed or
terminal result must finalize once before any provider turn starts.
Ambiguous process or session evidence must stay blocked without a signal
or duplicate spawn.
**Steps to reproduce**
1. Start a Paperclip Runner heartbeat and wait for an active provider
turn.
2. Restart only the Paperclip server, with or without a hot-restart
marker.
3. Observe that the old startup path does not reconstruct the native
control-plane authority.
4. Kill both the server and runner after a provider checkpoint.
5. Observe that the old path cannot resume the exact native session on
the original heartbeat run.
**Paperclip version or commit**
The defect was reproduced from commit
`1991f31fd53e7f7794d5c2e4b93be384ade2b41d`. This branch is rebased onto
the current `master`.
**Deployment mode**
Local development and self-hosted server deployments that use the local
Paperclip Runner.
## What Changed
- Added correlated hot-restart requests and version-compatible native
handoff fields.
- Added controller boot identity, process-start identity, controller
generation, recovery state, request id, and bounded history to the
native finalization ledger.
- Added transactional recovery claims for live-runner reattach,
dead-runner resume, and incomplete bootstrap.
- Added fail-closed ownership takeover rules and process identity
validation.
- Added live runner adoption to the local runner transport without a
duplicate spawn.
- Added same-run provider checkpoint resume and legacy retry-row
compatibility.
- Reconciled proposed and terminal results before runner or provider
recovery.
- Bound the HTTP and PRP listener before startup recovery and delayed
scheduling and generic reapers until classification completes.
- Added restart-aware health diagnostics, run-log recovery transitions,
durable runner diagnostics, and bounded shutdown finalizer draining.
- Moved restart-survivable diagnostics into runner-owned, pre-redacted
bounded writes; raw stdout and stderr are never persisted.
- Added process-start fencing for controller, runner, and provider PIDs;
startup classifies every candidate without an implicit cap.
- Added crash-recoverable, contention-safe development restart-request
coordination and failed-startup listener cleanup.
- Added a credential-free real-process restart suite for eight restart,
scale, and identity scenarios.
- Documented native restart operation, persistence, diagnostics, and
verification.
## Verification
- The documented native restart commands passed. They ran eight
real-process/database recovery scenarios and the live runner adoption
transport test.
- Native executor tests passed: 111 tests.
- Heartbeat recovery tests passed: 124 tests.
- Hot restart, health, and shutdown tests passed: 52 tests.
- The broader affected server suite passed: 350 tests.
- Focused native recovery and startup tests passed: 49 tests.
- Runner transport and control-plane tests passed: 63 tests.
- Runner-owned diagnostic tests passed for write-time bounding,
credential redaction, private file modes, and raw stream
non-persistence.
- Development restart coordination tests passed: 11 tests.
- Database migration checks and the partial-application/replay
regression test passed.
- Server, database, and Paperclip Runner typechecks passed.
- `git diff --check` passed.
- Full Paperclip PR CI passed, including build, canary, all five general
server shards, all five serialized server shards, all three browser E2E
shards, workspace suites, and release-registry verification.
- Greptile completed at 5/5 with no outstanding findings,
recommendations, follow-ups, or open review threads.
## Risks
- Moderate risk. This changes startup ordering and ownership transfer
for active native runs.
- The migration adds nullable columns and does not rewrite existing
rows.
- Recovery fails closed when process or durable session identity is
incomplete or contradictory.
- The first implementation supports the local Paperclip Runner. Remote
targets keep their existing behavior.
- The real-process suite covers cleanup and asserts that no runner or
provider process survives each test.
> 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 with GPT-5. The runtime did not expose a more specific
model revision or context-window size. Repository editing, shell
execution, database tests, and real-process test execution were enabled.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip records agent run outcomes through telemetry and run
lifecycle services
> - Terminal run transitions need one consistent event for outcome
analysis
> - The current paths do not report every terminal transition through
one event
> - This pull request adds the agent.task_run event and emits it at each
terminal transition
> - The benefit is complete run outcome data without exposing raw task
identifiers
## Linked Issues or Issue Description
**What existing behavior does this improve?**
Paperclip telemetry reports agent activity, but it does not report every
terminal task run through one event.
**Subsystem affected**
Cross-cutting (multiple of the above): packages/shared telemetry and
server run lifecycle services.
**Current behavior**
Several run paths write a terminal status without a matching
agent.task_run telemetry event.
**Proposed behavior**
Each terminal run transition emits one agent.task_run event. The event
records the terminal state and uses the existing pseudonym helper for
the optional task identifier.
**Reason and benefit**
Complete terminal-run data helps operators measure agent outcomes. The
pseudonym helper prevents the raw task identifier from leaving the
installation.
**Breaking changes**
None. The change adds an event and keeps existing event behavior
compatible.
## What Changed
- Add the agent.task_run telemetry contract and client helper.
- Reuse the existing pseudonym helper for the task identifier. The
helper hashes the identifier with a per-installation salt and returns 16
hexadecimal characters. The raw identifier never leaves the
installation. Existing identifiers do not move.
- Emit one event from each legacy, native, recovery, and issue terminal
transition.
- Keep emissions outside database transactions and make delivery
best-effort.
- Add regression tests for event shape, hashing, terminal transitions,
and emission failures.
- Document the event and its privacy rule in the telemetry data
contract.
## Verification
- `npx tsc --noEmit` in `server/` passes at the submitted commit.
- The pull-request CI suite must pass. CI is the authority because local
Vitest has a known dependency artifact.
- The added regression tests cover event output shape, per-installation
hash divergence, raw identifier handoff, omitted identifiers, and
non-throwing emits.
## Risks
- A missed terminal path could reduce event coverage.
- Telemetry delivery remains best-effort and cannot change run
finalization.
- The pseudonym helper uses installation-specific state, so identifiers
differ between installations.
## Model Used
OpenAI Codex, GPT-5, tool use and code execution. Context window details
were not provided.
## 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 have addressed all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip manages AI agents that perform work.
> - Paperclip Runner connects durable task runs to local provider
processes.
> - The full-stack paid matrix exposed failures after the runner
integrity repair.
> - Verified JavaScript entrypoints lost their relative module graph
when Linux executed them through descriptor paths.
> - Returned provider startup errors also remained pending and became
indeterminate after recovery.
> - Sparse Codex tool lifecycle events lost the `write_document`
identity before task transcript projection.
> - This pull request repairs those three boundaries and makes the
structured-question fixture deterministic.
> - The benefit is repeatable provider startup, exact failure replay,
and correct inline Plan placement.
## Linked Issues or Issue Description
Refs #12721 and #12700.
**What happened?**
The paid runner matrix failed ACPX and OpenCode startup before provider
session creation. The runner journal then replaced the original startup
error with an indeterminate recovery result. Native Codex saved a Plan
but rendered it only as a fallback card. A legacy Claude waiting reply
could also echo the reserved terminal marker before the answer arrived.
**Expected behavior**
Verified JavaScript providers must start from immutable
descriptor-backed artifacts. Returned startup failures must persist as
terminal failed command results. Native tool lifecycle updates must
preserve the `write_document` boundary. Pre-answer fixture output must
not contain the reserved terminal marker.
**Steps to reproduce**
1. Run the local provider cells in the Runner Full-Stack E2E workflow.
2. Observe ACPX and OpenCode fail during `session.open` before provider
execution.
3. Observe recovery report `execution_indeterminate` instead of the
original startup error.
4. Run the native Codex Plan cell and observe the fallback Plan card
after the tool activity row.
5. Run the legacy Claude structured-question resume cell and observe an
early marker echo in waiting prose.
**Paperclip version or commit**
`0f9452101740835ce0b1488a204bf48acd5bafc3`
**Deployment mode**
Local development with the paid GitHub Actions acceptance workflow.
## What Changed
- Bundle the ACPX sidecar and OpenCode proxy as self-contained Node ESM
entrypoints before hashing and verified descriptor launch.
- Anchor ACPX dynamic provider package resolution at a
controller-derived provider-pack root and keep that root out of the
provider child environment.
- Persist executor-returned startup errors as redacted durable failed
command results while retaining indeterminate recovery for true process
death.
- Coalesce sparse native tool items by stable ID so a late
`write_document` name, input, and result reach the transcript boundary
once.
- Forbid the structured-question fixture from spelling or announcing its
reserved terminal marker before the user answers.
## Verification
- Rust and TypeScript regression tests cover durable failed replay, true
crash ambiguity, bundle closure, package-root derivation, environment
filtering, exact Codex tool lifecycle coalescing, and prompt
determinism.
- Local execution is intentionally limited to formatters and static diff
checks. GitHub Actions will run tests, type checks, builds, and security
checks.
- After ordinary CI is green, scoped paid cells will validate one ACPX
launch, one OpenCode launch, native Codex Plan projection, and legacy
Claude structured resume before a complete matrix rerun.
- Prior failing matrix:
https://github.com/paperclipai/paperclip/actions/runs/33682434315
## Risks
- Bundling changes the bytes covered by provider launch hashes.
Provider-pack generation already hashes the final built files.
- ACPX still loads qualified provider packages dynamically. The
controller supplies a normalized package root, while existing version,
digest, path, and descriptor checks remain active.
- Durable `failed` is terminal. Replays return the same redacted result
and do not execute the provider effect twice.
> 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 based on GPT-5 with agentic reasoning, repository
inspection, code editing, Git, parallel subagents, and GitHub Actions
coordination. The exact deployed snapshot and context-window size are
not exposed to this task.
## 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 linked related public work or described the bug in
this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
ticket id
- [ ] I have run tests locally and they pass (intentionally deferred to
GitHub Actions)
- [x] I have added or updated tests where applicable
- [x] No documentation change is required for this runtime repair
- [x] I have considered and documented the 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agent permissions control which agents can create or hire other
agents (`canCreateAgents`)
> - Today only CEO-role agents get this permission by default; every
other agent starts without it
> - Teams that want agents to delegate and build out their own teams
must flip the toggle on each hire, and most operators want delegation to
work out of the box
> - This pull request makes `canCreateAgents` default to enabled for new
standard-trust agents, while low-trust agents keep a disabled default
> - The benefit is that agent teams can grow without per-agent
permission toggling, while low-trust containment and checkout protection
stay intact
## Linked Issues or Issue Description
Related (not fixed by this PR): #8064 also decouples an authority from
`agents:create`.
**Subsystem affected**
Server agent permissions (`server/src/services/agent-permissions.ts`),
authorization (`server/src/services/authorization.ts`), the shared
`agentPermissionsSchema` validator, and the UI trust-preset helper.
**Problem or motivation**
New agents cannot hire other agents unless an operator enables
`canCreateAgents` on each one. Only CEO-role agents get the permission
by default. This blocks delegation-by-default workflows. Operators must
toggle the permission for every hire.
**Proposed solution**
Default `canCreateAgents` to `true` for newly created agents. Apply and
persist the default at creation only. Stored rows without an explicit
value stay fail-closed at read and enforcement time. Keep the default at
`false` when the agent's permissions record marks it low-trust (the
`low_trust_review` preset or a trust boundary). Explicit values always
win. Decouple `tasks:manage_active_checkouts` from `canCreateAgents` so
the default-on flag does not let a peer agent write over another agent's
checked-out issue.
**Alternatives considered**
Granting the default only at the route layer would leave stored rows and
enforcement out of sync. Keeping the checkout authority coupled to
`canCreateAgents` would void the active-checkout write protection once
the flag is default-on. A per-company setting adds configuration surface
without a clear need; explicit per-agent overrides already exist.
**Roadmap alignment**
Governance and trust-preset work already separates standard-trust from
low-trust agents. This change follows that line: capability by default
for standard trust, containment by default for low trust.
## What Changed
- `normalizeAgentPermissions` now takes a `create`/`stored` context.
Creation writes get the new default: enabled unless
`permissionsImplyLowTrust()` detects the low-trust review preset or a
trust boundary. Stored rows without an explicit value normalize to
disabled (fail-closed). The role parameter is gone.
- `agentPermissionsSchema` no longer injects `canCreateAgents: false`
when the field is omitted. The server-side default applies instead.
- `authorization.ts` normalizes raw agent rows for `agents:create`, so
enforcement matches what the API reports for legacy rows.
- `tasks:manage_active_checkouts` no longer rides on `canCreateAgents`.
CEO role, explicit grants, and the manager chain remain the paths.
- `agents:create` is denied outright inside any resolved low-trust
execution context (agent, project, issue, or run policy). The default-on
flag can never reach the legacy creator allow there.
- The UI trust-preset helper sets `canCreateAgents: false` when an agent
is switched to the low-trust preset, instead of carrying the old value
forward.
- `doc/CLI.md` describes the new default for `teams install`.
- Tests pin the default matrix (standard, low-trust, explicit overrides)
on the server and in the UI helper.
## Verification
- `cd server && npx vitest run
src/__tests__/agent-permissions-service.test.ts
src/__tests__/agent-permissions-routes.test.ts
src/__tests__/low-trust-red-team-routes.test.ts
src/__tests__/authorization-service.test.ts` — 143 tests pass.
- Broader sweep: 18 suites that touch `canCreateAgents` (hire,
pending-approval, teams catalog, portability, built-in agents,
plugin-managed agents) pass locally.
- `cd ui && npx vitest run src/lib/trust-policy-ui.test.ts
src/components/TrustPresetSection.test.tsx src/pages/NewAgent.test.tsx
src/pages/Agents.test.tsx` — passes.
- Typecheck is clean for the changed files in `packages/shared`,
`server`, and `ui`.
## Risks
- Behavioral shift: agents created after this change persist
`canCreateAgents: true` unless low-trust. Pre-existing agents keep their
stored value. Legacy or malformed permission records without an explicit
value stay fail-closed at read and enforcement time; they never gain the
authority retroactively.
- Low-trust runs can no longer create agents at all, even when the agent
carries an explicit `canCreateAgents: true`. Before this change, that
combination could hire. The red-team suite and a new authorization test
pin the denial.
- Narrowing: a non-CEO agent with `canCreateAgents: true` loses implicit
`tasks:manage_active_checkouts`. The manager chain and explicit grants
still provide it. This narrowing is deliberate; without it, the
default-on flag would let any peer bypass active-checkout write
protection.
- No migrations. No API shape changes. Low-trust defaults are covered by
the red-team regression suite.
## Model Used
- Claude Fable 5 (`claude-fable-5`), Anthropic — via Claude Code CLI
with extended thinking and tool use (code search, editing, local test
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 (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
## Thinking Path
> - Paperclip is the control plane for companies that use AI agents.
> - Apps give humans and agents controlled access to external services.
> - The existing app detail flow split permissions, tests, setup, and
activity across separate pages.
> - The split made access rules harder to understand and made reconnect
work hard to find.
> - New write actions also defaulted to Ask first, which did not match
the intended connection policy.
> - This pull request combines permission control and action testing,
removes the setup page, and moves connection activity into Audit.
> - The benefit is one clear place to configure, test, reconnect, and
review each app.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
The installed app Permissions, Test, Setup, and Activity views.
**Subsystem affected**
Cross-cutting. This change updates the React UI, shared app defaults,
server permission behavior, tests, smoke scripts, and connection
documentation.
**Current behavior**
App access and action testing use separate pages. The app detail view
also links to a setup page after installation. Connection activity uses
a separate tab. New write actions default to Ask first.
**Proposed behavior**
Permissions uses the connection access language from the initial flow.
It includes searchable Read and Write sections, a three-state permission
control, and a Test dialog for each action. Reconnect appears below a
Needs attention header on Permissions and Review. Old Setup and Test
links redirect to Permissions. Old Activity links redirect to the
filtered company Audit feed. New write actions default to Allowed.
**Reason and benefit**
A person can understand and test app access without moving between
several pages. Reconnect work stays visible where the person reviews the
connection. Audit events use one consistent feed and filter model. New
connections have the intended default policy.
**Breaking changes**
The Setup, Test, and app Activity tabs are removed. Existing deep links
redirect to their replacement pages. Existing saved action permissions
do not change. Only defaults for new write actions change.
**Additional context**
This builds on the managed app connection work in #12728. A search found
no duplicate open pull request or issue.
## What Changed
- Combined action testing with Permissions.
- Added searchable Read and Write action groups.
- Added Off, Ask first, and Allowed controls with tooltips.
- Added an action Test dialog with agent selection, arguments, and
formatted results.
- Removed the installed-app Setup and Activity tabs.
- Added reconnect guidance to Permissions and Review when a connection
needs attention.
- Routed connection activity into the company Audit feed and preserved
the Apps & tools filter in streamlined Audit.
- Moved connection removal to the Connectors-page management menu.
- Made new write actions default to Allowed across connection creation
paths.
- Updated regression tests, browser suites, smoke scripts, and
connection documentation.
## Verification
- `pnpm check:token-gates`
- `pnpm exec vitest run packages/shared/src/app-definitions.test.ts
server/src/__tests__/generic-mcp-connection.test.ts
server/src/__tests__/tool-access-service.test.ts
ui/src/components/AppConnectionSidebar.test.tsx
ui/src/pages/apps/AppDetail.test.tsx
ui/src/pages/apps/AppNotConnected.test.tsx
ui/src/pages/apps/AppsConnect.test.tsx ui/src/pages/apps/Browse.test.tsx
ui/src/pages/apps/Connections.test.tsx
ui/src/pages/apps/composio-services.test.ts
ui/src/pages/audit/AuditFeed.test.tsx
ui/src/pages/tools/PasteConfigTab.test.tsx` (517 tests passed)
- `pnpm exec vitest run ui/src/pages/apps/app-detail/TestPanel.test.tsx
ui/src/pages/audit/AuditHub.test.tsx
ui/src/pages/audit/AuditFeed.test.tsx
ui/src/pages/apps/AppDetail.test.tsx ui/src/pages/apps/Browse.test.tsx`
(96 tests passed)
- Targeted Playwright verification for connection removal, rename on
Permissions, inline action testing, and Smoke Lab Audit evidence (5
flows passed)
- `pnpm -r typecheck`
- `pnpm build`
- `pnpm test:run` completed with 5,755 passing tests and 20 unrelated
macOS harness failures. The failures use `/tmp` versus `/private/tmp`,
invalid ports above 65535, and workspace fixtures outside this change.
## Risks
- Low migration risk. This change has no database migration.
- Old app-detail URLs depend on redirect compatibility.
- New connections grant write actions by default. Finalization remains
configure-authorized and audited, Ask first and Off remain available per
action, and existing connections keep their saved policy.
> 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, exact model ID `gpt-5`. The client does not expose the
context-window size. The model used reasoning, repository tools, code
execution, and browser verification.
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Apps let people give agents governed access to external providers
> - Paperclip Cloud brokers shared provider authorization for managed
stacks
> - The managed flow sent the browser through a confirmation page after
the tenant had already prepared sign-in
> - A lost confirmation response could also show an expired-session
error before the provider page opened
> - This pull request adds an opaque handoff contract and one shared
tenant coordinator
> - The benefit is a direct and recoverable transition from Paperclip to
every Cloud-brokered provider
## Linked Issues or Issue Description
**What happened?**
A managed Paperclip Cloud connection opened the Cloud confirmation
route. A response-loss race could show an expired-session error while
the authorization still continued.
**Expected behavior**
The current Paperclip loading state must stay visible while the tenant
exchanges an opaque session. The browser must then open the provider
directly. Self-hosted and direct OAuth must keep their existing
behavior.
**Steps to reproduce**
1. Open Apps on a Paperclip Cloud stack.
2. Start a managed provider connection.
3. Select Continue to sign in.
4. Observe that the browser visits the Cloud confirmation route before
it reaches the provider.
**Paperclip version or commit**
`b872cd3d1b404bdaff70af493a2973ceb7e5d6ec`
**Deployment mode**
Paperclip Cloud hosted stack.
No related open issue or pull request was found in the repository
search.
## What Changed
- Add a backward-compatible opaque Cloud handoff to the shared OAuth
start contract.
- Validate the Cloud descriptor on the server and expose no
browser-selected endpoint.
- Exchange managed handoffs through one fixed same-origin route in every
Apps OAuth launcher.
- Keep dialog popups reserved before asynchronous work and retain the
tenant loading state.
- Add recent-login resume storage, bounded retry behavior, terminal
tenant errors, tests, and Storybook states.
## Verification
- `pnpm check:token-gates`
- `pnpm -r typecheck`
- Focused connector and UI suites: 184 passed and 202 skipped.
- `pnpm build`
- `pnpm build-storybook`
- The full local suite reached one unrelated macOS path-alias failure.
The untouched test expected `/var/...` and received the equivalent
`/private/var/...`. The same test reproduces in isolation.
## Risks
- A malformed managed descriptor now fails closed in Paperclip instead
of opening a URL.
- A legacy Cloud deployment can omit the descriptor. Paperclip then uses
the existing validated confirmation URL.
- Direct provider OAuth and self-hosted flows do not receive a handoff
and remain unchanged.
- Rollback is a normal revert of this commit because the contract is
optional and backward compatible.
> 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 with GPT-5.6, reasoning mode, tool use, code execution,
and browser verification.
## 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
- [ ] 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>
## Thinking Path
> - Paperclip manages AI agents and their provider runtimes.
> - The paid runner workflow installs target dependencies with lifecycle
scripts disabled.
> - The bundled Daytona plugin depends on an audited repo-local plugin
SDK link.
> - The lifecycle-safe install path did not create that link.
> - This pull request restores only the trusted Daytona preparation step
before provider secrets are exposed.
> - The benefit is a working Daytona canary without enabling dependency
lifecycle scripts.
## Linked Issues or Issue Description
**What happened?**
The Daytona paid canary stopped before lease or provider startup. The
trusted paid job disabled root lifecycle scripts, so the repo-local
plugin SDK link was absent. The plugin install returned a missing
runtime dependency error for @paperclipai/plugin-sdk.
**Expected behavior**
The trusted workflow must prepare the bundled Daytona plugin without
running untrusted dependency lifecycle scripts. The paid cell must start
only after its runtime dependencies and entrypoints pass validation.
**Steps to reproduce**
1. Dispatch the runner full-stack paid workflow for
core-compatibility.runner-acpx-claude.daytona.message-marker.
2. Let the trusted job install root dependencies with lifecycle scripts
disabled.
3. Observe the Daytona plugin installation fail before a lease or
provider process starts.
**Paperclip version or commit**
Feature head 781ac7e08c. The failed canary
is Actions run 33803959325.
**Deployment mode**
GitHub Actions paid runner validation.
**Agent adapter(s) involved**
ACPX Claude through the bundled Daytona plugin.
**Additional context**
This is a small trusted-workflow prerequisite for public PR #12769. Old
green run 33118525827 created the SDK link through root postinstall.
This change keeps lifecycle scripts disabled and restores only the
audited prerequisite.
## What Changed
- Install standalone Daytona dependencies with lifecycle scripts
disabled.
- Run the audited repo-local plugin SDK linker before provider secrets
are exposed.
- Build the bundled Daytona plugin and verify its runtime dependency
plus both entrypoints.
- Add a security regression for ordering, scope, and secret isolation.
## Verification
- Five focused workflow-security tests passed.
- Seven focused linker tests passed.
- The exact Daytona preparation command completed locally in nine
seconds.
- Prettier and diff whitespace checks passed.
## Risks
Risk is low and limited to Daytona paid cells. The setup still disables
dependency lifecycle scripts. The trusted step runs before provider
credentials enter the job. Any missing or mismatched path fails closed
before provider startup.
## Model Used
OpenAI GPT-5 Codex with repository tools 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 described the issue in this PR with the bug template labels
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change
- [x] Focused local tests pass
- [x] I added tests for the change
- [x] I updated the relevant trusted-workflow security regression
- [x] I documented the risks above
Bumps @pierre/diffs from 1.3.5 to 1.3.6.
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~ije">ije</a>, a new releaser for
<code>@pierre/diffs</code> since your current version.</p>
</details>
<br />
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The ACPX runtime host tests manage credentials and sandbox
operations.
> - These tests poll operations that can join quarantine recovery.
> - Recovery uses real backoff and directory synchronization, so the
default poll deadline can expire while the operation makes progress.
> - Three tests also stage a contender before the kernel lease release
completes.
> - This pull request binds every relevant poll and staging call to the
documented retry envelope.
> - The benefit is more stable tests and error output that names the
last observed cause.
## Linked Issues or Issue Description
**What happened?**
Under concurrent test load, ACPX runtime host tests failed while
credential recovery still made progress. Three tests also saw an active
lease after they removed `auth.json`.
**Expected behavior**
The tests must wait for the documented retry envelope before they report
a failure. They must stage a contender only after the credential lease
becomes available.
**Steps to reproduce**
1. Run `npx vitest run src/drivers/acpx/` from
`packages/paperclip-runner`.
2. Run the suite under high concurrent load.
3. Observe intermittent timeout or active-lease failures in
`runtime-host.test.ts`.
**Paperclip version or commit**
`865b4854fb44d3689f1c0ff17e3e715d52aaea73` base commit.
**Deployment mode**
Built from source.
**Installation method**
Built from source.
**Agent adapter(s) involved**
ACPX Codex runtime host tests.
**Database mode**
Not database-related.
**Access context**
Unclear / not applicable.
**Node.js version**
Not recorded in the handoff.
**Operating system**
Not recorded in the handoff.
**Relevant logs or output**
Under concurrent load, the failure included `Timed out in waitFor!`
after 1157 ms and `Managed Codex credential home already has an active
lease`.
**Relevant config (if applicable)**
Not applicable.
**Additional context**
The change touches test code only. It adds no test, removes no test, and
weakens no assertion. The file keeps 28 tests and 146 assertions.
## What Changed
- Add a test-local wait helper with an explicit 10-second deadline.
- Apply the helper to every credential and sandbox poll in
`runtime-host.test.ts`.
- Report the last observed error when a poll reaches its deadline.
- Guard the three credential staging calls that could race with lease
release.
- Set a 20-second timeout on tests that use the long wait.
## Verification
- `npx vitest run src/drivers/acpx/runtime-host.test.ts` passes all 28
tests on the change branch.
- A 40-run concurrent comparison produced zero `runtime-host.test.ts`
failures on the change branch.
- The base comparison produced 13 `runtime-host.test.ts` failures across
40 runs.
- The broader ACPX suite still has a separate
`codex-credentials.test.ts` flake on both arms.
- CI and Greptile results will provide the remaining merge checks.
## Risks
Low risk. The change affects test synchronization only. It increases
selected test wait limits and does not change product behavior.
## Model Used
OpenAI Codex, GPT-5. The model used tool calls and code execution. The
runtime did not provide a context window value.
## 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 recorded the separate ACPX suite
flake above
- [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>
## Thinking Path
> - Paperclip manages AI agents and their provider runtimes.
> - Paid runner validation installs target dependencies with lifecycle
scripts disabled.
> - OpenCode leaves a sentinel executable until its package lifecycle
script runs.
> - Running arbitrary lifecycle code would weaken the paid-secret
boundary.
> - This pull request materializes one exact pinned binary before
secrets are exposed.
> - The benefit is working OpenCode validation without trusting
dependency install scripts.
## Linked Issues or Issue Description
**What happened?**
Every local OpenCode paid cell stopped before provider startup because
`pnpm install --ignore-scripts` correctly retained
`opencode-ai/bin/opencode.exe` as a sentinel.
**Expected behavior**
The trusted workflow must make the exact lockfile-pinned OpenCode
executable available without running package lifecycle scripts.
**Steps to reproduce**
Run a local legacy or native OpenCode paid cell from the trusted
workflow after the target dependency install. The provider health check
reports that the OpenCode postinstall script was not run.
**Paperclip version or commit**
Default branch commit `865b4854fb44d3689f1c0ff17e3e715d52aaea73`.
## What Changed
- Materialize only `opencode-linux-x64-baseline@1.18.17` into the
matching `opencode-ai@1.18.17` package.
- Verify package identity, version, regular-file type, SHA-256 equality,
executable permissions, and runtime `--version`.
- Invoke the helper for local OpenCode and breadth cells and for remote
provider-pack assembly.
- Retain `pnpm install --ignore-scripts`.
- Add helper and trusted-workflow security regressions.
## Verification
- Helper syntax checks passed.
- Helper unit tests passed: 2/2.
- Workflow-security tests passed: 5/5.
- Prettier, actionlint, and diff whitespace checks passed.
## Risks
Risk is low and contained to paid runner setup. The helper supports only
Linux x64, fails closed on package or version drift, and runs before
provider credentials enter the job.
## Model Used
OpenAI GPT-5 Codex with repository tools 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.
- [x] I have checked ROADMAP.md and confirmed this does not duplicate
planned core work.
- [x] I have searched GitHub for duplicate or related PRs and found
none.
- [x] I have described the issue in this PR with the bug template
labels.
- [x] I have not referenced internal or instance-local issues.
- [x] My branch name describes the change.
- [x] Focused local tests pass.
- [x] I added tests for the change.
- [x] I updated the runner E2E security documentation.
- [x] I documented the risks above.
Bumps
[@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react)
from 4.7.0 to 6.1.1.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/vitejs/vite-plugin-react/releases">@vitejs/plugin-react's
releases</a>.</em></p>
<blockquote>
<h2>plugin-react@6.1.1</h2>
<h3>Add <code>compiler.logDiagnostics</code> option</h3>
<p>Recoverable React Compiler diagnostics are no longer logged by
default. Set <code>compiler.logDiagnostics</code> to <code>true</code>
to log them through Vite. Fatal diagnostics are always logged and fail
the transform.</p>
<h3>Respect environment sourcemap option for React Compiler transform
when <code>builder.sharedPlugins</code> is enabled (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/pull/1439">#1439</a>)</h3>
<p>The React Compiler transform was using the top-level sourcemap option
instead of the environment sourcemap option. This caused a problem when
the experimental <code>builder.sharedPlugins</code> was enabled.</p>
<h2>plugin-react@6.1.0</h2>
<h3>Add experimental native React Compiler support (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/pull/1419">#1419</a>)</h3>
<p>Add experimental native React Compiler support.</p>
<p>You can use it by installing <code>oxc-transform-react</code> and
enabling it via the <code>compiler</code> option:</p>
<pre lang="sh"><code>npm install -D oxc-transform-react
</code></pre>
<pre lang="js"><code>import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
<p>export default defineConfig({<br />
plugins: [<br />
react({ compiler: true })<br />
]<br />
})<br />
</code></pre></p>
<h2>plugin-react@6.0.5</h2>
<h3>Fixed the react compiler preset filter to be linear (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/pull/1353">#1353</a>)</h3>
<p>The improved filter in v6.0.3 was non-linear and caused a performance
regression (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/issues/1349">#1349</a>).
The filter was changed to be linear to avoid that.</p>
<h2>plugin-react@6.0.4</h2>
<h3>Fixed <code>$RefreshSig$ is not defined</code> error when running
<code>vite dev</code> with <code>NODE_ENV=production</code></h3>
<p>When running <code>vite dev</code> with
<code>NODE_ENV=production</code>, the app errored with
<code>$RefreshSig$ is not defined</code>.
This error is now fixed.</p>
<h2>plugin-react@6.0.3</h2>
<p>No release notes provided.</p>
<h2>plugin-react@6.0.2</h2>
<h3>Allow all options in reactCompilerPreset (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/pull/1189">#1189</a>)</h3>
<p>This is a type only change. Only <code>compilationMode</code> and
<code>target</code> options were available for
<code>reactCompilerPreset</code>.</p>
<h2>plugin-react@6.0.1</h2>
<h3>Expand <code>@rolldown/plugin-babel</code> peer dep range (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/pull/1146">#1146</a>)</h3>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/CHANGELOG.md">@vitejs/plugin-react's
changelog</a>.</em></p>
<blockquote>
<h2>6.1.1 (2026-08-28)</h2>
<h3>Add <code>compiler.logDiagnostics</code> option</h3>
<p>Recoverable React Compiler diagnostics are no longer logged by
default. Set <code>compiler.logDiagnostics</code> to <code>true</code>
to log them through Vite. Fatal diagnostics are always logged and fail
the transform.</p>
<h3>Respect environment sourcemap option for React Compiler transform
when <code>builder.sharedPlugins</code> is enabled (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/pull/1439">#1439</a>)</h3>
<p>The React Compiler transform was using the top-level sourcemap option
instead of the environment sourcemap option. This caused a problem when
the experimental <code>builder.sharedPlugins</code> was enabled.</p>
<h2>6.1.0 (2026-08-19)</h2>
<h3>Add experimental native React Compiler support (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/pull/1419">#1419</a>)</h3>
<p>Add experimental native React Compiler support.</p>
<p>You can use it by installing <code>oxc-transform-react</code> and
enabling it via the <code>compiler</code> option:</p>
<pre lang="sh"><code>npm install -D oxc-transform-react
</code></pre>
<pre lang="js"><code>import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
<p>export default defineConfig({<br />
plugins: [<br />
react({ compiler: true })<br />
]<br />
})<br />
</code></pre></p>
<h2>6.0.5 (2026-07-30)</h2>
<h3>Fixed the react compiler preset filter to be linear (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/pull/1353">#1353</a>)</h3>
<p>The improved filter in v6.0.3 was non-linear and caused a performance
regression (<a
href="https://redirect.github.com/vitejs/vite-plugin-react/issues/1349">#1349</a>).
The filter was changed to be linear to avoid that.</p>
<h2>6.0.4 (2026-07-22)</h2>
<h3>Fixed <code>$RefreshSig$ is not defined</code> error when running
<code>vite dev</code> with <code>NODE_ENV=production</code></h3>
<p>When running <code>vite dev</code> with
<code>NODE_ENV=production</code>, the app errored with
<code>$RefreshSig$ is not defined</code>.
This error is now fixed.</p>
<h2>6.0.3 (2026-06-23)</h2>
<h3>Improve the react compiler preset filter to reduce false-positives
(<a
href="https://redirect.github.com/vitejs/vite-plugin-react/pull/1138">#1138</a>)</h3>
<p>Improved the filter in the react compiler babel preset to reduce the
false-positives so that less modules are processed by the react
compiler.</p>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="04cac5020e"><code>04cac50</code></a>
release: plugin-react@6.1.1 (<a
href="https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react/issues/1440">#1440</a>)</li>
<li><a
href="82d35abe49"><code>82d35ab</code></a>
fix(react): respect environment sourcemap option when
<code>builder.sharedPlugins</code>...</li>
<li><a
href="397e8471a5"><code>397e847</code></a>
fix(react): make logging diagnostics an opt-in for React Compiler (<a
href="https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react/issues/1431">#1431</a>)</li>
<li><a
href="61006e6f52"><code>61006e6</code></a>
fix(deps): update all non-major dependencies (<a
href="https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react/issues/1433">#1433</a>)</li>
<li><a
href="e2a649cbaa"><code>e2a649c</code></a>
chore: use <code>deps.neverBundle</code> instead of
<code>external</code> in tsdown config (<a
href="https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react/issues/1430">#1430</a>)</li>
<li><a
href="fb2d6f3635"><code>fb2d6f3</code></a>
fix(deps): update all non-major dependencies (<a
href="https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react/issues/1427">#1427</a>)</li>
<li><a
href="39b31735bf"><code>39b3173</code></a>
release: plugin-react@6.1.0 (<a
href="https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react/issues/1428">#1428</a>)</li>
<li><a
href="f1340b0c76"><code>f1340b0</code></a>
feat(react): add native React Compiler support (<a
href="https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react/issues/1419">#1419</a>)</li>
<li><a
href="9ab698eafc"><code>9ab698e</code></a>
fix(deps): update all non-major dependencies (<a
href="https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react/issues/1375">#1375</a>)</li>
<li><a
href="68c0cb8796"><code>68c0cb8</code></a>
release: plugin-react@6.0.5 (<a
href="https://github.com/vitejs/vite-plugin-react/tree/HEAD/packages/plugin-react/issues/1362">#1362</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/vitejs/vite-plugin-react/commits/plugin-react@6.1.1/packages/plugin-react">compare
view</a></li>
</ul>
</details>
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for <code>@vitejs/plugin-react</code> since your current
version.</p>
</details>
<br />
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip uses local adapters to connect agent sessions to the
control plane
> - The Codex adapter emits turn events from response and notification
channels
> - A terminal notification can arrive before the turn/start response
> - This pull request gates the terminal event on turn.accepted
> - The result keeps the event order stable for consumers and tests
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip uses local adapters to connect agent sessions to the
control plane
> - The Codex adapter emits turn events from response and notification
channels
> - A terminal notification can arrive before the turn/start response
> - This pull request gates the terminal event on turn.accepted
> - The result keeps the event order stable for consumers and tests
## Linked Issues or Issue Description
**What happened?**
The Codex harness session emitted `turn.accepted` only after the
`turn/start` response resolved. A terminal notification could arrive
before that response and reach consumers first.
**Expected behavior**
The Codex driver must emit `turn.accepted` before any terminal event for
the same turn.
**Steps to reproduce**
1. Start a Codex harness session.
2. Keep the `turn/start` response pending.
3. Send `turn/started` and `turn/completed` notifications.
4. Observe the event order.
**Paperclip version or commit**
`afbcd28dae9e51108738c4258929b95ca359186c`
**Deployment mode**
Built from source with the Codex driver test harness.
**Agent adapter(s) involved**
Codex.
## What Changed
- Add session state that tracks a pending `turn/start` operation.
- Resolve the state when `turn/start` succeeds or fails.
- Wait for that state before the terminal notification handler emits its
event.
- Add a regression test that delivers a terminal notification while
`turn/start` remains pending.
## Verification
- The regression test failed 5 of 5 times before this change and passed
5 of 5 times after it.
- The Codex driver suite passed 189 of 189 tests.
- The affected live transport test file passed 46 of 46 tests on 10
consecutive runs.
- The TypeScript check exited with status 0.
- Continuous integration must pass before merge.
## Risks
The change affects only Codex turn event ordering. It adds no sleep,
retry, or timeout. The main risk is a provider path that does not settle
`turn/start`; existing provider response handling still controls
completion.
## Model Used
OpenAI GPT-5. The exact deployment identifier is not exposed in this
environment. Tool use and code execution assisted this change.
## 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>
## Thinking Path
> - Paperclip manages AI agents and their work.
> - The runner starts ACPX sessions and controls their resources.
> - An aborted admission can leave sandbox preparation active after the
opening promise rejects.
> - Test teardown can then remove the sandbox directory before that work
ends.
> - This pull request retains and observes each unfinished admission
stage.
> - The change gives runtime resources and temporary directories one
deterministic cleanup owner.
## Linked Issues or Issue Description
**What happened?**
Under full test load, an aborted admission test can end before sandbox
preparation settles. Test teardown then removes the temporary session
directory. The active preparation can report an unhandled `ENOENT`
error.
**Expected behavior**
An aborted admission must observe and retain all active preparation
work. Test teardown must wait until that work settles.
**Steps to reproduce**
1. Run the complete `@paperclipai/paperclip-runner` test suite under CI
load.
2. Abort runtime admission during credential or sandbox preparation.
3. Observe an intermittent test timeout or an unhandled
missing-directory error.
**Paperclip version or commit**
The failure occurred on a branch based on commit `b1f4910ee`. This fix
is based on current `master` commit `4d30efa8e`.
**Deployment mode**
The failure occurred in GitHub Actions on a source build.
## What Changed
- Retain each unfinished abortable admission stage in the global
runtime-host cleanup set.
- Notify the embedding lifecycle when an aborted stage needs deferred
cleanup.
- Make test teardown abort and await all active opening and cleanup
promises before directory removal.
- Replace time-based stage detection with exact deferred stage signals.
- Add a deterministic regression test for an abort during sandbox
preparation.
## Verification
- Ran the focused runtime-host file in 20 separate processes. All 20
runs passed without an unhandled error.
- Ran `pnpm --filter @paperclipai/paperclip-runner exec vitest run
src/drivers/acpx/runtime-host.test.ts` after the rebase. All 27 tests
passed.
- Ran `pnpm --filter @paperclipai/paperclip-runner check:all` after the
rebase. The full command passed.
- The final TypeScript test stage passed 127 files and 1,490 tests. All
Rust checks, tests, and parity checks passed.
- Greptile reviewed two heads. The final review is 5/5 with no open
comments.
- All latest-head CI and security checks passed. One unrelated workspace
test passed on its permitted rerun.
## Risks
- Risk is low. An aborted stage now delays final runtime-host cleanup
until its active operation settles.
- A stage that never settles can delay embedding shutdown. The existing
stage operations have bounded or controlled owners.
- The regression test holds sandbox preparation and confirms the new
cleanup order.
> 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 with GPT-5 assisted this change. The environment did not
provide the exact deployment ID or context size. The model used
reasoning, shell tools, code editing, and test 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 (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>
## Thinking Path
> - Paperclip is the control plane for companies that use AI agents for
work
> - Local adapters connect Paperclip agents to provider command line
tools
> - The Codex adapter stores login data in a shared company home
> - A shared home cannot keep credentials for more than one Codex
account
> - This pull request gives each account a safe home and a matching
company secret
> - The benefit is that one company can use multiple Codex accounts at
the same time
## Linked Issues or Issue Description
**Problem or motivation**
A company can hold only one Codex subscription credential because device
login uses one shared home. A second account cannot log in without
replacing or conflicting with the first credential.
**Proposed solution**
This change validates the vendor account identifier, stores each
credential in its own home, and creates a company secret that points to
that home. Repeat login calls return success when the matching secret
already exists.
**Roadmap alignment**
The change supports the roadmap goal for centrally managed secrets with
scoped access and audited resolution.
**Additional context**
The security review returned approve with no blocking finding. The
branch adds shared account-handle validation and tests for device login
and the Codex local adapter.
## What Changed
- Add strict allowlist validation for Codex account handles.
- Store each Codex account credential in a separate home under the Codex
cache root.
- Verify that the resolved account home stays inside the cache root.
- Create the `CODEX_HOME_<handle>` company secret for each account.
- Keep repeat and concurrent login calls safe and idempotent.
- Add shared helper and route, adapter, and validation tests.
## Verification
- `pnpm --filter @paperclipai/adapter-codex-local test` passes with 343
tests.
- `pnpm --filter @paperclipai/server test
src/__tests__/agent-device-login-routes.test.ts` passes with 25 tests.
- The adapter suite passes with 23 tests.
- The shared package and Codex adapter typechecks pass.
- Continuous integration must pass on every check before merge.
## Risks
The account handle becomes part of a directory path and secret name. The
strict allowlist and root containment check reduce path traversal risk.
Existing single-account homes remain unchanged unless a new device login
creates an account-specific home.
## Model Used
OpenAI GPT-5 (exact runtime model ID: gpt-5), with tool use and code
execution. The runtime context window is not exposed in this run.
## 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
- [ ] 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The Claude local adapter lets operators select a Claude model for an
agent.
> - Claude Fable 5.1 was absent from the adapter model lists.
> - The adapter runtime also used a Claude Code build that rejected
Fable 5.1.
> - This pull request adds the direct Anthropic ID and the AWS Bedrock
inference profile ID.
> - It also updates the Claude ACP runtime and keeps the Paperclip usage
and isolation patches.
> - The benefit is that operators can select and run Claude Fable 5.1
through the Claude adapter.
## Linked Issues or Issue Description
Refs #8810. That issue covers related model ID handling. This change
does not change provider-prefixed model IDs.
**Agent or provider**
Claude Code through the built-in `claude_local` adapter. The requested
model is Claude Fable 5.1.
**Why this adapter is useful**
Operators can use Fable 5.1 without entering an undocumented model ID.
The configured model also reaches both supported Claude execution lanes.
**How the agent is invoked**
The CLI lane sends `--model claude-fable-5-1`. The ACP lane sends
`ANTHROPIC_MODEL=claude-fable-5-1` to
`@agentclientprotocol/claude-agent-acp`.
**Are you willing to implement it?**
Yes. This pull request includes the implementation and tests.
**Additional context**
Claude Code 2.1.232 rejected Fable 5.1 and required version 2.1.251 or
newer. ACP package 0.73.0 includes Claude Code 2.1.257. The update keeps
Paperclip's usage metadata and isolated-context behavior.
## What Changed
- Added `claude-fable-5-1` to the direct Claude fallback list.
- Added `us.anthropic.claude-fable-5-1` to the AWS Bedrock list.
- Kept the existing default model at the first position in each list.
- Updated the Claude ACP dependency from 0.70 to 0.73.
- Carried the Paperclip usage and isolated-context changes into the 0.73
patch.
- Added a Claude Code 2.1.251 minimum-version preflight for Fable 5.1
when using the standard `claude` executable, surfaced in both adapter
Test and execution. Explicit custom wrappers retain their existing
compatibility contract.
- Kept local adapter Tests from executing caller-selected binaries: when
runtime `PATH` selects a different Claude executable than the trusted
probe, the Test warns and defers the authoritative version check to
execution instead of approving or rejecting the alternate installation.
- Added tests for model listing, discovery deduplication, Bedrock
filtering, model pass-through in both execution lanes, old-CLI rejection
before launch, custom-wrapper compatibility, and local runtime-PATH
mismatch handling.
## Verification
- `pnpm --filter @paperclipai/adapter-claude-local typecheck`
- `pnpm exec vitest run
packages/adapters/claude-local/src/server/execute.remote.test.ts
packages/adapters/claude-local/src/server/test.remote.test.ts
packages/adapters/claude-local/src/server/test.probe.test.ts
packages/adapters/claude-local/src/server/acp.test.ts
server/src/__tests__/adapter-models.test.ts` (72 tests passed)
- `node --test scripts/acpx-patch-packaging.test.mjs` (13 tests passed)
- `pnpm -r typecheck`
- `pnpm build`
- A local Paperclip agent run completed with `usageJson.model` set to
`claude-fable-5-1` through ACP 0.73.0 and its bundled Claude Code
2.1.257.
- `pnpm test:run` completed 5,638 passing tests and 24 skipped tests. It
also found 24 failures in unrelated workspace-runtime,
path-canonicalization, and runtime-exposure tests on macOS with Node 26.
These failures do not touch this diff. Clean pull request CI is the
final full-suite gate.
## Risks
- The ACP dependency update can change Claude runtime behavior outside
model selection. Focused ACP tests, the full typecheck, the production
build, and a real local Fable run reduce this risk.
- The 0.73 patch must stay aligned with the installed ACP version.
Dependency-resolution CI verifies the manifest and patch pair.
- Fable 5.1 adds a short `claude --version` preflight to standard
CLI-lane Tests and runs. The result is intentionally not cached so an
in-place Claude Code upgrade takes effect without restarting Paperclip.
Explicit custom wrappers are not version-probed because their output and
compatibility contract can differ from the standard executable.
- Local Tests preserve the existing deny-by-default probe boundary and
do not execute a binary selected by caller-controlled `PATH`. A
mismatched runtime binary produces an explicit warning without blocking
an otherwise valid setup; execution independently validates the actual
runtime-selected CLI before launch.
- The AWS Bedrock identifier differs from earlier IDs because Fable 5.1
has no `-v1` suffix. The model-list test locks this exact value.
- There is no schema change or migration.
> 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
Provider: OpenAI. Model: GPT-5 Codex. The host did not expose a more
specific model ID or context-window size. Capabilities used: agentic
reasoning, repository editing, shell execution, web research, and local
runtime verification.
## 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>
## Thinking Path
> - Paperclip is the control plane for agents that perform work.
> - Paperclip Runner connects durable provider sessions to individual
task runs through PRP.
> - Provider continuity and per-run authority are different lifetimes.
> - The existing implementation mixed those lifetimes and lost event
metadata between provider frames, runnerd, persistence, API
sanitization, and the task thread.
> - That caused failed continuation, missing progress and Plans,
duplicate replies, hidden failures, and unsafe recovery.
> - This repair gives every heartbeat fresh authority, preserves
qualified provider-session continuity, and restores one lossless
presentation path without changing direct adapters.
## Linked Issues or Issue Description
**What happened?**
A second native heartbeat could reuse tickets, leases, command receipts,
sequence state, and run identity from the first heartbeat. Provider
phase and item identity could be lost before the UI read them. Redaction
could corrupt protocol discriminators while still missing malformed
credential tails. The task thread could fold progress into the final
response, hide failures, or show more than one final answer. Native
Codex also exposed approval modes that do not yet have a durable
approval bridge.
**Expected behavior**
Each heartbeat uses a new PRP authority epoch. Codex and OpenCode
preserve exact qualified provider sessions; ACPX emits an explicit
continuity event when its qualified process-replacement policy is used.
Every accepted provider event is presented, classified as internal, or
surfaced as unsupported. The task page shows chronological progress,
reasoning summaries, activity, Plans, interactions, terminal failures,
and exactly one final reply. Direct adapters retain their existing path.
**Steps to reproduce**
1. Enable the unified experimental Paperclip Runner setting.
2. Create a local native Codex, OpenCode, ACPX Claude, or ACPX Codex
agent.
3. Run response, Plan, structured-question/resume, restart,
cancellation, and failure scenarios.
4. Reload the task while active, waiting, failed, and settled.
5. On the old implementation, observe stale run authority, missing
classifications, incomplete output, or duplicated/folded replies.
**Paperclip version or commit**
The repair is based directly on `master` at
`87d05e194b643810d16d20612115acd01d735d43`.
**Deployment mode**
Local development with the embedded database.
Related work: Refs #12616, #12646, #12666, #12685, and #12700.
## What Changed
- Rotates PRP control-plane, outbox, ticket, lease, command, receipt,
and sequence authority for each heartbeat while carrying forward only a
validated provider-session identity.
- Reads `control-plane-state.json`, validates both durable schemas and
lifecycle values, resumes coherent current runs, archives qualified
settled authority, and quarantines malformed or mismatched scoped state
without moving ambiguous live legacy state.
- Preserves Codex provider phase and stable item identities so
commentary remains progress and only `final_answer` becomes final.
- Adds raw OpenCode HTTP/SSE boundary coverage and canonical reasoning
lifecycle mapping.
- Makes ACPX normalization lossless for visible reasoning, tool
lifecycle metadata, stable bounded identities, Plan revisions,
structured requests, failures, and qualified process replacement. Only
the compatible terminal assistant message is promoted as final.
- Applies schema-aware redaction before generic JWT-shaped detection and
scans every diagnostic string leaf. Malformed raw/escaped quoted
credential tails are redacted in both server and durable Rust state.
- Restores snapshot-style chronological task presentation, expandable
tool activity, inline Plan cards, visible waiting/resume/cancel/failure
states, and exactly one final answer.
- Makes `never` the only qualified native Codex permission mode and
rejects unsupported persisted native modes with remediation. OpenCode
and ACPX policies remain intact.
- Keeps the unified experimental Runner setting as the only enablement
flag. Onboarding and direct Codex, Claude, and OpenCode stay on their
legacy execution/finalization paths.
- Adds cross-language goldens, authority/recovery/fault coverage, exact
response/count assertions, and native plus legacy acceptance scenarios.
## Verification
- Pull-request GitHub Actions run Rust formatting/tests, TypeScript
checks, server/UI tests, builds, protocol drift checks, browser E2E, and
security scans.
- A separate workflow-only validation ref is pinned directly on this PR
head and runs the 35-cell paid local matrix: three core scenarios plus
structured-question resume and restart/resume for native Codex, native
OpenCode, ACPX Claude, ACPX Codex, and direct Codex/Claude/OpenCode.
Run: https://github.com/paperclipai/paperclip/actions/runs/33682434315
- Acceptance requires exact single visible replies, monotonic sequences,
matching envelope discriminators, one semantic terminal, one run
terminal, no unresolved interaction, no duplicate mutation, no secret
leakage, provider continuity, and zero native rows for direct adapters.
- Per maintainer direction, tests are running in GitHub Actions rather
than on the slower local host. Only formatters and static diff checks
were run locally.
## Risks
- Recovery from old or partial filesystem state is sensitive. The repair
fails closed, preserves active or unverifiable authority, and
quarantines only state whose scoped ownership is safe to move.
- Provider event formats can change. Closed validators and boundary
goldens turn new or malformed events into visible diagnostics instead of
silent drops.
- Shared task presentation could affect direct adapters. Runtime-fact
gating plus the direct-adapter matrix protect the existing path.
- Managed and remote providers are not qualified here. Shared code
continues to compile and fail safely, but live qualification is
deferred.
> 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 based on GPT-5. The exact deployed snapshot and
context-window size are not exposed to this task. It used agentic
reasoning, repository inspection, code editing, Git, parallel subagents,
and GitHub Actions.
## 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
- [ ] I have run tests locally and they pass (intentionally deferred to
GitHub Actions)
- [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 risks above
- [ ] All Paperclip CI gates are green
- [ ] The paid local-provider matrix is 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
## Thinking Path
> - Paperclip is the control plane for AI-agent companies.
> - Agent outputs must remain visible after a run and easy to inspect
from a task.
> - The thread and artifact inventory need one consistent rich-card
vocabulary.
> - Run uploads also need durable artifact registration and
producing-run context.
> - Reviewers need deterministic examples for each rich-card kind and
state.
> - This pull request adds the shared presentation, registration,
inventory, and Storybook review coverage.
> - The benefit is a complete output path that reviewers can inspect
without seeded data.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
This change improves work-product presentation in task threads and the
task Artifacts tab.
**Subsystem affected**
The change affects shared work-product contracts, the runner diff path,
server attachment and work-product services, GitHub metadata refresh,
the React board UI, and Storybook.
**Current behavior**
The thread used generic cards. Some files uploaded by a run existed only
as message attachments. The Artifacts tab showed a flat list without run
context or filters. Storybook showed only one resting card per kind.
**Proposed behavior**
The thread uses rich cards for supported work-product types. Each
run-produced file registers one attachment-backed artifact work product.
The Artifacts tab groups outputs by run and supports filters. Storybook
shows every kind and requested state, PR lifecycle states, stats
variants, truncation, mobile layout, and message-tail media.
**Reason and benefit**
Users can identify outputs quickly. Reviewers can inspect all card
permutations without creating task data.
**Breaking changes**
None. The metadata fields and automatic artifact registration are
additive. Existing attachments and work products keep their current
behavior.
## What Changed
- Added a shared rich work-product card with kind-specific content and a
compact inventory variant.
- Added pull-request and commit diff metadata plus bounded GitHub state
refresh.
- Added media strips and typed file chips to message-tail attachments.
- Registered each run-produced attachment as an artifact work product in
the same server transaction.
- Grouped task artifacts by run with agent and timestamp headings.
- Added type and run filters, image thumbnails, compact cards, and a
company Artifacts link.
- Added a Storybook kind-by-state matrix with stats variants for all
eight visual kinds.
- Added PR open, draft, merged, and closed examples, long-title
truncation, an exact 375-pixel viewport, and message-tail overflow
coverage.
- Closed reconciled runtime work products when the linked runtime stops
or disappears, so the card shows `Stopped` instead of `Unhealthy`.
### Screenshots
Before: one resting card per kind.
After: the kind and state matrix.
After: message-tail media at 375 pixels.
[Open the Storybook evidence
viewer](https://pages.paperclip.ing/rich-work-product-storybook-20260902/).
The earlier artifact inventory comparison remains available in the
[artifact inventory
viewer](https://pages.paperclip.ing/rich-artifacts-inventory-proof-20260902/).
## Verification
- `pnpm --filter @paperclipai/ui typecheck` passed.
- `pnpm check:token-gates` passed.
- `pnpm build-storybook` passed.
- `pnpm exec vitest run
server/src/__tests__/work-product-runtime-reconciliation.test.ts` passed
with 5 tests.
- Chromium visual checks passed at desktop and 375-pixel widths.
- All 30 latest-head GitHub checks passed. One unrelated annotation test
was flaky and passed on its single retry.
- Greptile passed at 5/5 with zero unresolved threads.
## Risks
- Low risk. The Storybook change adds review fixtures only. The runtime
fix changes read-time reconciliation without database writes.
- The matrix is intentionally large so every permutation stays visible
in one review surface.
> I checked `ROADMAP.md`. This work does not duplicate planned core
work.
## Model Used
- OpenAI Codex with GPT-5 and GPT-5.6-sol across this pull request.
Reasoning, tool use, and code execution were enabled. The context-window
size is not exposed.
## 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 public branch name describes the change and contains no
internal task id
- [x] I have run tests locally and the changed-path tests 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 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The Apps subsystem gives humans and agents governed access to
external tools.
> - The current connection flow hides Apps behind an experimental gate
and repeats setup text.
> - Google sharing choices and generic MCP permissions do not use one
consistent opening model.
> - Self-hosted installs also need a safe default origin for managed
OAuth without a manual config file.
> - This pull request makes Apps available, simplifies connection setup,
and applies one governed permissions model.
> - The benefit is a shorter connection flow that works on a clean
self-hosted install.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
This improves the Apps connection setup flow, managed Google connection
flow, generic MCP connection flow, navigation, and runtime origin
discovery.
**Subsystem affected**
Cross-cutting. This changes `ui/`, `server/`, `packages/shared/`,
connector documentation, and browser tests.
**Current behavior**
Apps require an experimental switch. Setup pages repeat titles and
explanatory copy. Connection names require manual input. Google
credential sharing does not always offer both personal and organization
access. Generic MCP providers do not start with the same permission
choices. Managed OAuth needs a public URL setting even when the request
already has a safe HTTPS origin.
**Proposed behavior**
Apps are available by default. Setup asks only for required permissions
and sharing choices. Paperclip creates conflict-free connection names.
Google apps and generic MCP providers use the same human and agent
access model. Managed OAuth derives a validated same-origin HTTPS URL
when no explicit public URL is set.
**Reason and benefit**
A clean self-hosted install can connect a managed Google app without
hidden setup. Humans can share a service account with their
organization. The shorter flow reduces duplicated choices and setup
errors.
**Breaking changes**
The Apps experimental switch is removed. Existing connection APIs remain
compatible. New connections can receive a numeric suffix when a name
already exists.
No duplicate or related public issue was found.
## What Changed
- Removed the Apps experimental gate and the breadcrumb that leaves the
Apps section.
- Simplified all connection setup pages and moved optional provider
requirements into one small link.
- Added consistent human and agent access choices for Google apps,
Zapier, and generic MCP connections.
- Added organization sharing to Google Workspace credentials while
keeping personal access available.
- Generated connection names automatically and resolved name conflicts
with numeric suffixes.
- Derived a validated public HTTPS origin from the request for
config-free managed OAuth.
- Updated connector contracts, tests, browser coverage, and authoring
documentation.
## Verification
- `pnpm check:token-gates`
- `pnpm -r typecheck`
- `pnpm build`
- `pnpm exec vitest run server/src/__tests__/tool-access-service.test.ts
server/src/__tests__/generic-mcp-connection.test.ts` (273 passed)
- Targeted UI/service regression suite (308 passed)
- Six targeted Playwright connection journeys on a fresh onboarding
instance (6 passed)
- Fresh-install browser proof through Tailscale HTTPS: enrolled with
Paperclip Cloud, connected managed Google Drive, and completed a real
read operation.
- [Exact-head CI
run](https://github.com/paperclipai/paperclip/actions/runs/33669760711):
all 23 matrix jobs passed, including build, typecheck, server,
serialized, canary, and all browser shards.
- Greptile 5/5 on `0ae2a859f269984ee950d0af231a5b09a06f3dfd`, with no
unresolved review threads.
## Risks
Apps are now visible to all operators. The removed experimental flag no
longer hides unfinished app definitions. Managed Google availability
still depends on the Cloud profile rollout and active instance
enrollment. Automatic conflict handling changes only the display name of
a newly conflicting connection.
> I checked [`ROADMAP.md`](ROADMAP.md). MCP Tool Gateway and Apps are
shipped. Connected Apps is planned, and this change improves the
existing shipped connection flow.
## Model Used
OpenAI Codex, GPT-5, with reasoning, browser control, 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 (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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner subsystem executes agent work across local and managed
provider backends.
> - The lower pull requests restore the task runtime, provider backends,
and managed-provider control plane.
> - The restored system needs repeatable full-stack checks before it can
ship safely.
> - Paid live checks also need clear access, cost, and secret controls.
> - This pull request adds acceptance, live evaluation, chaos, and
release gates for the restored runner stack.
> - The benefit is measurable runner parity with safer release
decisions.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting. This change covers runner tests, release workflows,
server contracts, and evaluation tools.
**Problem or motivation**
The runner stack did not have one complete acceptance surface for native
Codex, ACPX, Claude Managed, and AWS AgentCore. Release checks could
miss provider drift, task-view regressions, cost-policy errors, and
destructive cleanup errors.
**Proposed solution**
Add a 57-cell full-stack catalog, a Daytona image, and opt-in paid
workflows. Add live evaluation, chaos, cost-limit, redaction, and
release contract checks. Add AWS AgentCore infrastructure and guarded
provisioning tools. Keep the native runner experimental flag off by
default.
**Alternatives considered**
We considered manual smoke tests only. They do not give repeatable
evidence and they do not protect release branches. We also considered
one large pull request. The stacked pull requests keep each review below
the Greptile file limit.
**Roadmap alignment**
This work supports the shipped Cloud / Sandbox agents milestone and the
shipped Agent evals & feedback milestone in `ROADMAP.md`.
Related stack:
- #12699 adds managed provider backends and lifecycle support.
- #12691 adds qualified OpenCode and ACPX provider backends.
- #12685 restores task runtime rendering and steering.
## What Changed
- Add the runner full-stack harness with 57 catalog cells and 60 unit
tests.
- Add a Daytona runner image with digest-pinned base images and
base-aware image-content checks.
- Add guarded live evaluation and chaos workflows with a fixed
40-execution matrix; live and full-stack paid schedules now run only on
Sundays or by manual dispatch.
- Add in-flight reported-usage cost stops, post-turn cost caps,
exact-threshold failure classification, secret redaction, retry
classification, and actor authorization.
- Reattach stream and hard-budget listeners before restart-recovery
continuations so restored paid sessions cannot bypass in-flight
interruption.
- Preserve OpenCode usage and cost across tool-loop messages and turns
while exposing an explicit current-run delta to durable accounting.
- Keep PNG/WebM evidence in access-controlled artifacts only, reject
SVG, and publish only pruned inert structured per-attempt evidence.
- Add AWS AgentCore infrastructure, provisioning checks, and smoke
tools; reject unsafe model identifiers, require exact stack ownership
markers, and make failed-stack replacement explicit.
- Add evaluation-session contracts and capability reports.
- Add release workflow checks for immutable action pins, frozen
dependency installs, exact weekly cron shape, paid-run guards,
provider-secret isolation, and chaos test paths.
- Reauthorize the original and triggering numeric actor IDs as the first
step of every provider-secret job, including partial reruns, before
checkout or provider access.
- Give each full-stack matrix cell only its matching provider
credential, expose Daytona only to Daytona cells, and disable shared
dependency caches anywhere paid credentials or OIDC write access are
present.
- Protect the legacy manual E2E workflow with the same default-branch,
allowlist, environment, and per-job authorization boundary.
- Rotate live-eval candidates by week and retain 120 days of compatible
history so the seven-week trend window remains viable.
- Restore the root runner-acceptance commands and reconcile reported
snapshots,
raw receipts, and terminal usage without double counting or losing late
usage.
- Mark ACPX token deltas exact only when every budget field is present,
keep
cumulative cost/request authority separate, reject non-USD cost
labeling,
and include thought tokens in output-token budgets.
- Keep `enableNativeRunner` off by default. The acceptance harness
enables it only in its isolated test instance.
## Verification
Passed locally:
- `pnpm --filter @paperclipai/paperclip-runner typecheck`
- `pnpm test:runner-acceptance:typecheck`
- `pnpm test:runner-acceptance` (19 tests)
- focused OpenCode proxy, driver, runnerd transport, live-session, and
turn-stream tests (106 tests)
- `pnpm --filter @paperclipai/paperclip-runner exec vitest run
src/live/clean-room-server.test.ts` (22 tests)
- `pnpm test:e2e:runner:typecheck`
- `pnpm test:e2e:runner:unit` (62 tests)
- `node --test scripts/__tests__/release-verify-workflow.test.mjs`
- `pnpm --filter @paperclipai/paperclip-runner
test:runner-workflow-evals` (22 tests)
- `pnpm -r typecheck`
- `pnpm build`
- `node --test
packages/paperclip-runner/scripts/aws-agentcore-provisioning.test.mjs`
(6 tests)
- `git diff --check`
- `cargo test --manifest-path
packages/paperclip-runner/runner/Cargo.toml -p paperclip-runner-core
--lib --locked` (161 tests)
- focused ACPX provider-event tests (10 tests)
- The rebased PR changes 92 files. `pnpm-lock.yaml` is unchanged.
I did not run paid live provider jobs or provision AWS resources. Those
checks need credentials and can create cost.
## Risks
The paid workflows can create provider cost. They require an allowlisted
original and triggering actor, the protected `runner-e2e-paid`
environment, explicit opt-in variables, and cost limits. The four
provider credentials exist only in that master-only environment, which
requires allowlisted reviewer approval and disables administrator
bypass; repository and organization Actions scopes contain no copies.
Provider usage arrives after a billable request, so the live guard
cannot prevent one request from crossing a threshold. It interrupts
immediately on the first reported threshold hit and permits no
continuation.
Visual evidence can contain secrets rendered as pixels. PNG/WebM remain
only in access-controlled workflow artifacts; SVG and per-attempt XML
are excluded, and S3/Pages receive a pruned structured dashboard.
The AWS scripts can create cloud resources. They use explicit commands,
least-privilege roles, KMS encryption, saved nonsecret metadata, and
explicit teardown.
This pull request does not enable the experimental native runner for
existing instances.
> 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 with GPT-5. The model used extended reasoning, tool use,
code execution, and parallel subagents.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The Paperclip Runner provides durable, provider-neutral agent
execution.
> - The current stack supports qualified local providers but omits the
managed provider paths from the integration branch.
> - Claude Managed Agents and AWS AgentCore need explicit profile
qualification, durable recovery, usage accounting, and cleanup controls.
> - This pull request adds those managed backends as the third part of
the Runner parity stack.
> - The benefit is managed execution without weakening the default-off
Runner rollout gate.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting: Runner, server orchestration, database profiles, CLI, and
adapter configuration UI.
**Problem or motivation**
The current Runner stack cannot select or execute the managed Claude
Agents API or AWS Bedrock AgentCore Harness backends. It also lacks
qualified profile storage and recovery checks for those remote
resources.
**Proposed solution**
Add qualified managed and remote profiles, API and CLI management, exact
provider selection, durable lifecycle handling, cumulative usage
accounting, bounded cleanup, and retention acknowledgement. Keep
`enableNativeRunner` default-off.
**Alternatives considered**
A direct copy of the old integration branch was rejected because its
provider contracts, model values, credential flow, and migration history
no longer match the current base. A single large parity pull request was
also rejected because stacked review keeps each subsystem bounded.
**Roadmap alignment**
This continues the existing Runner architecture and rollout work. It
does not introduce a separate execution system.
**Additional context**
This pull request is based on the merged #12691 and #12685 stack. It
also closes the delayed security-review findings reported on #12691 by
binding qualified ACPX and OpenCode launch artifacts to the bytes
actually executed. A GitHub search for managed agent, AgentCore, and
Claude managed work found no duplicate public issue or pull request.
## What Changed
- Add Claude Managed Agents and AWS AgentCore provider executors to
runnerd.
- Add qualified managed and remote profile storage, routes, OpenAPI
contracts, CLI commands, and migration 0237.
- Validate profile ownership, enabled state, exact qualified revision,
model, agent version, and secret binding before persistence and
recovery.
- Persist durable provider session and owned skill state for
restart-safe cleanup.
- Reconcile uncertain create responses and delete remote sessions before
owned skills.
- Track cumulative provider usage and enforce positive session spend
caps.
- Recover interrupted AgentCore usage at the next turn boundary by
charging the prior invocation ceiling exactly once; keep the session
gated until an explicit monotonic budget raise.
- Isolate AgentCore AWS configuration from host profiles and
credential-process/SSO configuration while preserving workload identity.
- Require OpenCode 1.18.17 and fixed build-owned provider-pack artifact
paths; remove the ambient executable override.
- Snapshot and content-verify ACPX and OpenCode commands, scripts, and
provider executables before launch. Linux executes sealed inherited
descriptors; macOS uses authenticated private snapshots with retry-safe
rematerialization at the spawn boundary.
- Persist canonical ACPX and OpenCode launch-profile digests, reject
drift across fresh recovery, and make recovery failures sticky.
- Close and journal unsafe ACPX active-turn recovery before any provider
bootstrap or reconnect.
- Add managed provider fields to the Runner configuration UI and
permission projection.
- Preserve the default-off `enableNativeRunner` experimental flag.
## Verification
- `pnpm -r typecheck`
- `pnpm build`
- Focused managed server, database, CLI, Runner TypeScript, Rust,
Claude, AgentCore, ACPX, OpenCode, process-supervisor, and
durable-recovery tests passed.
- `cargo test -p paperclip-runner-core --lib --locked` (160 tests)
- `cargo check --workspace --all-targets --locked`
- Native Codex integration tests passed (60 tests); native provider
tests passed (7 tests); server native-runtime tests passed (87 tests).
- Verified-launch replacement, nested-spawn retry, exact-version,
profile-drift, sticky-failure, and no-bootstrap active-recovery tests
passed.
- `git diff --check`
- The PR changes 91 files. `pnpm-lock.yaml` is unchanged. The Rust
workspace lockfile adds the approved `rustix` dependency used for safe
descriptor handling while `#![forbid(unsafe_code)]` remains enabled.
## Risks
- The provider APIs can change while they are in beta. Exact
qualification and fail-closed recovery checks limit drift.
- Remote cleanup can fail after a partial create. Durable ownership
inventories and retry-safe deletion preserve recovery state.
- Migration 0237 adds profile tables. The generated migration and
snapshot pass the repository migration checks.
- Managed execution can incur provider cost. Positive default spend caps
and explicit retention acknowledgement limit accidental use.
- An interrupted AgentCore invocation without final metadata is
conservatively charged to its active session ceiling. This can overstate
cost, but cannot undercount it; later work requires an explicit budget
increase.
- Linux qualified launches use sealed memory descriptors. macOS lacks
executable-descriptor APIs, so the runner uses owner-only private
snapshots and minimizes linked-path lifetime; hostile same-UID processes
remain outside the documented local-host trust boundary.
- The global Runner feature remains default-off.
> 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 tool use, code execution, and subagent review.
## 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 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner is the experimental native runtime for governed
agent work.
> - The runtime contracts already describe Codex, OpenCode, and ACPX
providers.
> - The merged control plane still rejected OpenCode and ACPX for new
runner agents.
> - Runnerd also selected only the Codex provider implementation.
> - This pull request activates the qualified OpenCode and ACPX paths
from the form to runnerd.
> - The benefit is one durable runner path with provider-specific
permissions and recovery.
## Linked Issues or Issue Description
Refs #12685
**Subsystem affected**
This change affects the runner package, server orchestration, adapter
configuration, and UI configuration.
**Problem or motivation**
Paperclip Runner stores provider contracts for OpenCode and ACPX. New
agents cannot select those providers. Runnerd cannot execute those
stored provider descriptors. The UI also shows only Codex.
**Proposed solution**
Accept the qualified OpenCode 1.18.17 profile and the fixed ACPX Claude
and Codex profiles. Route them through runnerd. Keep provider selection,
model selection, permissions, credentials, events, and recovery inside
closed provider-specific boundaries.
**Alternatives considered**
One option was to keep the contracts dormant. That option leaves stored
configuration and runtime behavior out of sync. Another option was to
enable every ACPX agent. That option is not safe because Pi does not yet
have the same verified launch path.
**Roadmap alignment**
This change supports the completed cloud and sandbox agent milestone. It
also supports self-healing runs and governed agent execution. It does
not add a new roadmap surface.
## What Changed
- Add one server profile resolver for Codex, OpenCode, and qualified
ACPX descriptors.
- Keep `adapterConfig` as the provider and permission authority for
fresh runs.
- Add Paperclip Runner provider, ACPX agent, and provider-specific
permission controls to the UI.
- Reset the model to a compatible qualified value when the provider
changes.
- Route Codex, OpenCode, and ACPX through the durable runnerd provider
selector.
- Add a durable ACPX executor with bounded state, recovery, events, tool
receipts, and identity checks.
- Remove Codex labels from OpenCode events, results, evidence, and
recovery diagnostics.
- Pass only provider-specific credential names to child processes.
- Keep ACPX Pi unavailable and reject it before process launch.
- Keep the existing Paperclip Runner experimental flag unchanged.
## Verification
- `pnpm exec vitest run
packages/paperclip-runner/src/backends/native-backend-factory.test.ts
packages/paperclip-runner/src/live/runnerd-codex-transport.test.ts
packages/adapters/codex-local/src/ui/build-config.test.ts
ui/src/adapters/codex-local/config-fields.test.tsx
server/src/__tests__/adapter-registry.test.ts
server/src/__tests__/adapter-routes.test.ts
server/src/__tests__/agent-adapter-validation-routes.test.ts
server/src/__tests__/company-portability.test.ts
server/src/services/native-runtime/runtime-mode.test.ts
server/src/services/native-runtime/native-session-executor.test.ts
server/src/services/heartbeat-runner-provider-config.test.ts`
- The focused TypeScript, server, and UI suites passed 274 tests.
- `cargo test -p paperclip-runner-core --test native_provider_backend`
- The executable native provider integration suite passed 4 tests.
- `cargo test -p paperclip-runner-core --lib`
- The Rust unit suite passed 91 tests.
- `pnpm -r typecheck`
- `pnpm check:token-gates`
- `pnpm build`
- `git diff --check codex/runner-parity-task-runtime...HEAD`
## Risks
- This changes provider process selection and durable recovery. The
experimental flag still gates every fresh Paperclip Runner run.
- OpenCode requires a model in `provider/model` form and stays pinned to
version 1.18.17.
- ACPX accepts only exact Claude and Codex profile versions and models.
Pi stays unavailable.
- ACPX steering stays unavailable and reports that limit through the
driver capabilities.
- Child processes receive explicit environment allowlists. They do not
inherit the full server environment.
- This pull request has no database migration.
## Model Used
OpenAI Codex, GPT-5, with tool use, code execution, and subagent review.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip runs agents through provider-specific adapters in local
and remote environments
> - A remote Grok run can refresh its credential inside its sandbox
> - The host copy can become stale when teardown discards that refreshed
credential
> - This pull request copies the refreshed credential back through a
locked, fail-closed teardown path
> - The benefit is that later Grok runs can use the refreshed host
credential without another login
## Linked Issues or Issue Description
Refs: #12618
**Agent or provider**
Grok local adapter.
**Why this adapter is useful**
A remote Grok run can refresh its access token during a run. Copying the
refreshed credential back to the host keeps later runs ready to use.
**How the agent is invoked**
Paperclip invokes the Grok local adapter through its remote subscription
run path. The adapter stages the company Grok home as a sandbox asset.
The change adds a copy-out step on the teardown path.
## What Changed
- `grok-auth-merge-decision.cjs` adds a host predicate in its own
process. It compares the whole `<issuer>::<uuid>` identity key of the
two files. It reads `expires_at` as an ISO-8601 string, an epoch-seconds
number, or an epoch-milliseconds number. It exits 10 to use the source,
20 to keep the destination, 21 when the expiry shape is unreadable, and
22 when the source expiry sits more than 400 days after the host clock.
It fails closed in every unclear case: an unusable side, a different
identity, an absent expiry, a tie, an unreadable expiry, and an
implausible expiry all keep the destination.
- `grok-auth-merge-decision.ts` adds a wrapper that runs the predicate
and maps the exit code to a typed result.
- `grok-auth-copyback.ts` adds `copyBackGrokAuth({ hostHomeDir,
readSandboxAuth, log, env })`. It locks on `hostHomeDir` with
`withDirectoryMergeLock`, stages the sandbox bytes into a private `0600`
temporary file, runs the predicate, and installs the file with an atomic
rename in the same directory. It keeps no backup of the displaced
credential. It leaves no temporary file on the success path, the keep
path, or an error path. On an error it logs the `errno` code only, then
re-throws.
- `execute.ts` adds a `restore` callback to the Grok `home` asset. The
callback takes the destination from
`resolveManagedGrokHomeDir(process.env, agent.companyId)`, never from
`env.GROK_HOME`. A copy-out failure does not fail the run.
- `package.json` updates the `build` script to copy
`grok-auth-merge-decision.cjs` into `dist/server/`, because `tsc` does
not copy a `.cjs` file.
**The credential shape this predicate reads**
A redacted sample of a real vendor credential answered four structural
questions. The answers hold no credential bytes, no account identifier,
no file path, and no timestamp value.
1. `expires_at` is present.
2. `expires_at` sits inside the value object, under the
`<issuer>::<uuid>` key. It is not a top-level field.
3. `expires_at` is an ISO-8601 string. It carries UTC time with a
trailing `Z` and six fractional-second digits.
4. A normal run rewrites `auth.json`. The value object carries a
`refresh_token` next to `expires_at`, so the client refreshes the access
token and rewrites the file.
## Verification
- [x] `pnpm vitest run packages/adapters/grok-local` — 114 tests in 12
files pass.
- [x] `pnpm --filter @paperclipai/adapter-grok-local typecheck` — clean.
- [x] `pnpm --filter @paperclipai/adapter-grok-local build` — succeeds,
and `dist/server/grok-auth-merge-decision.cjs` exists after the build.
- [x] Continuous integration is green on every check.
## Risks
The predicate keeps the host credential when identity, expiry, file
access, or freshness data is unclear. The copy-out path can log an error
and leave the run successful when it cannot install the refreshed
credential. The atomic rename and directory lock protect the host file
from partial writes and concurrent copy-out actions.
## Model Used
OpenAI GPT-5, current deployment. The exact runtime version and context
window are not exposed to this agent. The model used tool calls and code
inspection.
## 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>
## Thinking Path
> - Paperclip manages agents that use different model providers and
adapters.
> - Paperclip must keep agent execution rules clear and predictable.
> - The cheap-model profile added a second execution mode across
adapters, task recovery, APIs, and the UI.
> - That mode increased configuration and recovery complexity.
> - This pull request removes the cheap-model profile as a product
feature.
> - The benefit is one model-selection path for normal work and recovery
work.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
This change simplifies model selection across agent configuration, task
execution, recovery, and adapter capabilities.
**Current behavior**
Paperclip exposes cheap-model profiles in adapter metadata, agent
runtime configuration, task overrides, recovery rules, APIs, and the
board UI. Recovery work can select a different model profile from the
agent's configured model.
**Proposed behavior**
Paperclip uses the agent's configured model for normal work and recovery
work. Status-only recovery stays limited to coordination work. The API
rejects legacy model-profile configuration. A migration removes stored
model-profile values from existing agent, issue, and historical revision
records.
**Reason and benefit**
One model path reduces configuration, API, UI, and recovery complexity.
It also prevents status recovery from becoming a separate product-level
model-routing feature.
**Breaking changes**
This change removes model-profile fields and adapter capability
metadata. Existing stored model-profile values are removed by an
idempotent migration. The validators reject new legacy profile values
with clear errors.
## What Changed
- Removed model-profile types, adapter capabilities, API fields, and
model selection logic.
- Removed cheap-model controls from agent and task UI surfaces.
- Kept status-only recovery limited to coordination context while normal
continuations use the configured agent model.
- Added an idempotent migration that removes stored model-profile values
from agents, issues, and configuration revisions without changing issue
update timestamps.
- Updated tests and product documentation for the single-model behavior.
## Verification
- `pnpm check:token-gates` passes.
- `pnpm -r typecheck` passes.
- `pnpm build` passes.
- `pnpm test:run` completed with 5,607 passing tests and 8
environment-sensitive failures in unrelated fixed-port and
database-deadlock suites. The same failures repeated in an isolated
rerun. CI is the final clean-room result.
## Risks
- This is an intentional breaking change for clients that send
model-profile fields.
- The migration changes legacy agent, issue, and configuration-revision
JSON. It is idempotent and preserves unrelated fields and issue update
timestamps.
- The change is cross-cutting because the removed feature existed in
adapters, shared contracts, the server, plugins, and the UI.
> 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 with `gpt-5`. Reasoning and tool use were enabled. The
runtime did not expose the context-window size.
## 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)
- [ ] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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>
## Thinking Path
> - Paperclip is the open source app that people use to manage AI agents
for work.
> - Instance settings control optional product features and developer
tools.
> - The experimental settings page mixed active experiments, internal
tools, and old recovery controls.
> - Some workspace links also used the selected company instead of the
workspace owner.
> - These problems made settings hard to scan and could send users to
the wrong company route.
> - This pull request removes old controls, groups developer settings,
and resolves workspace links from workspace data.
> - The benefit is a smaller settings surface and correct workspace
navigation.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
This improves the instance experimental settings page, task watchdog
controls, dependency wake recovery, and execution workspace routes.
**Current behavior**
The settings page shows old recovery controls and mixes product
experiments with internal developer settings. Task watchdogs require an
extra feature flag. Some direct workspace links use the current company
prefix instead of the company that owns the workspace.
**Proposed behavior**
Remove the old task recovery experiment and its unused API surface. Make
task watchdog controls available without the removed flag. Put worktree
execution and managed environment controls in the developer section.
Resolve direct workspace links from the workspace owner and reject a
company prefix that does not own the workspace.
**Reason and benefit**
The smaller settings page is easier to understand. The server keeps only
the dependency wake backstop that it still uses. Workspace links open
under the correct company route.
**Breaking changes**
This removes the experimental issue graph recovery preview and run
endpoints. It also removes the task watchdog feature flag. Task watchdog
data and dependency wake behavior remain available.
## What Changed
- Removed the old task watchdog and issue graph recovery feature flags.
- Removed the old issue graph recovery preview, run controls, API
contracts, and unused recovery implementation.
- Kept resolved dependency wakes as the scheduler backstop.
- Grouped product experiments and Paperclip developer settings on the
instance settings page.
- Made task watchdog controls available without an extra experimental
flag.
- Added owner-aware redirects and company checks for execution workspace
routes.
- Hid the false stopped-state badge while a workspace has no active
runtime state.
- Updated focused server and UI tests for the new behavior.
## Verification
- `pnpm check:token-gates`
- `pnpm -r typecheck`
- `pnpm build`
- `pnpm test:run` completed with 5,620 passing tests and four failures
in unchanged workspace runtime port tests. The same four failures repeat
when the two files run alone.
- The complete GitHub CI matrix passed, including all server, serialized
server, build, canary, and end-to-end jobs.
## Risks
- Clients that call the removed experimental recovery endpoints must
stop calling them.
- The route checks depend on workspace detail access. An unknown or
cross-company workspace returns the global not-found page.
- There are no database migrations, lockfile changes, workflow changes,
or design image changes.
> 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 with GPT-5. The exact deployment ID and context window are
not exposed. Reasoning, tool use, and code execution were enabled.
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Paperclip Runner package manages live sessions and durable
command recovery
> - Capability live-session tests can fail when a turn-timeout rejection
has no handler
> - A resumed session can also stall when the durable control plane
rejects an indeterminate command result
> - These failures make valid tests fail or hide the turn that stalled
> - This pull request captures timeout rejections early and accepts
indeterminate recovered commands
> - The benefit is stable tests and clearer timeout failures after a
runner restart
## Linked Issues or Issue Description
**What happened?**
Capability live-session tests failed intermittently on loaded CI hosts.
A timer could reject a turn promise before the test attached its
assertion. A resumed session could also stall after a runner restart
because the durable control plane rejected the indeterminate command
status.
**Expected behavior**
The test must handle a timeout rejection at promise creation. The
durable control plane must accept an indeterminate recovered command and
allow the session to continue. A configured timeout must persist in the
checkpoint and identify the stalled turn.
**Steps to reproduce**
1. Run the capability live-session test file on a loaded host.
2. Create a turn promise with a timeout and delay before attaching its
assertion.
3. Resume a session after a runner restart with a journaled but
unconfirmed command.
4. Observe the unhandled rejection or the stalled resumed session.
**Paperclip version or commit**
Commit `ede642e57e22ea3fb0a73590fca8bcc994f1a47f` on `master`.
**Deployment mode**
Built from source.
**Installation method**
Built from source.
**Agent adapter(s) involved**
Not adapter-specific. The tests use the Paperclip Runner package.
**Database mode**
Not database-related.
**Additional context**
Pull request #12646 also updates durable recovery for indeterminate
command results. If it lands first, this pull request must retain the
compatible behavior without duplicate edits.
## What Changed
- Add a helper that captures a turn rejection before any await step.
- Update three live-session test sites to assert the captured rejection
value.
- Add a helper test that waits past the turn timeout before it asserts.
- Accept indeterminate as a terminal recovered-command status.
- Add tests for acceptance, duplicate absorption, and reload from
persisted state.
- Add an optional turnTimeoutMs value to resume and pin its checkpoint
behavior.
## Verification
- `npx vitest run src/live/live-session.test.ts` from
`packages/paperclip-runner`: 19 passed, 1 skipped.
- `npx vitest run src/control-plane/durable-prp-control-plane.test.ts`
from `packages/paperclip-runner`: 5 passed.
- The live-session file passed 10 of 10 runs with 30 competing workers
on a 32-core host.
- TypeScript reported five pre-existing errors in
`src/eval/workflow-harness.ts`.
- CI must run `pnpm --filter @paperclipai/paperclip-runner check:all`.
## Risks
The durable control plane now accepts one additional terminal recovery
status. The change affects only recovered command handling and
capability live-session tests. The main risk is overlap with pull
request #12646 if that pull request lands first.
## Model Used
OpenAI Codex, GPT-5, with 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 (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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip reports server and browser errors through optional Sentry
monitoring
> - One environment variable sends both error types to one Sentry
project
> - Operators need separate control for browser and server error data
> - This pull request adds specific variables and keeps the existing
variable as a fallback
> - The benefit is separate monitoring without breaking current
deployments
## Linked Issues or Issue Description
**What existing behavior does this improve?**
The Sentry configuration for server and browser monitoring uses one
environment variable.
**Subsystem affected**
Cross-cutting (multiple of the above)
**Current behavior**
`SENTRY_DSN` supplies the server and browser clients. Both clients
therefore report to the same Sentry project.
**Proposed behavior**
`SENTRY_DSN_FRONTEND` supplies the browser client. `SENTRY_DSN_BACKEND`
supplies the server process. `SENTRY_DSN` remains a fallback for either
component.
**Reason and benefit**
Operators can send browser and server errors to separate Sentry
projects. Operators can also activate only one component.
**Breaking changes**
None. Existing deployments can continue to use `SENTRY_DSN`.
## What Changed
- Add `resolveSentryDsns(env)` and use it in the server and browser
configuration paths.
- Add precedence, empty-string, fallback, and route tests.
- Update the README, observability guide, and stale code comments.
- Log one warning when the server uses the legacy fallback without
exposing a DSN value.
## Verification
- `pnpm vitest run --project server sentry-dsn` — 8 tests pass.
- `pnpm vitest run --project server auth-routes` — 21 tests pass.
- The earlier run of the three targeted suites passed 40 tests.
- `tsc --noEmit` passes for the files in this diff.
- All required GitHub Actions checks pass, including the full
continuous-integration suite.
## Risks
The main risk is an incorrect environment variable precedence rule. Unit
tests cover specific values, empty strings, and legacy fallback
behavior. The existing `SENTRY_DSN` path remains compatible.
## Model Used
OpenAI Codex — GPT-5, current runtime, 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 (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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Local adapters run agents in local or remote sandboxes.
> - A remote Grok subscription run needs its credential file inside the
sandbox.
> - The adapter did not stage the Grok home, so the sandbox had no
credential file.
> - This pull request stages only the allowed Grok credential file and
sets the reported home path.
> - The adapter removes the temporary staged home before teardown
completes.
> - The benefit is reliable Grok subscription authentication with
limited credential exposure.
## Linked Issues or Issue Description
**What happened?**
A remote Grok subscription run had no credential file in its sandbox.
The adapter sent no Grok home asset.
**Expected behavior**
The adapter should stage the allowed Grok credential file and set
`GROK_HOME` to the reported sandbox path.
**Steps to reproduce**
1. Start a remote Grok run in subscription mode.
2. Inspect the sandbox environment and home asset.
3. Confirm that the run has `GROK_HOME` and `auth.json`.
**Paperclip version or commit**
`3df33b5b8f49063a5d1ab608f8ce372572ef09d1`
**Deployment mode**
Remote sandbox run.
## What Changed
- Stage a private temporary Grok home for remote subscription runs.
- Copy only the allowed `auth.json` file and set its mode to `0600`.
- Pass the staged directory as the remote `home` asset.
- Set `GROK_HOME` to the path that the remote runtime reports.
- Remove the staged directory before awaited teardown calls.
- Keep the API-key lane free of credential staging.
- Add tests for the allowlist, file mode, empty source home, run lanes,
and teardown cleanup.
## Verification
- `pnpm vitest run packages/adapters/grok-local` passes.
- `pnpm --filter @paperclipai/adapter-grok-local typecheck` passes.
- `grok-home.test.ts` covers the allowlist, mode `0600`, and empty
source home.
- `execute.test.ts` covers the remote subscription lane, the API-key
lane, and cleanup after restore failure.
## Risks
- The change affects only remote Grok subscription runs that use a
credential file.
- The allowlist limits the staged content to `auth.json`.
- The API-key lane does not stage a home or set `GROK_HOME`.
- CI must confirm adapter behavior across the supported runtime matrix.
## Model Used
- Codex, GPT-5, current 2026 model version, large context window,
reasoning mode, and tool use assisted the repository handoff and pull
request management. The implementation author supplied the code and
local verification.
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The runner subsystem pairs a Rust runner process with a durable
control plane in TypeScript. The control plane is the authority for
every command the runner executes
> - That pair has a crash-recovery contract. If the runner dies between
journaling a command and confirming the command's effect, it must not
run the command twice
> - The runner keeps its side of the contract. On restart it promotes
such a command to the `indeterminate` status and reports that status
back
> - The control plane did not accept `indeterminate`. It closed the
connection without a diagnostic, the runner reconnected and replayed the
same result, and the loop repeated forever
> - This pull request accepts `indeterminate` as a terminal command
status
> - The benefit is that a session survives a runner crash during a tool
call, instead of hanging until a 30 second deadline expires
## Linked Issues or Issue Description
No public issue exists for this defect, so it is described here.
**What happened?**
A live session cannot resume after the runner process is killed during a
governed tool call. The resumed transport waits for the provider
identity for
30 seconds and then fails with `runnerd did not report its provider
identity`.
`packages/paperclip-runner/src/live/live-session.test.ts` covers this
exact
sequence in "terminates real runnerd after a durable receipt and resumes
its
exact provider thread". That test has a 15 second budget, so it reports
the
defect as `Test timed out in 15000ms` and reads like a flake.
**Expected behavior**
The resumed control plane accepts the runner's recovery report, the
runner
reports its provider identity, and the session resumes on its original
provider thread.
**Steps to reproduce**
Build the runner binary, then run the test:
```
cargo build --manifest-path packages/paperclip-runner/runner/Cargo.toml --locked --workspace --bins
cd packages/paperclip-runner
npx vitest run src/live/live-session.test.ts -t "terminates real runnerd"
```
It fails every time on an idle machine. It also fails at `560e7e48b`,
the
commit that added the test, so the defect is not a recent regression.
**Paperclip version or commit**
Reproduced on `master` at `0a422fda5`, which is the base of this branch.
**Deployment mode**
Local development, running the package test suite.
**Root cause**
`DurablePrpControlPlane.#commandResult` accepted only `completed`,
`failed`
and `rejected`. The runner reports a journaled-but-unconfirmed command
as:
```json
{ "status": "indeterminate",
"result": { "code": "execution_indeterminate",
"message": "runner recovered after journaling this command; it will not execute twice" } }
```
That status fell through to a silent `connection.close()`. The runner
reconnected after 250 ms, replayed the same result, and was closed
again. No
durable event ever reached the control plane, so the transport never saw
`harness.ready`.
`indeterminate` is a deliberate part of the runner's contract. See
`reconcile_pending_commands` in
`packages/paperclip-runner/runner/crates/runner-core/src/durable/state.rs`.
The rest of the TypeScript code already models the status; only this
control
plane did not.
## What Changed
- `DurablePrpControlPlane.#commandResult` accepts `indeterminate` as a
terminal command status.
- The persisted-state validation accepts `indeterminate`, so a control
plane
restarted over the same directory can read its own saved state back.
Without this, accepting the status would make the next restart throw.
- `DurableRecoveryCoreCommand.status` includes `indeterminate` in both
declarations of that interface.
- Added an integration test that drives the exact recovery frame the
runner
sends. It asserts the connection stays open, the next command is
delivered,
the status is persisted, a restarted control plane reloads it, and a
replayed duplicate is absorbed rather than treated as a conflict.
## Verification
All commands run from `packages/paperclip-runner`.
- New test fails before the change and passes after it. Before:
`expected null to match object { kind: 'command' }` — `null` is the
closed
connection.
`npx vitest run src/control-plane/durable-prp-control-plane.test.ts`
→ 4 passed.
- The live runner test that exposed this reproduced
**deterministically** on an
idle machine before the change, and now passes in 3.3 s, well inside its
existing 15 s budget. Ran it 10 times in a row: 10/10 pass, 0 failures.
`npx vitest run src/live/live-session.test.ts -t "terminates real
runnerd"`
- Full package suite: `npx vitest run` → 1298 passed, 1 failed. The one
failure is `src/mock-core/local-runner.test.ts > cleans up the harness
process group when the controller closes`. It fails identically on an
unmodified checkout in the same container, so it is a pre-existing
environment issue and not related to this change.
- Typecheck: `tsc -p tsconfig.json --noEmit` → clean.
I did **not** raise the test's timeout. The budget was never the problem
—
with a 600 s budget the same test still failed, at 31 s, with the real
error.
## Risks
Low risk, and it widens rather than narrows what is accepted.
- Behaviour only changes for a status that is currently rejected, so no
previously working path is affected.
- `indeterminate` is terminal, not successful. A caller waiting on such
a
command still receives an error from the transport, which is correct:
the
effect is genuinely unconfirmed. This change does not make an
unconfirmed
command look like it succeeded.
- The persisted-state change only widens an allow-list, so existing
state
files stay valid.
Open topics for a reviewer:
- The control plane closes connections without any diagnostic. That
silence is
why this defect looked like a flaky test. Adding a diagnostic channel is
a
larger change and is not included here.
- `DurableRecoveryProcessedCommand` in
`src/contracts/durable-recovery.ts`
drifts from the Rust `StoredCommandResult` by more than this status: it
declares `commandDigest` and `logicalEffectCount`, which Rust does not
have,
and omits `commandType`, which Rust does. That is a separate correction
and
is deliberately not folded in here.
## Model Used
Claude Opus 5 (`claude-opus-5`), extended thinking, with tool use and
code
execution.
Depends-on: none — this is a self-contained fix with no dependent
changes.
## 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
---------
Co-authored-by: zannis <1011451+zannis@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The runner subsystem drives a Codex provider process and reads its
events with `CodexProvider::poll`
> - The Codex provider integration tests wait for those events in poll
loops
> - Two of those loops count iterations instead of measuring time, so
they stop waiting too early
> - This makes `cargo test` fail at random on branches that change no
Rust code
> - This pull request bounds the two loops by wall clock, like every
other wait in the same file
> - The benefit is that a red CI job now means a real defect
## Linked Issues or Issue Description
**What happened?**
`packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rs`
fails
`cargo test` at random. The failure appears in the `ci / Build` job with
exit code 101.
It appears on branches that change no Rust code. Two tests fail:
-
`ambiguous_or_dead_replacement_start_preserves_result_not_exit_authority`
at line 1274
- `ambiguous_replacement_turn_adopts_one_later_completion_identity` at
line 1443
Both assertions report `left: None`. The value is not wrong. The loop
never saw the
`CodexProviderEvent::Exited` event at all.
**Expected behavior**
The tests must wait for the provider process to exit. A test must fail
only when the
provider gives a wrong result.
**Steps to reproduce**
1. Build the integration test: `cargo test --test codex_provider
--no-run`.
2. Run one of the two named tests 25 times in a row.
3. About 8 of the 25 runs fail with `left: None`.
**Paperclip version or commit**
Reproduced on `master` at `2e5a24e17`.
**Related pull requests**
Refs #12241. That pull request also edits
`packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rs`.
It does not
fix these two loops. The two changes may need a merge if both land.
**Root cause**
`CodexProvider::poll` (`crates/runner-core/src/codex_provider.rs:824`)
reads with a 1 ms
timeout. That timeout does not apply on every path.
`ProcessSupervisor::receive_stdout_line`
(`crates/runner-core/src/process_supervisor.rs:293`)
returns at once, and uses none of the 1 ms budget, in two cases:
`StdoutClosed` at line 309
and `RecvTimeoutError::Disconnected` at line 315.
A child process closes its pipes before its exit status is ready to
reap. In that window
every `poll()` call returns `Ok(None)` in nanoseconds. A loop of 64 or
128 iterations then
ends in microseconds, before the exit status is available. The failing
run above ends in
0.06 s.
## What Changed
- `tests/codex_provider.rs`: bound the exit wait at line 1256 by a 5
second deadline instead
of 64 iterations.
- `tests/codex_provider.rs`: bound the exit wait at line 1397 by a 5
second deadline instead
of 128 iterations.
- Both loops now sleep 1 ms when `poll()` returns no event. This copies
the pattern that the
same file already uses at line 1511 and in every `wait_for_*` helper.
- No production code changes. The change is test-only.
## Verification
Measured before and after the change. Each test ran 25 times in
sequence, on an idle
machine, with `--test-threads=1`.
| test | before | after |
|---|---|---|
|
`ambiguous_or_dead_replacement_start_preserves_result_not_exit_authority`
| 8 / 25 failed | 0 / 25 failed |
| `ambiguous_replacement_turn_adopts_one_later_completion_identity` | 9
/ 25 failed | 0 / 25 failed |
The full `codex_provider` suite also ran 12 times with
`--test-threads=4` after the change.
Every run passed.
Commands:
```
cargo test --test codex_provider --no-run
cargo test --test codex_provider
```
## Risks
Low risk. The change touches test code only. It makes two waits longer
in the failure case:
a genuinely broken provider now takes up to 5 seconds to fail these two
tests instead of
microseconds. Every other wait in this file already uses the same 5
second deadline.
## Model Used
Claude Opus 5 (`claude-opus-5`), extended thinking, with tool use and
code execution.
Depends-on: none — this is a self-contained test-only change with no
prerequisite pull request.
## 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)
- [ ] 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 — none
apply. This change is test-only and alters no public interface, so no
docs page and no end-to-end test change is needed.
- [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
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: zannis <1011451+zannis@users.noreply.github.com>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner is an experimental execution adapter.
> - The adapter and its required sandbox ingress had separate settings.
> - A user could enable one setting and still have an unusable runner
configuration.
> - The runtime already makes one durable native or legacy decision for
each run.
> - This pull request uses that runtime decision for ingress
authorization.
> - The benefit is one clear opt-in with safe recovery for existing
native runs.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
This improves the experimental settings and transport authorization for
Paperclip Runner.
**Subsystem affected**
Cross-cutting. This change affects the React settings UI, shared
settings contracts, adapter utilities, and server runtime selection.
**Current behavior**
Settings shows separate Paperclip Runner and Runner Preview Ingress
controls. A user can enable the runner but leave required sandbox
ingress disabled.
**Proposed behavior**
Settings shows only Paperclip Runner. Its native runtime decision also
authorizes provider WebSocket ingress when the execution target requires
it. A persisted native run keeps its recovery transport after the
setting is disabled.
**Reason and benefit**
Paperclip Runner is one experimental capability. One opt-in removes an
invalid partial configuration and makes the rollout boundary easier to
understand.
**Breaking changes**
The Runner Preview Ingress card is removed. The old
`enableRunnerPreviewIngress` key remains accepted in stored settings and
managed configuration, but it has no server runtime effect. The public
adapter-utils input remains compatible through a deprecated alias.
**Additional context**
Refs: #12638, #12641, #12656.
## What Changed
- Removed the separate Runner Preview Ingress card from Experimental
Settings.
- Made resolved native runtime selection authorize required provider
ingress.
- Preserved ingress recovery for persisted native runs after the rollout
flag is disabled.
- Kept the old settings key and adapter-utils input as deprecated
compatibility contracts.
- Added focused UI, runtime policy, transport, stored-settings, and
managed-config regression tests.
- Updated deployment documentation and feature descriptions.
## Verification
- GitHub Actions will run typecheck, tests, build, policy, and browser
shards.
- Focused tests cover the single settings control, runtime
authorization, fail-closed transport selection, the deprecated public
input, and old managed configuration.
- No local tests were run, per the maintainer request to use GitHub
Actions for verification.
- `git diff --check` passes.
## Risks
Low to moderate risk. The effective ingress gate changes from a separate
stored flag to the resolved native run decision. Fresh runs still
require `enableNativeRunner`. Persisted native runs remain recoverable.
Legacy adapters never receive ingress authorization.
> 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 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner needs repeatable evaluation contracts.
> - Evaluation code must stay separate from provider launch and
production orchestration.
> - Offline fixtures need stable compatibility, scoring, traceability,
and report rules.
> - Published Runner consumers need only the supported evaluation
contract surface.
> - This pull request adds offline evaluation tooling and a
workspace-private matrix kernel.
> - The benefit is deterministic evaluation without credentials or paid
provider calls.
## Linked Issues or Issue Description
Refs #11297
This pull request extracts the offline evaluation unit from the earlier
aggregate Runner work.
## What Changed
- Add a workspace-private, provider-neutral evaluation matrix kernel.
- Add the public `@paperclipai/paperclip-runner/evals` compatibility and
native execution contracts.
- Add fail-closed runnerd artifact and protocol compatibility checks.
- Add deterministic workflow catalogs, scoring, traceability, and report
generation.
- Add sanitized Codex, OpenCode, and ACPX fixtures.
- Add package-boundary and clean-consumer checks.
- Add the eval package manifest to the Docker dependency stage.
- Add the generated protocol fixture digest without changing the
lockfile.
## Verification
GitHub Actions must run:
- Runner TypeScript and Rust type checks.
- Runner unit and protocol tests.
- Evaluation kernel tests.
- Workflow traceability checks.
- Clean-consumer and package-boundary checks.
- Repository test, type-check, build, policy, and security gates.
No local test command was run. The repository owner requested
GitHub-only verification.
## Risks
This is a large greenfield review surface with 51 files. The code does
not launch a live provider or load credentials. Package and protocol
drift fail closed. The workspace lockfile remains under the existing
CI-owned process.
## Model Used
OpenAI Codex with the GPT-5 agent model. The work used high reasoning,
repository inspection, tool use, and parallel code review.
## 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
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner currently enables only the Codex production path.
> - The package also contains dormant OpenCode and ACPX provider
boundaries.
> - Dormant boundaries must still fail safe before later activation
work.
> - Provider children must not inherit unrelated server secrets or host
homes.
> - Permission defaults must require interaction instead of broad
automatic approval.
> - This pull request hardens those boundaries without activating them.
> - The benefit is a safer base for later provider-specific runnerd
work.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
This improves the inactive OpenCode and ACPX provider boundary in
Paperclip Runner.
**Subsystem affected**
The adapter permission contract, Runner provider environment, and native
execution input builder.
**Current behavior**
Dormant OpenCode code can inherit the full server environment. Its
default permission mode allows operations. ACPX also defaults to broad
approval. The provider guard can accept inherited object property names.
**Proposed behavior**
Use exact provider identifiers. Use interactive defaults. Allow only
required OpenCode environment keys. Reject invalid proxy permission
modes.
**Reason and benefit**
This reduces accidental authority and secret exposure before future
provider activation.
**Breaking changes**
No production provider is activated. Codex runtime selection and Codex
credential-home discovery do not change. Dormant OpenCode and ACPX
callers that omit permission modes now receive safer defaults.
## What Changed
- Change dormant OpenCode and ACPX permission defaults to interactive
modes.
- Reject prototype property names as provider identifiers.
- Default dormant ACPX input to the qualified Codex agent profile.
- Add an explicit OpenCode runner environment allowlist.
- Exclude host homes, server credentials, database values, and Node
injection options.
- Add a fail-closed OpenCode proxy permission parser.
- Add focused tests for defaults, filtering, and invalid values.
## Verification
GitHub Actions must run:
- Adapter utility tests.
- Paperclip Runner tests, type checks, and build.
- Server native runtime tests.
- Repository test, type-check, build, policy, and security gates.
No local test command was run. The repository owner requested
GitHub-only verification.
## Risks
Future OpenCode credential providers must add required variables to the
allowlist through review. The safer defaults can pause dormant internal
scenarios that relied on implicit broad approval. Production Codex
behavior is unchanged.
## Model Used
OpenAI Codex with the GPT-5 agent model. The work used high reasoning,
repository inspection, tool use, and parallel security review.
## 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
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip supports direct adapters and an experimental native Runner
path.
> - These paths need one stable compatibility matrix.
> - The matrix must not launch providers or load credentials during
normal tests.
> - Result handling must reject incomplete output and sensitive values.
> - This pull request adds a credential-free acceptance foundation.
> - The benefit is a reviewable contract for later end-to-end executors.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
This improves verification for direct adapters and Paperclip Runner
providers.
**Subsystem affected**
Cross-cutting test infrastructure for adapters, the server runtime, and
the task thread.
**Current behavior**
The repository has subsystem tests. It does not have one declarative
matrix for direct and native compatibility.
**Proposed behavior**
Add a pure acceptance catalog, result validator, redaction helpers, and
failure classification. Keep all execution authority outside this
change.
**Reason and benefit**
The matrix makes legacy isolation and native recovery requirements
explicit. The helpers let later executors report safe and complete
results.
**Breaking changes**
None. This change does not alter production runtime selection or start
any provider.
## What Changed
- Add a catalog for built-in direct adapters and qualified native
provider profiles.
- Add compatibility cases for runtime selection, task threads,
questions, and flag-change recovery.
- Add pure redaction and transient-failure classification helpers.
- Add fail-closed Markdown and JUnit report aggregation.
- Add isolated test and type-check commands.
- Document the credential-free boundary and deferred live execution
work.
## Verification
GitHub Actions must run:
- `pnpm test:runner-acceptance`
- `pnpm test:runner-acceptance:typecheck`
- The repository test, type-check, build, policy, and security gates.
No local test command was run. The repository owner requested
GitHub-only verification.
## Risks
Low production risk. The change adds test-only files and root scripts.
The catalog can drift when a built-in adapter changes. Its validation
fails closed on that drift.
## Model Used
OpenAI Codex with the GPT-5 agent model. The work used high reasoning,
repository inspection, tool use, and parallel code review.
## 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
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Administrators need bounded controls for experimental native
execution.
> - The lower stack adds remote Codex execution and the task workspace.
> - Operators need to configure Codex safely and inspect provider
traces.
> - Unsupported providers must not appear as runnable choices.
> - This pull request adds Codex-only administration and observability.
> - The benefit is a default-off operational surface for production
diagnosis.
## Linked Issues or Issue Description
Refs #12640.
Refs #12616.
Refs #12352.
**Subsystem affected**
Agent configuration, instance experimental settings, run ledger,
provider trace inspector, and administrator actions.
**Problem or motivation**
The native runner lacks one safe operator surface for Codex permissions,
lifecycle, raw trace capture, and run inspection. The integration branch
also contains provider choices that the production backend cannot
execute yet.
**Proposed solution**
Expose only the qualified Codex controls. Keep Paperclip Developer Mode
and runner preview ingress off by default. Gate raw trace actions by
administrator access and existing trace authorization.
**Alternatives considered**
Exposing unfinished providers would create configurations that fail at
runtime. Always-on tracing would increase sensitive data and storage
risk.
**Roadmap alignment**
This work supports governed Cloud and Sandbox agents and production
diagnostics.
## Stack
- Base PR: #12640.
- Lower PRs: #12639 and #12638.
- This PR contains only its 54-file administration and observability
delta.
- This is the final feature PR in the Codex production stack.
## What Changed
- Added Codex-only Paperclip Runner permission and lifecycle controls.
- Added bounded warm idle configuration.
- Kept the provider field fixed to Codex.
- Added administrator-only one-run raw trace requests.
- Added a persistent future-run raw trace toggle.
- Added trace status, metadata, ledger, and canonical runner inspection.
- Added JSON-RPC request-origin grouping and finalization lineage.
- Restored the stateful PRP transcript parser and focused projection
tests required by trace inspection.
- Added default-off Paperclip Developer Mode.
- Added Honeycomb run links for authorized developer mode.
- Disabled the legacy operational skill for `paperclip_runner`.
- Did not expose OpenCode, ACPX, Pi, Claude Managed, or AWS runner
choices.
- Did not change migrations, workflows, dependencies, or
`pnpm-lock.yaml`.
## Verification
- GitHub Actions will run UI tests, server tests, repository typecheck,
build, browser tests, security, and policy gates.
- Tests cover Codex configuration defaults and bounds, administrator
trace actions, persistent settings, ledger inspection, trace lineage,
and Honeycomb links.
- Existing server trace authorization and retention tests remain the
backend authority.
- Local tests were not run. The requested verification policy uses
GitHub Actions for this series.
- `git diff --check runner/task-workspace-experience...HEAD` passes.
- The delta contains 54 files.
## Risks
- Raw provider traces can contain sensitive provider data.
- Existing server authorization controls access, reveal, download,
retention, and deletion.
- The UI gates trace actions by administrator access and developer mode.
- All new instance settings remain off by default.
- Fresh Paperclip Runner configuration remains Codex-only.
- Direct adapters and legacy task behavior do not change in this PR.
> 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 with GPT-5.6. The work used high-reasoning agent mode,
repository tools, GitHub tools, and parallel code-audit agents.
## 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 or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner gives native runs a durable and governed execution
path.
> - The lower stack PR adds authenticated remote execution targets and
provider ingress.
> - The Rust daemon currently accepts only loopback plaintext WebSocket
connections.
> - Remote Codex needs authenticated WSS dialing and provider-ingress
listener mode.
> - This pull request adds the bounded Rust transport contract.
> - The benefit is a secure transport layer for the Codex remote
vertical slice.
## Linked Issues or Issue Description
Refs #12638.
Refs #12616.
Refs #12352.
**Subsystem affected**
Paperclip Runner Rust transport and remote runner networking.
**Problem or motivation**
The runner daemon cannot connect to a public control plane with TLS. It
also cannot accept a provider preview connection on the run-bound
ingress path.
**Proposed solution**
Add WSS with native trust roots and an optional private CA bundle. Add a
fixed authenticated listener mode for provider ingress. Advertise the
exact transport contract through build metadata.
**Alternatives considered**
Plaintext public WebSocket connections would weaken the transport
boundary. A general listener would expose more network surface than the
run-bound provider ingress requires.
**Roadmap alignment**
This work supports the Cloud and Sandbox agents milestone. It also
supports self-healing native runs.
## Stack
- Lower merged PR: #12638.
- This PR contains only its 13-file delta against `master`.
- Later stack PRs add the task workspace and administrator UI.
## What Changed
- Added WSS dialing with rustls and native certificate roots.
- Added an optional bounded private CA bundle that augments native
roots.
- Kept plaintext WebSocket dialing restricted to loopback addresses.
- Pinned resolved dial addresses for the process lifetime.
- Added a fixed `0.0.0.0:43127` listener with an exact run-bound path.
- Rejected listener queries, ambiguous paths, and WebSocket extensions.
- Kept frame and message size bounds.
- Added bounded reconnect grace and exponential jitter.
- Retried bootstrap failures only before authentication proof
transmission begins.
- Kept post-proof failures fail-closed and bounded the welcome exchange
at two seconds.
- Added runnerd build metadata for the versioned transport contract.
- Updated Rust dependencies and `Cargo.lock` only for TLS and
certificate handling.
- Did not add provider dispatch, Pi, AWS, `pnpm-lock.yaml`, migrations,
or workflows.
## Verification
- GitHub Actions will run Cargo formatting, Rust tests, repository
tests, typecheck, build, security, and policy gates.
- Rust tests cover URL validation, listener path validation, build
metadata, durable recovery, and the existing Codex provider path.
- Local tests were not run. The requested verification policy uses
GitHub Actions for this series.
- `git diff --check master...HEAD` passes.
- The delta contains 13 files.
## Risks
- TLS and listener changes affect the runner trust boundary.
- Public plaintext transport remains rejected.
- The listener uses one fixed port and one exact run-bound path.
- PRP authentication remains required after the WebSocket upgrade.
- The optional CA file uses the existing private-file checks and a 4 MiB
limit.
- This PR does not enable another provider or change direct adapters.
> 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 with GPT-5.6. The work used high-reasoning agent mode,
repository tools, GitHub tools, and parallel code-audit agents.
## 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 or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner gives native runs a durable and governed execution
path.
> - The current native path runs on the control-plane host.
> - Remote environments need an authenticated execution-target contract.
> - The contract must not change direct adapters or enable new runtimes
by default.
> - This pull request adds the remote execution substrate and Daytona
ingress.
> - The benefit is a bounded base for later remote runner transport
work.
## Linked Issues or Issue Description
Refs #12616.
Refs #12352.
**Subsystem affected**
Cross-cutting. This change touches runner transport, server
orchestration, plugin contracts, and shared settings.
**Problem or motivation**
Native execution cannot resolve an authenticated runner ingress through
a remote environment. The server also lacks one provider-neutral
contract for remote execution targets.
**Proposed solution**
Add a default-off runner preview ingress capability. Add
transport-neutral runner connectivity. Add remote execution target and
lifecycle handling. Add a Daytona ingress implementation with redacted
credentials.
**Alternatives considered**
A provider-specific server path would duplicate orchestration and
authorization. A public endpoint without an environment contract would
weaken the trust boundary.
**Roadmap alignment**
This work supports the Cloud and Sandbox agents milestone. It also
supports self-healing runs and governed tool access.
## What Changed
- Added execution-target traits for local, SSH, and sandbox
environments.
- Added plugin RPC contracts for runner ingress endpoints.
- Added authenticated Daytona preview ingress.
- Added transport-neutral PRP outbound connections.
- Added remote runner artifact verification and fail-closed provider
selection.
- Added bounded native session resume, cancellation, and lifecycle
recovery.
- Preserved Codex-only selection for fresh experimental runner starts.
- Preserved all direct adapter execution and finalization paths.
- Removed stale Pi provider-pack requirements that security review
rejected.
- Kept the rollout controls off by default.
- Did not change pnpm-lock.yaml, Cargo, database migrations, or GitHub
workflows.
## Verification
- GitHub Actions will run the repository test, typecheck, build,
security, and policy gates.
- Focused tests cover ingress validation, redaction, execution targets,
remote lifecycle, cancellation, resume, and legacy adapter selection.
- Local tests were not run. The requested verification policy uses
GitHub Actions for this series.
- `git diff --check origin/master...HEAD` passes.
- The diff contains 52 files.
## Risks
- Remote execution crosses a trust boundary.
- The implementation validates target capabilities, artifact digests,
provider-pack pins, and connection metadata.
- The feature remains default-off.
- Fresh native selection remains Codex-only.
- Existing direct adapters remain on the legacy path.
- This PR does not yet make remote Codex runnable. The next PR adds the
Rust WSS and TLS transport.
## Model Used
OpenAI Codex with GPT-5.6. The work used high-reasoning agent mode,
repository tools, GitHub tools, and parallel code-audit agents.
## 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 or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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 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
## Thinking Path
> - Paperclip is the open source control plane for teams of AI agents.
> - Agent runs currently use direct adapters and their established
finalization paths.
> - The new runner package needs one production integration before it
can execute a real provider through the server.
> - That integration must not change direct adapters or expose
unsupported providers.
> - The rollout must also preserve native runs that were already
recorded when the feature flag changes.
> - This pull request adds a default-off, Codex-only native execution
path and its authority boundary.
> - The benefit is a recoverable production vertical slice with explicit
compatibility guards.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting server orchestration and adapter selection.
**Problem or motivation**
The runner package exists, but the server cannot yet start and recover a
governed Codex run through it. A careless integration could also route
existing direct adapters into the native runtime or lose cancellation
and finalization state.
**Proposed solution**
Add a hidden `paperclip_runner` adapter for Codex. Keep it behind the
default-off instance flag. Bind native execution, resume, cancellation,
semantic tool authority, and finalization to the recorded company,
issue, run, and coordinator identities. Leave every direct adapter on
its existing path.
**Alternatives considered**
A multi-provider launch was rejected because only Codex has the complete
production bridge in this series. Replacing direct adapter execution was
rejected because the runner remains experimental.
**Roadmap alignment**
This work supports governed tool access, action attribution, and
self-healing runs. It keeps the integration narrow and default-off.
## What Changed
- Add the Codex-only native session executor and persisted resumption
path.
- Add run-scoped semantic tool projection, authorization, receipts, and
idempotency.
- Add audited native cancellation with durable issue and coordinator
binding.
- Add result fencing so a recorded result cannot reacquire the provider
and run twice.
- Reject fresh runner starts when the rollout flag is off while
preserving recorded native recovery.
- Keep direct adapters outside native status, cancellation, record
creation, and finalization.
- Add focused conformance, recovery, cancellation, status, portability,
and compatibility coverage.
## Verification
- GitHub Actions is the authoritative test environment for this large
stack.
- The PR policy and lightweight stack checks run while this is a middle
PR.
- The full required suite runs when this PR becomes the lowest unmerged
or top PR.
- Greptile will review this exact delta after the branch is pushed.
## Risks
- The main risk is routing a legacy adapter into native execution.
Runtime selection and heartbeat tests cover that boundary.
- The next risk is stale or cross-company cancellation. Durable binding
checks and transactional audit persistence cover it.
- The adapter remains hidden and default-off. Only Codex is admitted.
- There are no database migration, lockfile, or GitHub workflow changes
in this PR.
## Stack
1. [Runner package, SDK, and developer
tools](https://github.com/paperclipai/paperclip/pull/12608)
2. This PR: Codex production server integration
3. [Provider-neutral task-thread
UI](https://github.com/paperclipai/paperclip/pull/12617)
## Model Used
OpenAI Codex with GPT-5, extended reasoning, repository tools, and
parallel review agents.
## 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
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package already provides the production protocol and
execution spine.
> - Contributors still need stable SDK surfaces, deterministic test
tools, and local inspection tools.
> - Those surfaces share generated contracts and must change as one
package boundary.
> - This pull request adds the package-local SDK, labs, examples, and
drift checks.
> - The benefit is a reviewable developer platform that does not change
application execution selection.
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` — runner SDK, conformance tools, and
developer tooling.
**Problem or motivation**
The production runner spine is present, but package consumers cannot
build deterministic integrations, inspect sessions, or verify
provider-neutral behavior through supported surfaces.
**Proposed solution**
Add browser, React, standalone, live-session, scenario, conformance, and
evaluation surfaces. Add generated contract inventories and
package-local verification scripts. Keep production application routing
unchanged.
**Alternatives considered**
We considered splitting each generated catalog, SDK surface, and demo
into separate pull requests. Those changes share exports, fixtures, and
drift gates. Splitting them would create intermediate package states
that do not build.
**Roadmap alignment**
No overlapping item appears in `ROADMAP.md`. This work extends the
runner package that is already on `master`.
## What Changed
- Add browser, React, standalone, live-session, and issue-thread SDK
surfaces.
- Add deterministic mock control-plane, scenario, conformance, replay,
and evaluation tools.
- Add bounded Codex, OpenCode, and ACPX development transports and
fixtures.
- Keep deferred managed-provider execution fail-closed. Persisted
compatibility data remains readable.
- Add generated capability inventories with their source files and drift
checks.
- Add examples, package documentation, browser checks, and
clean-consumer checks.
- Preserve the reviewed protocol bounds, replay compatibility aliases,
process environment isolation, and semantic redaction limits.
- Update the ACPX package patch that the existing workspace patch
registry already tracks.
- Do not change `pnpm-lock.yaml`, repository workflows, server runtime
selection, or the application UI.
## Verification
GitHub Actions is the verification authority for this pull request. The
repository CI, package TypeScript and Rust checks, package tests,
generated-output drift checks, browser checks, security scans, and
Greptile review must pass on the exact head.
Local test suites were not run because this series uses parallel GitHub
Actions for verification.
## Risks
This is a large greenfield package change. The main risks are public
export drift, generated-output drift, and optional React consumer
compatibility. Package boundary checks, clean-consumer checks, and
browser tests cover those risks. Production adapter selection and server
execution are outside this pull request.
## Stack
1. **This PR:** runner SDK and developer tooling.
2. [Codex production server
integration](https://github.com/paperclipai/paperclip/pull/12616).
3. [Provider-neutral task-thread
UI](https://github.com/paperclipai/paperclip/pull/12617).
## Model Used
OpenAI Codex, GPT-5, high-reasoning mode, with 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 described the issue in-PR following the feature request
template
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Apps system gives agents governed access to external services
> - The managed Google Workspace connector uses separate profiles for
each app and access level
> - Several app definitions and callback paths did not enforce the same
profile contract
> - The default method could also select a customer OAuth setup when a
managed read profile was available
> - This pull request aligns the profile contracts, setup guidance,
default selection, and activity attribution
> - The benefit is a consistent managed connection flow for every Google
Workspace app
## Linked Issues or Issue Description
N/A — no public GitHub issue exists for this follow-up. Related merged
work:
[#12600](https://github.com/paperclipai/paperclip/pull/12600) and
[#12609](https://github.com/paperclipai/paperclip/pull/12609).
This change follows the merged Paperclip Cloud managed OAuth broker
work. It does not add a new broker or provider client.
**What happened?**
The Google Workspace connection definitions could drift from the shared
connector profile registry. The callback activity always named Gmail.
Google Sheets did not show the Developer Preview requirement. The setup
flow could select a customer-owned write method when Cloud advertised
only a managed read profile. The tool-access service had no non-Gmail
managed callback test.
**Expected behavior**
Each managed Google Workspace profile must use its exact app slug, MCP
URL, scopes, ownership, risk tier, and write-tool policy. Callback
activity must name the correct app and profile. Every Google Workspace
card must show the same Developer Preview prerequisite. An available
managed method must be the default within the selected capability. The
customer-owned method must remain available as a fallback.
**Steps to reproduce**
1. Advertise only the `gmail.read` managed profile.
2. Open the Gmail connection setup.
3. Observe that the customer-owned draft method becomes the default.
4. Complete a managed Google Drive callback.
5. Observe that the activity row names Gmail instead of Google Drive.
6. Open the Google Sheets setup.
7. Observe that it does not show the Google Developer Preview
prerequisite.
**Paperclip version or commit**
Current `master` at the start of this follow-up.
**Deployment mode**
Local development. The same connector definitions apply to Cloud-hosted
and self-hosted instances.
**Installation method**
Built from source with pnpm.
**Agent adapter(s) involved**
Not adapter-specific. This change affects the core Apps and tool-access
paths.
## What Changed
- Added one table-driven invariant for all 16 Google Workspace profiles.
- Verified each profile against its app slug, MCP URL, exact scopes,
capability, ownership, grant kind, risk tier, and write-tool allowlist.
- Kept the Google Chat write profile least-privilege because its only
enabled write tool is `send_message`.
- Added the Google Developer Preview prerequisite to Google Sheets.
- Preferred an available Paperclip-managed method before a
customer-owned method.
- Preserved explicit capability selection and the customer OAuth
fallback.
- Switched managed-profile availability from the anonymous global
capability document to the enrolled instance's signed status response,
so internal-pilot profiles cannot be enabled locally without an
authorized instance binding.
- Replaced the Gmail callback activity constant with the validated app
slug and connector profile.
- Added connector and route coverage for signed per-instance
capabilities, including inactive and malformed responses.
- Added a Google Drive callback test that covers the signed profile
request, personal vault refs, encrypted secret rows, catalog filtering,
and non-sensitive activity details.
## Verification
- `pnpm -r typecheck` — passed across all workspaces before the
signed-capability follow-up; final targeted shared and server typechecks
also passed after it.
- `pnpm exec vitest run
server/src/services/paperclip-cloud-connector.test.ts` — passed, 9
tests.
- `pnpm exec vitest run packages/shared/src/app-definitions.test.ts` —
passed, 19 tests.
- `pnpm exec vitest run
server/src/__tests__/tool-access-service.test.ts` — passed, 205 tests.
- `pnpm test:run` — incomplete after the general server group reported
five failures in `server/src/__tests__/workspace-runtime.test.ts`. The
failures are outside the changed files. The run was stopped before the
remaining serialized suites because the shared worktree was needed for a
follow-up edit.
- `pnpm build` — passed on the final tree.
- `git diff --check` — passed on the final tree.
The five full-suite failures were:
- `records teardown and cleanup operations when a recorder is provided`
- `does not accept an occupied allocated port when listener ownership is
unavailable`
- `backfills a pre-existing HTTP-only managed worktree runtime to
verified HTTPS in place`
- `re-adopts a live service whose shell command differs from the
surviving process argv`
- `reuses a registered legacy worktree that already has the branch
checked out`
## Risks
- The default setup method changes when at least one Paperclip-managed
method is available. Explicit read, write, or draft choices still stay
within the selected capability group.
- Managed method availability now depends on Paperclip Cloud's signed
enrolled-instance status. A Cloud outage or an inactive enrollment hides
managed methods while leaving customer-owned OAuth available.
- The callback activity schema gains a non-sensitive `profile` value. It
does not include tokens, account identifiers, emails, tenant
identifiers, or provider error text.
- The profile invariant is strict. A future Google scope or tool change
must update the shared registry and the matching app definition
together.
- There are no database migrations and no public API changes.
> 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.6, with reasoning, repository tools, code
execution, and test execution. The effective context window was managed
by the Codex task runtime.
## 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
- [ ] 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The heartbeat runtime classifies adapter run failures, and the
recovery service uses that classification to decide between automatic
retry, a timed provider-quota wait, and a board escalation
> - The Claude CLI changed its subscription-limit stop message to
"You've hit your limit · resets 2:30am (UTC)", and no quota matcher
knows this qualifier-less wording
> - A limit-hit run therefore classifies as `adapter_failed` (or
`claude_auth_required`), recovery burns its continuation retries against
a hard limit, and the issue blocks with the opaque "No live execution
path" notice instead of waiting for the reset and retrying automatically
> - This pull request teaches the adapter and the recovery service the
new wording, and titles stranded-escalation notices from the classified
run error code so operators see the cause at a glance
> - The benefit is that usage-limit stops self-heal at the provider
reset time, and the notices that do post say "Error: usage limit
reached" or "Error: not logged in to Claude" instead of a generic title
## Linked Issues or Issue Description
No public issue exists; the underlying problem follows the bug template:
**What happened?**
On a staging deployment, an assigned `in_progress` issue hit the Claude
subscription usage limit. The run recorded the error `Claude run failed:
subtype=success: You've hit your limit · resets 2:30am (UTC)`. The
automatic continuation retry failed the same way in 34 seconds with
`errorCode: adapter_failed`. Terminal-run recovery then escalated: the
issue moved to `blocked` with the notice "No live execution path" and a
board-owned recovery action. The notice gave the operator no indication
that the cause was a usage limit with a known reset time.
**Expected behavior**
A usage-limit stop classifies as `provider_quota` with the reset clock
parsed into `retryNotBefore`. The recovery service takes its
provider-quota wait path: a system-owned recovery action that waits for
the reset time and retries the original assignee automatically. If an
escalation notice does post, its title names the classified cause.
**Steps to reproduce**
1. Run a `claude_local` agent on an issue until the Claude subscription
limit is hit, so the CLI result is "You've hit your limit · resets
\<time\> (UTC)".
2. Let terminal-run recovery retry the continuation.
3. Observe the issue block with the "No live execution path" notice
instead of a timed quota wait. `classifyAdapterFailureForRecovery`
returns `null` for the recorded error text; `CLAUDE_PROVIDER_QUOTA_RE`
and `PROVIDER_QUOTA_ERROR_RE` both fail to match it.
## What Changed
- `CLAUDE_PROVIDER_QUOTA_RE` and `CLAUDE_EXTRA_USAGE_RESET_RE`
(claude-local adapter) accept "you've hit your limit" with no qualifier,
alongside the existing "session"/"usage" wordings, so the run classifies
as `provider_quota` and the reset clock lands in `retryNotBefore`.
- `PROVIDER_QUOTA_ERROR_RE` and `isProviderQuotaRecovery` (recovery
service) accept the same wording, so runs recorded before the adapter
fix (errorCode `adapter_failed` with the limit text in the error) also
route to the quota wait.
- `parseProviderQuotaClockReset` parses the "resets 2:30am (UTC)" clock
shape alongside the existing "try again at" shape.
- `buildStrandedRecoveryEscalationNotice` titles the notice from the
source run's classified error code when one is mapped: `provider_quota`
→ "Error: usage limit reached", `claude_auth_required` → "Error: not
logged in to Claude", `acpx_auth_required` → "Error: agent login
required". The raw failure text stays withheld from the issue thread;
only the server-classified code is surfaced. Unmapped codes keep the
existing seed/cause titles.
## Verification
- `pnpm vitest run
packages/adapters/claude-local/src/server/parse.test.ts
server/src/services/recovery/provider-failure-classification.test.ts
server/src/services/recovery/stranded-notice.test.ts` — 72 tests pass,
including 5 new cases that use the exact new CLI message.
- `pnpm vitest run server/src/__tests__/issue-recovery-actions.test.ts
server/src/__tests__/heartbeat-retry-scheduling.test.ts
server/src/__tests__/heartbeat-process-recovery.test.ts` — 189 tests
pass (no reroute regressions from the widened matchers).
- `tsc --noEmit` clean for `@paperclipai/adapter-claude-local` and
`@paperclipai/server`.
## Risks
- Low risk. The regex widenings are additive; every previously matched
wording still matches, and the existing negative test ("Workspace
storage capacity limit reached." stays unclassified) still passes.
- Behavioral shift, intended: an `adapter_failed` run whose error text
is the new limit wording now routes to the silent system-owned quota
wait instead of a board escalation. This matches how the older limit
wordings already behave.
- The notice title change only affects escalations whose source run
carries one of the three mapped error codes; all other notices render
exactly as before.
## Model Used
Claude Fable 5 (`claude-fable-5`, Claude Code CLI, extended thinking
with tool use).
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package is useful only when the application can start,
observe, and recover a native Codex run safely.
> - Existing direct adapters must keep their current execution and
finalization paths.
> - The application boundary therefore needs additive persistence,
authorization, coordination, and recovery behind an explicit
experimental adapter.
> - This pull request adds that Codex-only boundary without activating
generalized providers, remote environments, or the later task/SDK
surfaces.
## Linked Issues or Issue Description
**Subsystem affected**
Shared contracts, database persistence, adapter utilities, server
native-runtime services, and the experimental Paperclip Runner adapter.
**Problem or motivation**
The already-landed runner package has a qualified Codex path, but the
application needs durable native-run state, guarded runtime selection,
authenticated coordination, tool security, finalization, and recovery
before the experimental adapter can be exercised safely.
**Proposed solution**
Add a Codex-only `paperclip_runner` application path behind the existing
default-off native-runner setting. Bind native state and coordination to
company/run identity, preserve persisted-run recovery, and leave every
direct adapter on its existing legacy execution path.
**Alternatives considered**
The earlier stack boundary introduced a generalized executor and
remote-environment lifecycle here. That made this PR depend on
implementations in higher PRs and changed reusable sandbox behavior
globally. Those pieces are now deferred together to #12592.
**Roadmap alignment**
ROADMAP.md does not list a conflicting native-runner integration
project. This change adds the application boundary for the existing
Runner architecture.
## What Changed
- Added native run/result/finalization/provider-trace persistence,
shared validators, and idempotent migration/replay coverage.
- Added guarded Codex-only runtime selection, authenticated PRP
coordination, recovery, finalization, and interaction services.
- Added run/company-bound tool-gateway authorization, credential
redaction, SSRF protections, and replay-safe behavior.
- Added the explicit `paperclip_runner` adapter behind the default-off
rollout setting.
- Preserved legacy answered-question wake projection and direct-adapter
execution/finalization paths.
- Hardened cancellation so only owned in-memory child processes are
signaled; persisted recycled PIDs/process groups are never trusted.
- Retained the narrow Claude ACPX isolated-context security follow-up
discovered after #12590.
- Deferred the generalized executor, provider ingress, remote lifecycle,
SDK/lab/eval work, release-process changes, and lockfile.
## Verification
- Changed-file delta against `master`: 133 files.
- GitHub Actions is the authoritative verification environment for this
PR.
- Full CI, security, and Greptile review will run on this lowest
unmerged stack PR.
- Local tests/build/typecheck were not run because this checkout is
resource constrained.
- Static diff/reference checks pass, and `pnpm-lock.yaml` is unchanged.
## Risks
- This touches central heartbeat and agent-route code, so legacy
compatibility is the primary risk.
- Runtime selection remains Codex-only and explicit; direct Codex,
Claude, OpenCode, process, HTTP, and plugin adapters remain on their
existing paths.
- Fresh native starts fail closed while the rollout flag is off;
persisted native records remain readable and recoverable.
- Cancellation, company/run binding, tool calls, status decisions, and
completion writes are guarded or replay-safe.
> 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.
## Model Used
OpenAI Codex, GPT-5.6, with repository tools, code execution, and
parallel agent review.
## 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 linked existing issues or described the issue in-PR
following the relevant issue template
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] I have run tests locally and they pass — GitHub Actions is
authoritative for this resource-constrained checkout
- [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 risks above
- [ ] All Paperclip CI and security gates are green
- [ ] Greptile is 5/5 with no open actionable findings
- [x] I will address all Greptile and reviewer comments before merge
## Stack
- Position: 3 of 5 overall; lowest of 3 currently unmerged
- Base: `master`
- Previous:
[#12590](https://github.com/paperclipai/paperclip/pull/12590), qualified
Claude ACPX runtime — merged
- Next: [#12592](https://github.com/paperclipai/paperclip/pull/12592),
generalized Codex executor, task experience, and developer SDKs
---------
Co-authored-by: Dev Agent <dev@paperclip.ing>
## Thinking Path
> - Paperclip lets operators give governed tools to AI agents.
> - Connected Apps already support provider OAuth and personal
connection grants.
> - Some providers require one stable callback and do not support
dynamic client registration.
> - Self-hosted Paperclip instances can run at private or changeable
origins.
> - Paperclip Cloud can provide the stable callback while each instance
keeps its durable provider credentials.
> - This pull request adds the instance side of that managed OAuth
protocol and keeps customer-created clients available.
> - The benefit is a safe path to one-click Workspace connections for
hosted and enrolled self-hosted instances.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting. This change updates the server, Apps UI, shared app
definitions, and connection documentation.
**Problem or motivation**
Some OAuth providers require a pre-registered callback and
provider-owned client. An arbitrary self-hosted Paperclip origin cannot
use that client callback directly. Paperclip ID must also stay limited
to product identity instead of resource authorization.
**Proposed solution**
Use the existing Paperclip Cloud application as the fixed callback
broker. Enroll each instance to an exact origin and separate Ed25519 and
X25519 keys. Bind every request and sealed envelope to the instance,
environment, user, company, provider, profile, and exact scope set.
Store durable provider credentials only in the originating instance
vault.
**Alternatives considered**
Customer-created OAuth clients remain available as the independent
fallback. A generic redirect relay was rejected because it would allow
caller-selected destinations and scopes. Paperclip ID was rejected as
the broker because it is the identity boundary. A new service was
rejected because the existing Cloud application already owns customer
login and the public callback origin.
**Roadmap alignment**
This work extends the shipped MCP Tool Gateway and Apps milestone. It
also supports the Connected Apps and Cloud deployments roadmap items.
Companion Cloud implementation:
https://github.com/paperclipai/paperclip-cloud/pull/312
The duplicate search found no related open Paperclip PR or issue.
## What Changed
- Add a `paperclip_cloud_connector` client with signed requests, exact
profile and scope bindings, and X25519-sealed credential handling.
- Add explicit self-hosted enrollment with owner-only instance key
storage and exact HTTPS origins.
- Route managed Google Workspace setup through Paperclip Cloud and
preserve customer-created OAuth clients.
- Keep broker claims retryable until the local vault transaction
commits.
- Keep managed Google per-profile removal local-only to avoid
client-wide provider revocation.
- Add setup status to the Connections page and retain the Paperclip ID
names as compatibility aliases.
- Document the trust boundaries, enrollment, callback, refresh, removal,
and rollout flows.
## Verification
- `pnpm -r typecheck`
- `pnpm --filter @paperclipai/shared exec vitest run
src/app-definitions.test.ts`
- `pnpm --filter @paperclipai/server exec vitest run
src/services/paperclip-cloud-connector.test.ts
src/services/paperclip-cloud-connector-enrollment.test.ts`
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/tool-access-service.test.ts -t 'brokered Gmail
OAuth|brokered OAuth state'`
- `pnpm --filter @paperclipai/ui exec vitest run
src/pages/apps/Connections.test.tsx`
- `pnpm check:token-gates`
- `pnpm build`
- The full stable test runner also reproduced existing macOS workspace,
skill-discovery, and listener fixture failures outside the changed
paths. GitHub Linux CI is the authoritative full-suite result.
## Risks
- The managed flow depends on
https://github.com/paperclipai/paperclip-cloud/pull/312. Real provider
profiles stay disabled until Cloud deploys that protocol and the
provider approves the managed client.
- A Cloud outage blocks new authorization and refresh. Existing access
tokens continue to work until expiry.
- Managed Google profile removal only deletes the local grant. This
avoids invalidating the user's other profiles that share the managed
Google client.
- Legacy `paperclip_id_connector` records require a reconnect after
their current access tokens expire. Old Paperclip ID keys and refresh
tokens are not sent to Paperclip Cloud.
> 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 GPT-5.6 (Codex). Agentic coding, tool use, code execution, and
subagents were enabled. The context-window size is not exposed in this
session.
## 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>
## Thinking Path
> - Paperclip Runner already has a hardened ACPX path for Codex.
> - Claude can reuse that protocol only with an exact package/model
profile and provider-lifetime fencing.
> - Pi needs a separately spawned runtime whose executable does not yet
have the descriptor-confined verified launch used by the ACP server.
> - This pull request therefore activates Claude only and keeps Pi
unavailable before installation or process launch.
## Linked Issues or Issue Description
**Subsystem affected**
Paperclip Runner ACPX driver, runtime host, sidecar, backend factory,
package dependency, and provider conformance tests.
**Problem or motivation**
The production ACPX backend was Codex-only. Claude needs the same
fail-closed model, authorization, cancellation, cleanup, and recovery
boundaries without exposing an unsafe secondary runtime path.
**Proposed solution**
Generalize the hardened ACPX runtime for the exact qualified `claude`
profile, add the pinned Claude ACP package and reviewed isolation patch,
and reject Pi before installation, backend construction, sidecar
initialization, Rust session admission, or process creation.
**Alternatives considered**
Activating Pi in this PR was rejected after security review because its
secondary runtime executable was pathname-based and lacked the verified
descriptor/snapshot boundary. Pi is deferred to a dedicated follow-up.
Replaying the older generic ACPX implementation was rejected because it
predates current hardening.
**Roadmap alignment**
ROADMAP.md does not list a conflicting ACPX-provider project. This
extends the existing Runner provider architecture.
## What Changed
- Generalized the ACPX backend, driver, runtime adapter, host, and
sidecar for the qualified Claude profile.
- Added Claude ACPX activation through its exact pinned package/model
pair and isolated-settings patch.
- Added provider-lifetime fencing for non-Codex qualified ACPX sessions.
- Kept Pi dependencies and its patch out of the package and build
configuration.
- Added fail-closed Pi rejection at driver validation, backend
construction, runtime-host admission, sidecar initialization, and Rust
session validation.
- Added focused tests for Claude selection, model enforcement, lifecycle
fencing, cancellation, recovery, and Pi rejection.
- Did not change or commit `pnpm-lock.yaml`; CI regenerates the PR
lockfile under the existing repository policy.
## Verification
- GitHub Actions is the authoritative verification environment for this
PR.
- CI runs dependency policy, runner package checks, protocol parity,
typecheck, build, security, and stack policy.
- Local tests were not run because this checkout is resource
constrained, per the requested workflow.
## Risks
- Claude package behavior can drift from the qualified protocol; the
package and patch are pinned and admission verifies the exact profile.
- Unsupported providers and models fail closed.
- Pi remains unavailable until descriptor-confined verified launch
exists for its separate runtime.
- Existing Codex ACPX behavior remains covered by shared conformance
tests.
> 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.
## Model Used
OpenAI Codex, GPT-5.6, with repository tools, code execution, and
parallel agent review.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used
- [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
- [x] I have described the issue in the PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name contains no internal task identifier
- [ ] I have run tests locally and they pass — GitHub Actions is
authoritative for this resource-constrained checkout
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation
- [x] I have considered and documented risks
- [ ] All applicable Paperclip CI gates are green
- [ ] Greptile is 5/5 with no actionable findings
## Stack
- Position: lowest unmerged PR
- Base: `master`
- Previous:
[#12588](https://github.com/paperclipai/paperclip/pull/12588), merged
qualified OpenCode runtime
- Next: [#12591](https://github.com/paperclipai/paperclip/pull/12591),
native application integration
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner provides a durable execution boundary for supported
providers.
> - The current production runtime supports Codex but cannot execute
OpenCode sessions.
> - OpenCode needs a qualified transport, strict input mapping, and
normalized events.
> - This pull request adds the OpenCode runtime as one isolated provider
unit.
> - The benefit is a reviewable provider expansion that does not weaken
the existing Codex path.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting: packages/paperclip-runner and the Codex-local adapter
configuration contract.
**Problem or motivation**
Paperclip Runner has provider-neutral contracts, but the production
backend factory cannot start a qualified OpenCode session. This blocks
OpenCode from using the durable runner path.
**Proposed solution**
Add the qualified OpenCode app-server proxy, driver, MCP bridge,
backend, fixtures, and factory wiring. Keep existing Codex behavior
unchanged.
**Alternatives considered**
Keeping OpenCode only on the direct adapter path would avoid this
runtime work, but it would not provide durable runner recovery or
normalized provider events.
**Roadmap alignment**
ROADMAP.md does not list a conflicting provider-runtime project. This
change extends the existing Paperclip Runner architecture.
## What Changed
- Added the qualified OpenCode app-server proxy and input queue.
- Added collaboration-mode and provider-event normalization.
- Added the OpenCode MCP bridge and native session backend.
- Added strict fixtures and focused unit coverage.
- Added only the package exports and adapter configuration required by
this runtime.
- Kept deferred SDK, lab, eval, and public package surfaces out of this
change.
## Verification
- GitHub Actions is the authoritative verification environment for this
PR.
- Run the package type checks and focused OpenCode tests in CI.
- Run repository typecheck, test, build, security, and policy gates
through the stack-aware workflow.
- Local tests were not run because this checkout is resource
constrained.
## Risks
- OpenCode protocol changes could affect event normalization or
recovery.
- The driver fails closed on malformed input and unsupported runtime
behavior.
- Existing Codex selection remains unchanged unless the stored provider
is OpenCode.
> 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.
## Model Used
OpenAI Codex, GPT-5.6, with repository tools, code execution, and
parallel agent review.
## 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 linked existing issues or described the issue in-PR
following the relevant issue template
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] I have run tests locally and they pass — GitHub Actions is
authoritative for this resource-constrained checkout
- [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
## Stack
- Position: 1 of 4
- Base: master
- Next: additional qualified provider runtimes
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust ACPX session can now suspend only at a safe idle boundary
and its events have a durable projection
> - A later runner process cannot safely resume from an unbound or
partially written identity record
> - The recovery anchor must bind the exact provider identity, run,
normalized session, catalog revision, and catalog digest
> - The record must be bounded, private, strict about schema drift, and
atomically replaceable
> - Recovery must re-admit the entire prospective session configuration
before releasing the stored identity
> - This pull request adds only that package-local checkpoint store
without selecting ACPX in runnerd
## Linked Issues or Issue Description
Refs #12424
Refs #12422
## What Changed
- Add a versioned ACPX safe-suspension checkpoint contract with unknown
fields rejected at every persisted level.
- Bind each checkpoint to the run, normalized session, catalog revision,
catalog digest, and exact provider identity.
- Persist a checkpoint-specific strict identity that requires the pinned
permission mode without narrowing the additive live sidecar identity
wire shape.
- Construct checkpoints only from a session configuration whose model,
permission policy, tool catalog, and expected identity validate.
- Admit recovery only when reconstructing the checkpoint from the
prospective configuration produces an exact match.
- Reject run, session, catalog revision, catalog digest, model,
permission, expected-identity, profile, and workspace drift fail closed.
- Require persisted run/session IDs to satisfy the same stable-ID
boundary as fresh session admission.
- Store the checkpoint under a dedicated private runner-state
subdirectory.
- Bound checkpoint files to 1 MiB before reading or decoding.
- Refuse symlinked state directories and non-private or non-regular
checkpoint files.
- Replace checkpoints atomically through a private temporary file and
directory sync.
- Make repeated saves of the same checkpoint idempotent.
- Add integration coverage for private round trips, complete recovery
admission, malformed/oversized files, nested schema drift, missing
permission binding, invalid stable IDs, and symlink denial.
- Document the package-local suspension recovery boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `1ee738cf487defe88043b241c4e2dc34a1a8a7bc` (`master`
after #12424 merged).
- Exact replay head: `89cfea5495428be890810d2b8a27673943234ca3`.
- Stable patch ID: `dbaeb0bbe773f1ca5ef1f9bdc0fa61f4a08ca451`.
- The exact delta is 4 files and 591 additions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, dependency, or migration change.
- `git diff --check` and the Cargo formatting check pass on the replayed
delta.
- Exact-head GitHub Actions run `33374006661` (attempt 2): **PASSED**
with 23/23 jobs passed.
- Greptile reviewed exact head
`89cfea5495428be890810d2b8a27673943234ca3`: **5/5**, with zero
unresolved review threads.
- Superagent, contributor trust, Socket, and Snyk security checks:
**PASSED**.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- A checkpoint is valid only after the sidecar has confirmed safe
suspension. The constructor therefore accepts the exact identity
returned by that operation and revalidates it against local authority.
- Loading proves only that the file is structurally valid;
`admit_recovery` is the boundary that proves the file belongs to the
prospective run, catalog, model, permission policy, and expected
provider identity.
- The checkpoint intentionally contains no credentials, bootstrap
ticket, provider output, or pending request payload.
- Strict checkpoint schema and identity validation rejects incompatible
or tampered recovery records rather than attempting partial migration.
This strictness is checkpoint-local and does not narrow existing PRP or
sidecar wire compatibility.
- Atomic replacement uses the platform `rename` primitive; Unix
additionally syncs the private parent directory before reporting
success.
- No production path loads this checkpoint in this pull request. Runnerd
execution and durable recovery wiring remain a later slice.
> 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 with GPT-5.6, 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 linked the preceding public PRs or described the issue
in-PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now owns validated, scoped ACPX reducer events and
safe session suspension
> - Durable PRP transport must receive provider-neutral events rather
than sidecar-native envelopes
> - Semantic calls and questions must retain the exact run, session,
turn, item, and provider-request authority used by the durable command
stream
> - Terminal, result, assistant, process, and diagnostic events also
need one reviewed projection boundary
> - Permission requests remain impossible under the pinned Codex policy
and must fail closed if they reach projection
> - This pull request adds only that package-local projection without
selecting ACPX in runnerd
## Linked Issues or Issue Description
Refs #12422
## What Changed
- Add a validated durable ACPX event projection context bound to one
run, normalized session, turn, and item.
- Pass already normalized activity events through without reintroducing
provider-native envelopes.
- Project authorized tool calls into canonical semantic input receipts
with exact correlation and content digests.
- Project structured questions into provider-neutral
`paperclip.runtime_request.v2` events.
- Preserve both the public projected request identity and the original
provider request identity so responses resolve the exact sidecar
request.
- Project dynamic semantic operation results as `semantic_tool.result`;
only reserved finish/block operations may propose the run result.
- Project semantic completion results into `run.result.proposed`.
- Project terminal-flushed assistant messages on the final channel and
turn terminal states into existing provider-neutral event families.
- Project sanitized process metadata and diagnostics into bounded
harness diagnostics.
- Validate runtime-request origins against their strict durable shape
and fall back from empty optional titles to a valid question prompt.
- Reject invalid identities, projected-identity collisions, unstable
semantic receipt identities, permission requests, and cross-turn
projection fail closed.
- Add integration coverage across reducer event families, correlation,
identity validation, projected question resolution, and pinned-policy
denial.
- Document the durable projection boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `80639f4f69c8938eb74bdc0833df93e0ed91dab3` (`master`
after #12422 merged).
- Exact replay head: `3cb29581d2bcbc4b47f8069baffd721c6ce4e444`.
- Stable patch ID: `92910b56575e67ae83960177d467a565019ba282`.
- The exact delta is 22 files, 1,206 additions, and 59 deletions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, dependency, or migration change.
- `git diff --check` and the Cargo formatting check pass on the replayed
delta.
- Exact-head GitHub Actions run `33372209037` (attempt 2): **PASSED**
with 23/23 jobs passed.
- Greptile reviewed exact head
`3cb29581d2bcbc4b47f8069baffd721c6ce4e444`: **5/5**, with zero
unresolved review threads.
- Superagent, contributor trust, Socket, and Snyk security checks:
**PASSED**.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- This function accepts reducer output, not raw sidecar frames. Callers
must preserve the existing scope-first decode and reduction order.
- Semantic input includes the already sanitized provider input while its
content receipt uses the same canonical digest.
- Structured input preserves the validated provider-neutral question set
and sanitized origin.
- Noncanonical provider request identities are deterministically
projected for PRP while the original identity remains authoritative for
the sidecar resolution command.
- Existing PRP v1 identifiers remain schema-compatible; the only public
ID-schema change widens turn/item limits from 160 to 240 characters. The
internal ACPX sidecar wire schema now mirrors the stable IDs its Rust
transport already enforced.
- The projector verifies event-carried terminal and assistant turn
identifiers against the durable context.
- No production path invokes this projector in this pull request.
Durable command execution remains the next slice.
> 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 with GPT-5.6, 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 linked the preceding public PR or described the issue in-PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now owns exact ACPX request resolution and
fail-closed session state
> - A recoverable provider session needs an explicit suspension boundary
before runnerd can safely hand work across process lifetimes
> - Suspension is unsafe while a turn or provider request is active
because remote effects may still be in flight
> - A successful acknowledgement must preserve the exact immutable
session identity
> - This pull request adds only that guarded package-local lifecycle
operation without selecting ACPX in runnerd
> - The benefit is a small recovery primitive whose safety rules are
independently reviewable
## Linked Issues or Issue Description
Refs #12421
## What Changed
- Add a provider-state query for active pending tool, input, or
permission requests.
- Permit session suspension only when no turn or provider request is
active.
- Send a bounded `session.suspend` command with an operator-safe reason.
- Require an affirmative suspension acknowledgement and the exact
existing session identity.
- Treat transport failure, rejection, omitted or malformed identity, and
identity drift as fail-closed terminal errors.
- Mark a successfully suspended session closed and terminate the local
sidecar process while retaining cleanup ownership if termination must be
retried.
- Preserve a valid session after purely local unsafe-state rejection so
it can settle before retry.
- Extend the fake sidecar with deterministic suspension success,
acknowledgement mismatch, identity mismatch, and missing-identity modes.
- Add integration coverage for safe suspension, active-turn rejection,
fail-closed remote mismatches, and retained cleanup.
- Document the package-local suspension boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `91d861ff69d415a3b105ae2eaad9cc56c66a9231` (`master`
after #12421 merged).
- Exact replay head: `085667e10c51c6c0360732f63c8fef83e806dd88`.
- Stable patch ID: `b18d6b7efd1de569d3068b0a782f8aac2fbc9322`; this is
the prepared suspension delta plus the focused fake-sidecar fix that
consolidates mismatch modes into the existing command arm.
- The exact delta is 5 files, 136 additions, and 5 deletions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, or migration change.
- Exact-head GitHub Actions run `33369571343` (attempt 1): **PASSED**
with 23 jobs passed and zero failures.
- Greptile reviewed exact head
`085667e10c51c6c0360732f63c8fef83e806dd88`: **5/5**, with zero
unresolved review threads.
- Superagent, contributor trust, Socket, and Snyk security checks:
**PASSED**.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- The sidecar may apply suspension before a transport failure is
observed. The local session closes rather than retrying an ambiguous
effect.
- Local active-work rejection happens before transport and leaves the
valid session open so the caller can settle it safely.
- Identity equality is checked across provider, driver, session, thread,
run, and company fields before accepting suspension.
- No production path invokes suspension in this pull request. Runnerd
execution and durable recovery wiring remain later slices.
> 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 with GPT-5.6, 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 linked existing issues with `Refs #` or described
the issue in-PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now owns a scoped ACPX turn and validates provider
requests before exposing them
> - A live turn can pause for semantic tool results or structured input
> - Local state and the sidecar can diverge if the runner clears a
request before the sidecar accepts its resolution
> - A mismatched or ambiguous remote acknowledgement must close the
session, while a local validation error must preserve the request for a
safe retry
> - This pull request adds those two-phase resolution paths and rejects
Codex permission events that bypass the pinned policy without selecting
ACPX in runnerd
> - The benefit is an atomic request boundary that can be wired into
durable execution in a later slice
## Linked Issues or Issue Description
Refs #12420
Refs #12419
## What Changed
- Resolve authorized semantic tool calls only for the active turn and
exact pending operation.
- Validate semantic results against the authorized response schema
before transport.
- Send a bounded generic provider error when a semantic operation fails
without exposing internal error text or payloads.
- Resolve structured input only after validating the exact persisted
question set.
- Support explicit submit, decline, and cancel input outcomes.
- Reject any Codex permission event that bypasses the pinned sidecar
policy.
- Build candidate provider and authorization state before each request.
- Commit candidate state only after the sidecar returns an affirmative
resolution acknowledgement.
- Preserve pending work after local validation errors so the caller can
retry safely.
- Terminate the session after transport failure or an invalid remote
acknowledgement because the remote effect is ambiguous.
- Bind every resolution to the exact active turn and request or call
identity.
- Extend the fake sidecar and add integration coverage for successful
commits, safe local retries, pinned-policy enforcement, redaction, and
fail-closed acknowledgement mismatch.
- Document the package-local resolution boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `3aa2065d084d6a29492aaa15e822b5d17c3a4266` (`master`
after #12420 merged).
- Exact replay head: `9507024f70c6f434c2c322385d3a9e240250b03c`.
- Stable patch ID: `a4f27d2fae606596f70b5b1c2b29dd7f250541d8`, identical
to the prepared two-commit delta.
- The exact delta is 5 files, 463 additions, and 7 deletions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, or migration change.
- GitHub Actions run `33368135190`, attempt 2: **PASSED** on the exact
replay head (23/23 jobs passed; a failed-job-only retry cleared one
unrelated server test environment failure where `npm` was unavailable).
- Greptile: **5/5** on the exact replay head with zero unresolved review
threads; Superagent, Socket, Snyk, and contributor-trust checks also
passed.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- A transport failure can happen after the sidecar applied a resolution.
The session closes instead of retrying an ambiguous effect.
- Local validation happens before transport and preserves pending state,
so a corrected answer or result can be retried.
- The sidecar transport already correlates each command response to its
request identifier. This slice also requires `resolved: true` before
local commit.
- The initial Codex sidecar owns its pinned permission policy and does
not delegate permission resolution. Any permission event therefore
terminates the session fail closed.
- No production path invokes these methods in this pull request. Durable
ACPX execution wiring remains a later slice.
> 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 with GPT-5.6, 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 or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now owns a bounded ACPX session and a fail-closed
turn lifecycle
> - Provider questions pause a turn and must return structured answers
to the same persisted question set
> - JSON Schema validates the wire shape, but it cannot validate
identifiers and constraints across two documents
> - Unknown questions, invalid choices, and malformed custom answers
must fail before any provider receives them
> - This pull request adds only the package-local response validator and
tests
> - The benefit is a small trust boundary that later request-resolution
code can use without changing production selection
## Linked Issues or Issue Description
Refs #12419
## What Changed
- Validate `paperclip.question_response.v1` against its versioned JSON
Schema.
- Bound serialized responses to 768 KiB before validation.
- Require answer identifiers to match the exact persisted question set.
- Require answers for required questions and reject unknown question
identifiers.
- Enforce text, single-select, and multi-select answer modes.
- Match the existing TypeScript numeric syntax, including decimal,
exponent, hexadecimal, octal, and binary input.
- Match ECMAScript trimming exactly, including BOM whitespace while
rejecting Unicode NEL rather than inheriting Rust-specific whitespace
behavior.
- Enforce known options, custom-answer policy, text length, pattern, and
numeric constraints.
- Validate duplicate option IDs, inverted bounds, and dynamic patterns
before answer lookup so malformed optional questions fail closed even
when unanswered.
- Match JavaScript UTF-16 code-unit length semantics for text
constraints and the 100,000-unit response-field bound.
- Preserve the public optional `recommended` question-option field in
the versioned schema, generated schema bundle, and Rust validation path.
- Return typed validation errors for malformed inputs without panics.
- Export the validator from the Rust runner core.
- Add table-driven tests for valid, mismatched, malformed, oversized,
and numeric-boundary responses.
- Document the package-local structured-response boundary.
- Add `num-bigint` 0.4 and `num-traits` 0.2 as direct runner-core
dependencies for exact arbitrary-length radix parsing and one-step
JavaScript Number rounding; update only the package-local runner Cargo
lockfile.
- Do not change the repository PNPM lockfile, workflows, runnerd
selection, server behavior, UI, or migrations.
## Verification
- Replay base: `9a9fdf06ee4142f77427db30efccc4c43056f64b` (`master`
after #12419 merged).
- Exact replay head: `fad92b3fb348b66ddb10dde44b7b060e55c4fe96`.
- Stable patch ID: `4d6ffbd519dd081f7ea530977cd965bd4569fc75`; this is
the prepared two-commit delta plus the focused cross-language parity fix
found during replay review.
- The exact delta is 10 files, 712 additions, and 2 deletions, all in
`packages/paperclip-runner`.
- The package-local `packages/paperclip-runner/runner/Cargo.lock`
records the two direct runner-core dependencies; their already-resolved
versions and checksums are unchanged.
- The question-set schema source, generated TypeScript schema bundle,
and protocol manifest hash are updated together; the schema SHA-256 is
`42b5441a3d388851dacb6e4500dfd4a17d878eded2e724228078b647e7440d3f`.
- GitHub Actions run `33366812025`, attempt 2: **PASSED** on the exact
replay head (23/23 jobs passed; a failed-job-only retry cleared one
unrelated ACPX runtime-host timeout).
- Greptile: **5/5** on the exact replay head with zero unresolved review
threads; Superagent, Socket, Snyk, and contributor-trust checks also
passed.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- The validator compiles the embedded response schema for each
submission. Responses are user-paced and bounded, so this keeps the
slice simple without affecting a hot event path.
- The persisted question set is the source of truth for identifiers and
constraints. A malformed persisted set fails closed.
- Numeric input follows the existing structured-question contract,
including JavaScript-prefixed syntax. Optional whitespace-only answers
are rejected instead of being treated as an omitted value.
- Error messages identify the invalid field but do not include answer
text.
- No production path invokes this validator in this pull request.
Request resolution remains the next slice.
> 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 with GPT-5.6, 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 or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now validates and opens an exact Codex ACPX session
and attaches one run/catalog identity
> - A live session must start one turn, preserve immutable workspace
authority, accept interruption, and consume provider events
> - Command acknowledgements and event scope are trust boundaries;
disagreement must terminate the session rather than permit divergent
state
> - The existing reducer already owns bounded state, ordering,
correlation, and terminal cleanup
> - This pull request connects turn commands and polling only to that
reviewed reducer without selecting ACPX in runnerd
> - The benefit is a fail-closed execution loop before semantic request
resolution and production selection are added
## Linked Issues or Issue Description
Refs #12418
Refs #12417
## What Changed
- Start one ACPX turn only after validating a bounded turn identifier,
bounded message, and the session's immutable working directory.
- Require `turn.start` to acknowledge the exact requested turn before
mutating provider state.
- Request interruption only for the active turn and require an
affirmative cancellation acknowledgement.
- Keep the turn active until the authoritative terminal event is polled
and reduced.
- Poll bounded sidecar events and route every event through the existing
scope-first payload/state boundary.
- Terminate the sidecar fail closed after a rejected or mismatched turn
command, transport failure, or invalid scoped event.
- Preserve ordinary local validation failures without mutating or
closing an otherwise valid session.
- Admit semantic tool calls through the run-scoped authorized tool
bridge before returning them to runnerd.
- Reduce events and authorize tool calls on candidate clones, then
commit both together only after every check passes.
- Rotate and scope tool receipts by run and turn; reserve pending,
completed, and settled call IDs across both tool bridges so cross-bridge
duplicates cannot be re-admitted.
- Preserve exact turn correlation through payload, scope, provider
state, fake sidecar, and integration fixtures.
- Extend the package-local fake sidecar with deterministic turn
activity, terminal, acknowledgement-mismatch, and scope-violation modes.
- Add integration coverage for happy-path
activity/interruption/settlement, local validation, turn mismatch,
cancellation mismatch, cross-run denial, receipt rotation, and
cross-bridge call-ID reuse.
- Document the turn lifecycle boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `10cf68295d5457ccf1010db20a06e2951e47162a` (`master`
after #12418 merged).
- Exact replay head: `1ec18368bdacafafa58720b9e2b982e1b0d11163`.
- Stable patch ID: `4b43a5ef2a428850a05b0741d06e7cf4f48ec334`, identical
to the prepared four-commit delta plus the focused cross-bridge call-ID
reservation fix.
- The exact delta is 13 files, 1,855 additions, and 37 deletions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, or migration change.
- GitHub Actions run `33364033038`, attempt 2: **PASSED** on the exact
replay head (23/23 jobs passed; the failed-job-only retry cleared one
unrelated flaky server heartbeat test).
- Greptile: **5/5** on the exact replay head with zero unresolved review
threads; Superagent, Socket, and Snyk checks also passed.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- A sidecar may emit events while a command response is in flight. The
transport buffers them, then the session binds the acknowledged turn
before polling and reducing those events.
- A turn-start rejection can leave provider-native state ambiguous, so
command rejection or acknowledgement mismatch terminates the session
instead of attempting unsafe reuse.
- Interruption does not settle local state; only the validated terminal
event clears the active turn.
- Any transport or event validation failure terminates the child process
so a compromised stream cannot continue.
- Call identifiers are authorization identities and remain reserved
across pending, completed, and settled states in both bridges.
- The package exposes new Rust methods, but no production path invokes
them in this pull request.
- Tool authorization is atomic with reducer state, but tool results,
structured input, and permission resolution remain later slices.
> 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 with GPT-5.6, 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now has bounded ACPX transport, scope, payload,
normalization, and state-reduction layers
> - A live provider needs a lifecycle owner that starts the sidecar and
proves it opened the exact requested session
> - The initial production slice is Codex-only and must fail closed on
capability, model, identity, policy, or catalog drift
> - Failed bootstraps must not leak a child process, and ordinary
shutdown must preserve resumable provider state
> - This pull request adds that package-local lifecycle without
selecting ACPX in runnerd
> - The benefit is a reviewable bootstrap/recovery boundary before turn
commands and production selection are connected
## Linked Issues or Issue Description
Refs #12417
Refs #12416
## What Changed
- Add a package-local ACPX provider session configuration and lifecycle
owner.
- Reject non-UTF-8 runtime and working directories before spawning so
JSON path serialization cannot panic.
- Validate the sidecar launch contract, Codex-only agent, model, run and
session identifiers, absolute directories, positive JSON-safe catalog
revision, pinned permission mode, bounded instructions, and canonical
authorized tool catalog before spawning.
- Verify the initialization protocol version, child PID,
persistent-session support, exact-model support, runner-owned permission
policy, semantic-tool bridge, and structured-input contract.
- Open an identity-bound session and require the requested and effective
models, permission mode, session identifier, digests, and optional
recovery identity to match exactly.
- Attach the run and require the sidecar to confirm the exact run
identifier and catalog revision.
- Retry failed transport cleanup while retaining lifecycle ownership;
terminate the sidecar after every failed bootstrap and on an unclosed
session drop.
- Close sessions without discarding persistent state and make explicit
shutdown idempotent.
- Extend the package-local fake sidecar with deterministic bootstrap,
wrong-model, and wrong-run responses.
- Add five integration tests covering successful bootstrap/shutdown,
pre-spawn policy validation, model mismatch, run mismatch, and recovery
identity matching.
- Document the session bootstrap boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `f038633bf5b04163ff985ef0542876bd9f455379` (`master`
after #12417 merged).
- Exact replay head: `a6d9ad62f20fdb47a1dbc76aa4baa9d8fa6dae53`.
- Stable patch ID: `82b6f2551749598a688c3f44a1a3714516030429`, identical
to the reviewed `e6e550f9..d51a8855` delta.
- The exact delta is 5 files and 609 additions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, or migration change.
- Focused Rust lifecycle, package, repository, security, and Greptile
checks: **PASSED** on the replayed exact head. Full CI run `33362799786`
is green; its failed-job retry passed one unrelated flaky server shard
without a patch change. Greptile is exact-head 5/5, all security checks
pass, and no review threads remain unresolved.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- This lifecycle owns a child process and session identity.
Configuration is fully validated before spawning, every bootstrap
response is checked against the child PID and requested identity, and
failed bootstrap always terminates the process.
- Recovery identity matching is exact so a persisted native record
cannot silently attach to another session, model, workspace, profile, or
permission policy.
- Explicit shutdown preserves persistent provider state; a dropped
unclosed session still terminates its process group as a safety
fallback.
- The package exports a new Rust module, but no production path
constructs it in this pull request.
- Turn commands, event polling, request resolution, and runnerd
selection remain later slices.
> 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 with GPT-5.6, 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now has bounded ACPX transport, scope, payload, and
provider-neutral normalization layers
> - A live provider still needs state across events to correlate
requests and preserve turn ordering
> - That state must not mutate before scope and payload validation
succeeds
> - It must bound retained text and pending values, suppress repeated
reasoning boundaries, and make one semantic result authoritative
> - This pull request adds that reducer without issuing process commands
or selecting ACPX in runnerd
> - The benefit is a separately reviewable state machine before
transport commands and production selection are connected
## Linked Issues or Issue Description
Refs #12416
Refs #12415
## What Changed
- Add a package-local ACPX provider state reducer with one run binding
and one active turn.
- Decode every sidecar event through the existing scope-first payload
boundary before state mutation.
- Bound retained assistant text, pending semantic tool inputs, and
pending runtime request values.
- Correlate semantic tool calls, structured input requests, and
permission requests by stable IDs.
- Keep pending tool resolution two-phase so callers remove state only
after a later sidecar command succeeds.
- Carry authoritative tool classification from validated payloads into
retained state.
- Suppress repeated reasoning-start activity within one turn.
- Accept one semantic result idempotently and fail closed on a
conflicting result.
- Flush the final assistant message before the authoritative terminal
event.
- Clear unresolved turn-scoped requests at terminal state and reject
late events for the settled turn.
- Admit redacted global process and diagnostic events without requiring
an active turn.
- Add seven integration tests for turn ordering, correlation, conflicts,
scope-before-mutation, redaction, and terminal cleanup.
- Document the state boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `7bb6cebeae727a16c205bb80b5c2b9e92ea6b5fa` (`master`
after #12416 merged).
- Exact replay head: `da82e7f67ecd6f0f2184f303b1b703721099cd86`.
- Stable patch ID: `3027df409450d08b2c32383585597a39e06c6f53`, identical
to the reviewed `f9cb4e54..e6e550f9` delta.
- The exact delta is 4 files and 720 additions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, or migration change.
- Focused Rust state, package, repository, security, and Greptile
checks: **PASSED** on the replayed exact head. Full CI run `33362166929`
completed successfully, Greptile is exact-head 5/5, all security checks
pass, and no review threads remain unresolved.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- This reducer owns security-sensitive correlation and terminal
ordering, so its only raw-event entry point always invokes scope-first
decoding.
- Pending resolution methods must be called only after the corresponding
sidecar transport command succeeds; the later process adapter owns that
sequencing.
- Terminal events intentionally clear unresolved turn-scoped requests so
late tool or input results fail closed.
- One semantic result remains readable after terminal state for later
durable finalization and is cleared only when a new turn begins.
- The package exports a new Rust module, but no production path
constructs it in this pull request.
> 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 with GPT-5.6, 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now admits ACPX sidecar frames only after transport,
scope, and payload validation
> - Valid payloads still contain provider-native runtime event shapes
> - Provider-native shapes must not cross the PRP boundary or diverge
from direct Codex task activity
> - This pull request maps the display-safe runtime subset into existing
provider-neutral event families
> - Stateful semantic-result, terminal, and reasoning-deduplication
behavior remains reserved for the later provider adapter
> - The benefit is a reviewable normalization boundary without selecting
ACPX in production
## Linked Issues or Issue Description
Refs #12415
Refs #12414
## What Changed
- Normalize validated ACPX text, reasoning, plan, status, tool, notice,
and error updates into existing PRP activity families.
- Keep reasoning contents private while preserving a reasoning activity
boundary.
- Map plan entries, usage, review-mode status, and tool lifecycle into
bounded canonical payloads.
- Generate one shared ACPX sidecar event/classification contract for
TypeScript and Rust, with ASCII-only classification parity and bounded
kind/title fields.
- Preserve authoritative tool-call identity and classification even when
the aggregate native event exceeds the generic frame budget.
- Resolve display-only tool targets within the workspace under the
provider host's path semantics; reject raw, unmarked, absolute,
parent-traversing, URL-shaped, and unsafe drive-shaped values.
- Redact and digest retained tool output with the existing durable
policy.
- Ignore provider inventory status updates that have no user-facing
activity.
- Leave semantic results and `done` updates to the stateful adapter so
durable receipts and terminal events are not duplicated.
- Add cross-language and Rust coverage for every mapping family,
classifier parity, privacy, unsafe paths, redaction, bounded
titles/kinds, and oversized tool-call preservation.
- Document the normalization and display-path authorization boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `fe2ddfad2b5cb604b3244492257db0e6aec11d47` (`master`
after #12415 merged).
- Exact replay head: `b7f5588bf6e8e0f946ffa8869a3204c344808418`.
- Stable patch ID: `fda62c7c20afc5ef9c75d07f163a466db82efabd`, identical
to the prepared six-commit delta plus the focused oversized-tool-call
review fix.
- The exact delta is 14 files, 1,714 additions, and 60 deletions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, or migration change.
- Focused protocol-generation, TypeScript sidecar, Rust normalization,
package, repository, security, and Greptile checks: **PASSED** on the
replayed exact head. Full CI run `33361437835` completed 23/23 jobs
successfully, Greptile is exact-head 5/5, all security checks pass, and
no review threads remain unresolved.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- This code controls what provider activity is retained and displayed,
so malformed native values must not bypass the earlier decoder.
- The function contract requires an already scope-checked and
payload-validated runtime event; the future adapter must preserve that
order.
- Tool classification and identity are security-relevant authorization
inputs and remain explicit even when optional aggregate display data is
dropped for bounds.
- Repeated reasoning chunks require stateful suppression. This mapper
exposes a privacy-safe start boundary and the later adapter owns
per-turn deduplication.
- Semantic results and terminal authority intentionally produce no
activity here; the later adapter must commit them through the durable
operational paths.
- The package exports new generated and Rust normalization surfaces, but
no production path invokes them in this pull request.
> 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 with GPT-5.6, 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The runner needs a bounded process boundary for each qualified
provider runtime
> - The ACPX transport now verifies frame shape, sequence, run scope,
and turn scope
> - The sidecar schema keeps event payloads open so each event family
needs a second validation boundary
> - A later provider adapter must not retain or act on malformed payload
fields
> - This pull request validates and redacts package-local payloads and
keeps the provider unselected
> - The benefit is a typed fail-closed boundary before provider state or
semantic tools can consume an event
## Linked Issues or Issue Description
Refs #12414
Refs #12412
## What Changed
- Decode sidecar payloads only after run and turn scope validation
passes.
- Limit each decoded payload to 256 KiB.
- Add typed payload variants for runtime events, permission requests,
input requests, semantic tool calls, terminal events, process events,
and diagnostics.
- Admit only the nine runtime event shapes emitted by the reviewed Codex
ACPX sidecar.
- Validate runtime text, plan entries, tool locations, semantic result
identities, notices, errors, and terminal status values.
- Validate input requests against `paperclip.question_set.v1`.
- Reject duplicate question IDs and duplicate option IDs within one
question.
- Require bounded control identities and object-shaped operational
values.
- Redact diagnostic, error, process, permission, tool, and retained
runtime values before they can enter provider state.
- Add six integration tests for every admitted shape, malformed values,
scope-before-decode ordering, size limits, question ambiguity, and
secret redaction.
- Document the payload boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `3db24d9366831559b1219782475e760ec041b639` (`master`
after #12414 merged).
- Exact replay head: `de045b42b5b52cca6c3021380747c56693ccd179`.
- Stable patch ID: `90a6f0ed68b2ca7fa5397a8bf93e5e95df5bb58c`, identical
to the reviewed `972a3b38..9bb85e93` delta.
- The exact delta is 4 files and 806 additions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, or migration change.
- Focused Rust payload, package, repository, security, and Greptile
checks: **PASSED** on the replayed exact head. Full CI run `33360832792`
completed 23/23 jobs successfully, Greptile is exact-head 5/5, all
security checks pass, and no review threads remain unresolved.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- This decoder is a security boundary because later code can act on
decoded semantic tool calls and input requests.
- It validates event authority before it inspects a payload.
- It fails closed on unknown runtime event types, malformed fields,
ambiguous question identifiers, unsupported terminal states, and
oversized payloads.
- It applies the existing durable redaction policy to retained values.
- The package exports a new Rust module, but no production path
constructs it in this pull request.
- A later provider adapter must preserve this validation order and must
not consume raw sidecar payloads directly.
> 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 with GPT-5.6, 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The runner needs a bounded process boundary for each qualified
provider runtime
> - The package now has a fail-closed transport for the Codex ACPX
sidecar
> - A valid sidecar frame can still name the wrong run or turn
> - A later provider adapter must reject those events before it maps or
persists them
> - This pull request adds package-local run and turn scope validation
and keeps it unselected
> - The benefit is an explicit authorization boundary without a
production behavior change
## Linked Issues or Issue Description
Refs #12412
Refs #12410
## What Changed
- Add an `AcpxEventScope` for one run and at most one active turn.
- Validate run and turn identifiers before they enter scope state.
- Make repeated binding of the same turn safe.
- Reject a second active turn and a stale turn clear.
- Require exact run and active turn bindings for operational, tool,
input, permission, and terminal events.
- Permit process and diagnostic events without a scope because they can
describe the sidecar process itself.
- Validate every optional run or turn binding on process and diagnostic
events.
- Add an integration-test file for all seven event families, missing
scope, cross-run scope, cross-turn scope, inactive turns, turn
lifecycle, and invalid identifiers.
- Document the event authorization boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `75708fec6d421a247ba2fc832997de24ed10a085` (`master`
after #12412 merged).
- Exact replay head: `88bb248442b8f628c20e977d2c2dbc21d85fb6dd`.
- Stable patch ID: `0b6443b1bc32ed244f650936026367dd84bcfd65`, identical
to the reviewed `c5654218..972a3b38` delta.
- The exact delta is 4 files and 280 additions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, or migration change.
- Focused Rust scope, package, repository, security, and Greptile
checks: **PASSED** on the replayed exact head. Full CI run `33360199404`
completed successfully, Greptile is exact-head 5/5, all security checks
pass, and no review threads remain unresolved.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- Event scope is a security boundary because it rejects data from
another run or turn.
- The validator fails closed on missing, malformed, stale, or
cross-scope identifiers.
- Process and diagnostic events can remain global, but any scope they
provide must be valid.
- The package exports a new Rust module, but no production path
constructs it in this pull request.
- A later provider adapter must bind and clear the exact turn around
each sidecar turn.
> 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 with GPT-5.6, 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The runner needs a bounded process boundary for each qualified
provider runtime
> - The package now provides a reviewed Codex-only ACPX sidecar
executable
> - Runnerd does not yet have a strict client for that sidecar protocol
> - A later provider adapter must not mix process transport defects with
provider mapping
> - This pull request adds the package-local Rust transport and keeps it
unselected
> - The benefit is a tested fail-closed boundary for the later Codex
provider adapter without a production behavior change
## Linked Issues or Issue Description
Refs #12410
Refs #12386
## What Changed
- Add a Rust client for the generated ACPX sidecar v2 contract.
- Validate the executable path, launch arguments, request timeout, and
shutdown grace before process start.
- Require exact request identities and contiguous event sequence
numbers.
- Reject replayed events, sequence gaps, wrong response identities,
malformed frames, unknown fields, and unsupported protocol versions.
- Bound stdout frames to 1 MiB and buffered events to 512 entries.
- Bound event poll timeouts to 120 seconds before any `Instant`
arithmetic.
- Buffer valid events that arrive while a command waits for its
response.
- Treat an empty event poll as a normal timeout without poisoning the
transport.
- Discard retained events and reject all polling after a terminal
transport failure.
- Terminate the process group after a timeout, transport failure, or
protocol failure.
- Keep a valid sidecar command rejection separate from a transport
failure so the next command can run.
- Redact and bound stderr diagnostics before they enter an error.
- Add a deterministic fake sidecar and twelve integration tests for
success, polling, timeout bounds, poisoned queues, replay, gaps,
identity mismatch, rejection, event floods, oversized frames, and secret
redaction.
- Document that the transport remains package-local and does not change
runnerd provider selection.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `9ad8dbffa0a4759dcda2769042d6e8f02adcdf8d` (`master`
after #12410 merged).
- Exact replay head: `5c41111c4f9564405a6e87a02b6cf253a4424e5f`.
- Stable patch ID: `60aca2620fdbb73fbbc203e928d39dcd450e085b`; this
preserves the reviewed `1334a7f5..c5654218` six-file delta and keeps
trusted bounded-reader failures distinct from fully redacted child
stderr.
- The exact delta is 6 files and 896 additions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, or migration change.
- Focused Rust transport, package, repository, security, and Greptile
checks: **PASSED** on the replayed exact head. Full CI run `33359202433`
is green; its failed-job retry passed the two unrelated flaky jobs
without a patch change. Greptile is exact-head 5/5, all security checks
pass, and no review threads remain unresolved.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- The transport crosses an untrusted process boundary and is
security-sensitive.
- It fails closed on malformed frames, identity drift, event replay,
sequence gaps, queue overflow, frame overflow, timeout, process exit,
and channel failure.
- A terminal failure clears retained events before it marks the
transport unavailable.
- It redacts and bounds retained diagnostics before it returns them to a
caller.
- A valid remote command rejection does not corrupt the transport state.
- The package exports a new Rust module, but no production path
constructs it in this pull request.
- The later provider adapter must validate run, turn, session, model,
and tool bindings before it selects this transport.
> 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 with GPT-5.6, 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner needs a bounded process boundary for each qualified
provider runtime.
> - The ACPX contract, Codex profile, structured questions, and recovery
rules now exist in the package.
> - The package does not yet provide an executable that applies those
rules to a real Codex ACPX host.
> - Provider admission must retain process, credential, and cleanup
ownership on every failure path.
> - A production selector must not depend on an unreviewed
provider-generic sidecar.
> - This pull request adds one installable Codex-only ACPX sidecar and
leaves it unselected.
> - The benefit is a testable package boundary for later runnerd
integration without changing current execution selection.
## Linked Issues or Issue Description
Refs #12409
Refs #12386
This pull request implements the Codex-only executable for the ACPX
sidecar contract merged in #12386. It builds on the question conformance
gate merged in #12409. Runnerd and the server do not select this
executable in this pull request.
## What Changed
- Publish the `paperclip-runner-acpx-sidecar` package binary and
document its current boundary.
- Add a versioned stdin/stdout sidecar that admits only the qualified
Codex ACPX profile and exact initialized model.
- Support atomic session open, run attachment, turn start and
cancellation, tool and input resolution, session read and snapshot, safe
suspension, close, and recovery identity checks.
- Bind runtime directory, workspace, permission mode, provider identity,
run identity, and semantic tool catalog before use.
- Validate completion and blocked results against the PRP result
contract. Bound pending tools, pending inputs, messages, events, usage,
diagnostics, and errors.
- Redact provider output and convert file locations to bounded
workspace-relative display data. Do not treat displayed paths as
file-access authority.
- Harden verified executable loading, module resolution, launch
environment filtering, process-group guardianship, and provider
termination.
- Retain managed credentials and every failed-admission resource until
the exact provider cleanup proves ownership was released.
- Keep failed-admission cleanup alive with bounded backoff until the
provider exits. Do not scrub credentials or admit a replacement while
cleanup still owns the provider.
- Use one runtime-host cleanup-owner registry and preserve sequential
cleanup retries across command timeouts and shutdown.
- Arm a credential-free same-group watchdog before provider admission so
guardian death reaps even a stopped provider; retain an independent
kernel EOF proof before releasing credentials.
- Add sidecar process, lifecycle, location, package, driver, credential,
installation, runtime-adapter, and runtime-host regression tests.
- Add `tsx` as a package test-only development dependency for the real
TypeScript sidecar process test.
## Verification
- Replay base: `b93ad538b63c81a1e3d24bbb54c02f8effdea787` (`master`
after #12409 merged).
- Exact replay head: `ca7e93f4385c37289c82b360ca8def0d88c1bd00`.
- Stable patch ID for the resolved 18-file delta:
`d293717a1e9f2485b61c553c58ea37690fc0a4fa`.
- The intended pull request delta contains exactly these 18 files:
- `packages/paperclip-runner/README.md`
- `packages/paperclip-runner/package.json`
- `packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts`
- `packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts`
- `packages/paperclip-runner/src/cli/acpx-sidecar-lifecycle.ts`
- `packages/paperclip-runner/src/cli/acpx-sidecar-locations.ts`
- `packages/paperclip-runner/src/cli/acpx-sidecar-locations.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-credentials.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-credentials.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts`
-
`packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts`
-
`packages/paperclip-runner/src/drivers/acpx/installation-integrity.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts`
- `packages/paperclip-runner/test/acpx-codex-package-contract.test.mjs`
- The resolved combined delta is 4,725 additions and 665 deletions; it
preserves the lower-PR runtime-close semantics, repairs stale
successful-admission fixtures, deterministically observes renewed
reconciliation, accepts authoritative same-host cleanup recovery without
dropping pending owners, ignores superseded cleanup failures after a
newer owner recovers, and requires both guardian exit and independent
provider-lifetime EOF before releasing cleanup or credential ownership.
A readiness-gated, credential-free watchdog also reaps a stopped
provider if its guardian is externally killed.
- This change updates the runner package manifest, README, and test-only
dependencies. It does not change `pnpm-lock.yaml`, a workflow,
migration, server route, UI path, runnerd selection, or current
direct-adapter behavior.
- Focused GitHub verification: **PASSED** for the sidecar process,
lifecycle, location, package-contract, driver, credential,
installation-integrity, runtime-adapter, and runtime-host suites on the
replayed head.
- Package verification: **PASSED** for the clean tarball, Node shebang,
and exact binary mapping on the replayed head.
- GitHub Actions and security checks: **PASSED** for the replayed exact
head; full CI run `33357846557` completed 23/23 jobs successfully, and
Superagent, Socket, Snyk, supply-chain, and contributor-trust checks are
green. Storybook was intentionally skipped because this PR does not
touch its paths.
- Greptile: **5/5** on the exact head with zero unresolved review
threads.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for the replayed revision.
## Risks
This change has medium security and lifecycle risk because the new
executable crosses a process, credential, filesystem, and provider
boundary. The sidecar fails closed on unsupported providers, models,
permissions, identities, catalogs, forms, commands, and persistent-state
deletion. A cleanup owner can remain alive until a stubborn provider
exits. Its retries use bounded backoff, and admission stays closed while
ownership remains. Command and shutdown waits remain bounded without
abandoning the underlying cleanup. The new `tsx` dependency is
development-only. The package exposes a new binary, but no runnerd,
server, UI, or direct-adapter path starts it in this pull request.
> 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 with GPT-5.6, extended reasoning, repository 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner maps provider questions to one versioned Paperclip
contract.
> - Codex and ACPX now perform that mapping through separate adapters.
> - Separate adapter tests do not prove that both paths preserve the
same user-visible form.
> - Fixture validation must also match production behavior for optional
answers and unsupported patterns.
> - This pull request adds shared fixtures, validation, and
cross-adapter conformance checks.
> - The benefit is a reusable question contract for later providers
without enabling a new runtime.
## Linked Issues or Issue Description
Refs #12408
This pull request builds on the Codex ACPX question bridge merged in
#12408. It adds fixture and generator checks for the existing Codex and
ACPX question adapters. It does not add another provider or production
execution path.
## What Changed
- Add a canonical ACPX form fixture and native response. Mark the
equivalent Codex fixture field as required.
- Add shared validation for question IDs, option IDs, answer modes,
required answers, text bounds, numeric bounds, and response shapes.
- Evaluate fixture-only regular expressions in a bounded child process.
Reject patterns that cannot finish safely.
- Validate ACPX fixtures against a manifest-side mirror of the
production form projection. Reject free-text ACPX patterns, but ignore
patterns on enumerated option fields.
- Accept explicit empty optional answers and omit them from the
projected ACPX response, which matches the production parser.
- Validate every question fixture during manifest generation and
regenerate the checked-in manifest.
- Add cross-adapter tests that compare user-visible presentation while
preserving provider-owned IDs and provider-specific response conversion.
- Add negative regressions for malformed forms, invalid responses,
unsafe patterns, special property names, and projection drift.
## Verification
- Replay base: `4fe3189f0256873a359d2d53c209076919fd1c3b` (`master`
after #12408 merged).
- Exact replay head: `0532e7dfbb5a246033ffeef55a0c0013fdab07f1`.
- Stable patch ID for the intended seven-file delta:
`28154d86b2c37e0e8d442419e26703584852f67e`.
- The intended pull request delta contains exactly these seven files:
- `packages/paperclip-runner/protocol/fixtures/questions/acpx.json`
- `packages/paperclip-runner/protocol/fixtures/questions/codex.json`
- `packages/paperclip-runner/protocol/manifest.json`
- `packages/paperclip-runner/scripts/generate-protocol-manifest.mjs`
- `packages/paperclip-runner/scripts/protocol-contract.mjs`
-
`packages/paperclip-runner/src/contracts/question-adapter-conformance.test.ts`
- `packages/paperclip-runner/test/protocol-contract.test.mjs`
- The intended combined delta is 1,211 additions and 20 deletions.
- This change does not add a dependency, lockfile update, migration,
workflow, server route, UI change, documentation file, or production
runtime change.
- GitHub Actions run `33352004952` passed the complete matrix on retry
at the unchanged exact head, including protocol/package verification,
build, typecheck/release-registry, general and serialized server suites,
canary, and all e2e shards.
- Superagent, Socket, Snyk, contributor-trust, policy, and PR-review
checks pass on the exact replay head.
- Greptile reviewed the exact replay head at 5/5 with no blocking
finding and zero unresolved review threads.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for the replayed revision.
## Risks
This change has low runtime risk because it changes fixtures, generator
validation, generated metadata, and tests only. Fixture pattern checks
run in a child process with a one-second timeout and a bounded output
buffer. The ACPX gate intentionally rejects free-text patterns because
the production adapter has no bounded expression engine. It
intentionally permits an explicit empty optional answer because
production omits that answer from the native response. A validation
mismatch can block manifest generation, but it cannot change server
selection, direct adapters, or task-page behavior.
> 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 with GPT-5.6, extended reasoning, repository 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
- [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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package gives provider sessions one normalized execution
contract.
> - The merged Codex ACPX path can run and recover settled turns.
> - It cannot yet send a structured provider question through the
existing Paperclip question boundary.
> - Provider questions must not expose ACPX-specific data to later
server integrations.
> - Every pending provider request must also settle on resolution,
handoff, cancellation, failure, or close.
> - This pull request adds a bounded Codex ACPX form bridge inside the
runner package.
> - The benefit is a provider-neutral question flow with fail-closed
lifecycle handling.
## Linked Issues or Issue Description
Refs #12407
This pull request builds on the settled Codex ACPX recovery path merged
in #12407. It adds only package-local structured-question support for
Codex ACPX sessions.
## What Changed
- Enable ACPX form elicitation for the Codex runtime and pass its
handler through the runtime host boundary.
- Normalize ACPX forms to `paperclip.question_set.v1` and emit
`paperclip.runtime_request.v2` events.
- Validate `paperclip.question_response.v1` resolutions before
conversion to ACP form responses.
- Support explicit resolution and durable handoff. Cancel pending
requests on provider abort, stream failure, turn settlement, and session
close.
- Limit each session to 16 pending requests. Reject unsupported input
modes, regular expression patterns, session-wide acceptance, stale
turns, and late responses.
- Fail closed under bounded event-queue pressure: cancel an input whose
creation event cannot be retained, and preserve a live request when its
durable-handoff event cannot be retained.
- Persist pending-request facts in snapshots and reject recovery while a
provider request is still pending.
- Add focused driver, runtime-adapter, and runtime-host regression tests
for round trips, aborts, stream failures, handoff, and handler
forwarding.
## Verification
- Replay base: `96421b0663d8b740ac5d5d53359aef65c5a158ca` (`master`
after #12407 merged).
- Exact replay head: `d8184502e1c4570d1003379365850f3419f64d82`.
- Stable patch ID for the exact replay delta:
`00807ebfcd1b153f759366db023437b681d69017`.
- The pull request delta contains exactly these six files:
- `packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts`
-
`packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts`
- The exact combined delta is 716 additions and 14 deletions.
- This change does not add a dependency, lockfile update, migration,
workflow, server route, UI change, documentation file, or public package
export.
- GitHub Actions run `33351323368` passed the full matrix on the exact
replay head, including Paperclip Runner verification, build,
typecheck/release-registry, general and serialized server suites,
canary, and all e2e shards.
- Superagent, Socket, Snyk, contributor-trust, policy, and PR-review
checks pass on the exact replay head.
- Greptile reviewed the exact replay head at 5/5 with no blocking
finding and zero review threads.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for the replayed revision.
## Risks
This change has medium package-local risk because it connects
provider-owned input to durable runner state. Unsupported modes and
unbounded patterns fail closed. The pending-request limit bounds
retained provider state. Provider abort, turn settlement, stream
failure, and session close cancel live questions. A durable handoff
expires the request before it interrupts the turn. Recovery rejects a
snapshot that still contains a pending provider request. Existing direct
adapters, server selection, and task-page behavior do not use this
route.
> 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 with GPT-5.6, extended reasoning, repository 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
- [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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package keeps provider sessions durable across process
restarts.
> - The merged Codex ACPX backend can admit a new qualified session
through the package factory.
> - It cannot yet recover a settled session from a durable checkpoint.
> - Recovery must prove the same provider identity, runtime root,
workspace, and latest terminal settlement before it resumes.
> - ACPX cannot yet prove continuity for a provider turn that was active
when the process stopped.
> - This pull request recovers only settled Codex ACPX checkpoints and
rejects ambiguous or stale state.
> - The benefit is fail-closed restart recovery without repeated work,
silent session replacement, or recovery of an older semantic result.
## Linked Issues or Issue Description
Refs #12406
This pull request builds on the Codex ACPX backend route merged in
#12406. It adds only settled-session recovery and the package-local
durability and filesystem checks that recovery requires.
## What Changed
- Add settled-session recovery to the Codex ACPX harness driver and
advertise resume support for that bounded path.
- Keep provider recovery on the same persisted ACPX session. Do not
permit a replacement provider session.
- Require persisted run, normalized session, provider, profile,
workspace, permission, result, terminal, and recovery-policy identities
to agree.
- Reopen the provider with the exact persisted ACPX identity and reject
provider or qualification drift.
- Restore the last source sequence, terminal history, semantic result,
provider recovery policy, and normalized terminal fact before new work
can start.
- Clear a stale active-turn marker only when durable terminal history
proves that exact turn settled.
- Reject active-turn recovery when durable history cannot prove
provider-turn continuity.
- Require a semantic result to belong to the latest completed terminal
settlement.
- Reject an older completed semantic result when a later identical retry
failed or was interrupted.
- Reject resultless recovery unless the latest terminal turn completed
successfully.
- Bound terminal history and semantic-result recovery by entry count,
aggregate bytes, fingerprint bytes, node count, and nesting depth before
cloning or serializing persisted data.
- Read the private workspace record through pinned namespace,
runtime-root, record, and workspace identities.
- Reject symbolic links, substituted directories, replaced records,
invalid files, root workspaces, and workspace changes during admission.
- Keep the recovery workspace lease pinned and revalidate it at the host
and provider-spawn boundaries.
- Retain and close a workspace lease that resolves after cancellation.
Close a partially recovered provider session if lease cleanup fails.
- Stage a valid isolated Codex credential in the runtime-open-boundary
regression so the test reaches and proves the intended workspace
revalidation fence.
- Add focused recovery tests for settled checkpoints, terminal
ownership, stale semantic results, active turns, identity drift, bounded
persisted data, cancellation, directory substitution, record
replacement, and spawn-boundary workspace replacement.
## Verification
- Replay base: `30ef14edd4e7290d9eac43ca7b7835611933cc74` (`master`
after #12406 merged).
- Exact replay head: `3d1b16d5cda2dd72f83785c921a025cc57aab8d6`.
- Stable patch ID for the exact replay delta:
`10742d7db00f801b5723e7a8582c637261ceb0dd`. The source-stack combined
patch was `4d7c9de72a0a30f6e33c935c092b745fe414c588`; the replay
preserves the newer unconditional provider process-group containment
from `master` while adding recovery workspace revalidation before spawn,
plus the exact-head credential fixture correction exposed by GitHub
Actions.
- The exact pull request delta contains exactly 14 files:
- `packages/paperclip-runner/src/backends/harness-driver-backend.ts`
-
`packages/paperclip-runner/src/backends/harness-driver-backend.test.ts`
-
`packages/paperclip-runner/src/backends/native-backend-factory.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts`
-
`packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/recovery-identity.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-sandbox.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-sandbox.test.ts`
- `packages/paperclip-runner/src/native-session-runtime.ts`
- `packages/paperclip-runner/src/native-session-runtime.test.ts`
- The exact combined delta is 2,279 additions and 73 deletions.
- This delta does not change dependencies, `pnpm-lock.yaml`, workspace
configuration, workflows, migrations, server selection, UI behavior, or
public package exports.
- Focused GitHub recovery tests: **PASS**. The exact-head Build job
passed the harness backend, native runtime, Codex ACPX driver, runtime
host, runtime sandbox, runtime adapter, and backend factory suites as
part of all 751 TypeScript runner tests.
- GitHub Actions: **PASS** for exact head
`3d1b16d5cda2dd72f83785c921a025cc57aab8d6`. Every applicable job passed.
The Storybook visual regression skipped intentionally because this
package-only delta does not touch UI or Storybook paths.
- Security checks: **PASS** for the exact head. Superagent, Snyk, both
Socket checks, and contributor trust completed successfully.
- Greptile: **5/5** for the exact head, with no open P1/P2 findings,
recommendations, or follow-ups.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for the replayed revision.
## Risks
This change has medium package-local risk because it admits persisted
state back into a provider session. Recovery fails closed when an active
provider turn has no matching terminal fingerprint, when a semantic
result is not owned by the latest completed settlement, when any durable
identity changes, or when the workspace cannot remain pinned through
provider spawn. Recovery never selects a replacement provider session.
Bounds prevent oversized or deeply nested persisted state from consuming
unbounded work before validation. The workspace lease prevents path
substitution during recovery admission. Existing direct adapters and the
Codex app-server driver do not use this ACPX recovery route. This change
does not add a migration, dependency, lockfile update, workflow, server
route, UI surface, public export, or production rollout flag.
> 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 with GPT-5.6, extended reasoning, repository 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 (e.g. `docs/...`) and contains
no internal Paperclip ticket id or instance-derived details
- [ ] 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
- [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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package gives provider runtimes one normalized session
boundary.
> - The merged Codex ACPX driver implements that boundary and keeps its
cleanup ownership bounded.
> - The package backend factory still needs a narrow route from a
persisted Codex ACPX execution input to that qualified driver.
> - The route must validate the stored qualification snapshot and reject
unsupported providers before runtime admission.
> - This pull request wires only the qualified Codex ACPX driver into
the package-local backend factory.
> - The benefit is a fail-closed backend construction path without
enabling a server adapter, changing execution selection, or adding
another provider.
## Linked Issues or Issue Description
Refs #12405
This pull request builds on the Codex ACPX harness driver merged in
#12405. It adds only the package-local backend factory route for that
driver.
## What Changed
- Add an internal Codex ACPX native backend constructor.
- Require provider kind `acpx` and agent `codex` at the
provider-specific boundary.
- Resolve the qualified Codex ACPX profile for the requested model.
- Compare the persisted driver kind, protocol version, ACPX version,
agent profile, package versions, runtime package fields, and command
digest with the qualified profile.
- Compose the existing native system instructions and task constraints
for the Codex ACPX driver.
- Route qualified Codex ACPX inputs through the native backend factory
only when the caller supplies an explicit instance runtime directory.
- Pass the scoped environment, managed credential source, dynamic tools,
and ACPX tool handler through the factory boundary.
- Keep Pi, Claude, OpenCode, managed Claude, AgentCore, and every other
deferred ACPX agent unavailable.
- Add factory tests for qualified construction, the explicit
runtime-root requirement, unsupported ACPX agents, and
qualification-snapshot drift.
- Keep ACPX construction lazy. Reading the backend descriptor does not
start ACPX transport or a provider process.
## Verification
- Replay base: `74aabb7ea6c5cf373f2254e5f854a5233b745ddc` (`master`
after #12405 merged).
- Exact replay head: `827090a0cff870eedb99fa1b5cfda8bb87efa515`.
- Stable patch ID for the exact replay delta:
`e0f6733a5a124a4fb93155257358b966c354a176` (identical to the original
narrow source patch).
- The exact pull request delta contains exactly three files:
- `packages/paperclip-runner/src/backends/codex-acpx-native-backend.ts`
- `packages/paperclip-runner/src/backends/native-backend-factory.ts`
-
`packages/paperclip-runner/src/backends/native-backend-factory.test.ts`
- The exact source delta is 193 additions and 10 deletions.
- This delta does not change dependencies, `pnpm-lock.yaml`, workspace
configuration, workflows, migrations, server selection, UI behavior, or
public package exports.
- Focused GitHub test coverage: **PASS**. The exact-head Build job
passed all six native backend factory tests and all 720 TypeScript
runner tests.
- GitHub Actions: **PASS** for exact head
`827090a0cff870eedb99fa1b5cfda8bb87efa515`. Every applicable job passed.
Failed-job-only reruns cleared unrelated database timeout and server
concurrency flakes without changing the patch. The Storybook visual
regression skipped intentionally because this backend-only delta does
not touch UI or Storybook paths.
- Security checks: **PASS** for the exact head. Superagent, Snyk, both
Socket checks, and contributor trust completed successfully.
- Greptile: **5/5** for the exact head, with no open P1/P2 findings,
recommendations, or follow-ups.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for the replayed revision.
## Risks
This change has low package-local runtime risk. It adds a new branch to
the native backend factory, but no server or runnerd factory selects an
ACPX execution in this pull request. The route fails closed when the
runtime directory is absent, the agent is not Codex, or the persisted
qualification snapshot differs from the qualified Codex profile. The
constructor repeats the provider-kind and agent checks as a second
boundary. Existing direct adapters do not use this route. The change
does not add a migration, dependency, lockfile update, workflow, UI
surface, public export, or production rollout flag.
> 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 with GPT-5.6, extended reasoning, repository 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 (e.g. `docs/...`) and contains
no internal Paperclip ticket id or instance-derived details
- [ ] 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P1/P2 findings, recommendations, or
follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package hides provider behavior behind the
`HarnessDriver` contract.
> - The admitted Codex ACPX runtime can open sessions, execute bounded
turns, and use run-scoped semantic tools.
> - The package still needs a driver that translates those turns into
canonical PRP events and semantic results.
> - The driver must preserve terminal facts under backpressure and
retain cleanup ownership after caller-facing timeouts.
> - Abort can win after the host transfers a credential-bearing
admission but before the adapter body starts, so that boundary must
publish a completed cleanup proof without changing the exact
cancellation reason.
> - An external close can join an autonomous reconciliation attempt; if
it joins the exhausted final attempt, its batched intent must create one
new bounded generation when that exact cleanup fails.
> - A late cleanup failure needs a finite reconciliation budget that
cannot renew itself without a distinct external intent.
> - This pull request adds the Codex-only ACPX harness driver and the
package-local lifecycle rules it needs.
> - The benefit is a tested provider-neutral session boundary for later
runnerd and server integration.
## Linked Issues or Issue Description
Refs #12404
**Subsystem affected**
This change affects `packages/paperclip-runner`, the Codex ACPX driver,
and the provider-neutral native session runtime.
**Problem or motivation**
The package has an admitted Codex ACPX session, bounded turn control,
and authenticated semantic tools. It does not have a `HarnessDriver`
implementation that joins those parts and emits canonical PRP events. It
also needs bounded ownership for provider cleanup that settles after a
caller-facing timeout. Cancellation can win after the host schedules
runtime admission and transfers the staged credential but before the
adapter body starts; that rejected admission must still prove that
provider cleanup is complete so the credential can be scrubbed and later
admission can proceed. Separately, an external close that coalesces onto
an exhausted autonomous reconciliation must not lose its cleanup intent
if that exact protocol or provider-process cleanup fails.
**Proposed solution**
Add a Codex-only harness driver. It opens the admitted host, executes
one active turn, normalizes ACPX events, dispatches run-scoped tools,
and commits one schema-valid completion or blocked result. It provides
bounded event storage, interruption, transcripts, usage, snapshots,
diagnostics, and ordered close behavior. The native session runtime
quarantines incomplete cleanup before another session can enter the same
cleanup domain. The ACPX adapter records the immutable origin and
attempt number of each exact close attempt. Autonomous reconciliation
failures stay inside the three-attempt budget of the generation that
created them. External callers that join an attempt are represented by
one idempotent batched intent: success consumes it, failure on an
earlier attempt uses the remaining same-generation retries, and failure
on the exhausted final attempt creates exactly one new bounded
generation. Both direct and late protocol/provider cleanup outcomes use
the same rule. At the adapter entry boundary, an already-aborted
admission transfers an already-complete cleanup proof before rethrowing
the exact abort reason; the host retains credential cleanup until that
proof settles.
**Alternatives considered**
The multi-provider integration driver was not copied because it mixes
deferred providers and recovery behavior into the Codex path. Direct
server registration was also deferred because this package slice must
remain inactive and independently safe. Relabeling a coalesced
autonomous attempt as external was rejected because it would let
observers replenish retry budgets; starting another protocol close
before the exact retained attempt settles was rejected because it would
overlap cleanup ownership.
**Roadmap alignment**
This is package-local production hardening for the experimental runner.
It does not enable a new adapter or change current agent execution
selection.
## What Changed
- Add a Codex-only ACPX `HarnessDriver` and session implementation.
- Advertise only implemented capabilities. Keep resume, steering,
runtime request resolution, runtime request handoff, goals, and thread
lineage unavailable.
- Emit canonical PRP turn, transcript, tool execution, final reply,
result, failure, interruption, and usage facts.
- Dispatch authorized dynamic tools through the authenticated semantic
bridge.
- Validate and commit one completion or blocked result with disposition
and conflict checks.
- Add stable bounded event identities, one-active-turn admission,
terminal capacity reservation, and bounded interruption.
- Redact authorization credentials from emitted events and retained
transcripts.
- Add read, reconcile, transcript, usage, snapshot, status,
interruption, and ordered close surfaces.
- Retain and quarantine host cleanup that outlives a caller-facing close
bound.
- Gate new native-session admission on prior cleanup in the same cleanup
domain.
- Preserve durable success and governed waits while provider cleanup
continues under bounded ownership.
- Transfer a completed cleanup proof when cancellation wins before the
Codex adapter body, then preserve the caller's exact abort reason.
- Add a host-level regression proving staged credentials are scrubbed,
the credential lease can be reacquired, and a later runtime admission
succeeds after that pre-entry abort.
- Tag each exact ACPX close attempt with an immutable external or
reconciliation origin and immutable reconciliation attempt number.
- Keep timed-out autonomous reconciliation failures inside their
originating three-attempt budget.
- Batch concurrent external callers that join one reconciliation attempt
so they cannot mint independent generations.
- Consume a joined external intent on successful cleanup and on an
earlier failed attempt that still has same-generation retries.
- Renew exactly one bounded generation when a joined external intent
reaches a failed, exhausted final reconciliation attempt.
- Treat both protocol-close and provider-process cleanup failures as
failed intent settlement, including non-timeout and timed-out late
paths.
- Prevent a coalescing external observer from relabeling an immutable
autonomous attempt.
- Reset the finite reconciliation budget only for a distinct external
late-failure generation or one failed batched intent on an exhausted
final attempt.
- Isolate persistent-cleanup tests by cleanup domain and attach expected
rejection handlers before fake timers release them.
- Stabilize cleanup-settlement assertions exposed by GitHub Actions:
observe retained proofs without relying on callback order, wait for the
credential lease release rather than only the preceding credential-file
deletion, and use a supported scalar size assertion instead of an
unavailable Set matcher.
- Add focused tests for driver behavior, event validation, bounded
buffers, cleanup quarantine, admission gating, immutable attempt
origins, final-attempt intent batching, direct and late cleanup
failures, late success consumption, bounded reconciliation, exact
pre-entry cancellation, credential recovery, and durable native-session
outcomes.
## Verification
- Exact head: `584cc420f6ca249cdc0a831779192ca827764d96`.
- Stable patch ID for the combined exact delta:
`5329d8123baf62c339a15bdff16717b3803ebb74`.
- Stack position: #12404 is merged. This pull request targets `master`.
#12406 is stacked on this pull request.
- The exact pull request delta contains eight files:
- `packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts`
-
`packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts`
- `packages/paperclip-runner/src/native-session-runtime.ts`
- `packages/paperclip-runner/src/native-session-runtime.test.ts`
- `git diff --check` passed for the exact eight-file delta.
- This delta does not change dependencies, `pnpm-lock.yaml`, workflows,
migrations, server selection, UI behavior, or production runner wiring.
- GitHub previously exposed an unsupported Set matcher in the
cleanup-settlement regression; this exact delta uses the
repository-supported scalar `size` assertion without changing the tested
behavior.
- GitHub Actions: **PASS** for the exact head. The complete matrix is
green after a failed-job-only rerun cleared one unrelated
`plugin-worker-manager-duplex` flake; no patch or restack occurred.
- Security checks: **PASS** for the exact head (Superagent, Snyk,
Socket, and contributor trust).
- Greptile: **PASS, 5/5** on the exact head with no open P1/P2 findings,
recommendations, or follow-ups.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this revision.
## Risks
This change has medium package-local risk. It adds a new driver and
changes native-session cleanup coordination. A lagging event consumer
could otherwise lose terminal state. The driver reserves terminal
capacity and rejects new work when bounded storage cannot safely accept
it. A stalled, rejected, or late provider close could otherwise overlap
a new session, retain credentials indefinitely, lose an external cleanup
request, or consume unlimited retries. Cleanup-proof transfer keeps the
staged credential owned across the pre-entry abort race, while the host
scrubs it only after the adapter proves that no provider resource
exists. Cleanup quarantine blocks conflicting admission and keeps exact
attempts owned. Immutable attempt origins and attempt numbers prevent
autonomous retries and coalesced observers from silently replenishing
the cap. One batched external intent can renew one generation only after
the exhausted final attempt fails; earlier failures remain within the
original generation, and success consumes the intent. Each renewed
generation remains capped at three autonomous attempts. The driver
reports recovery and other unimplemented capabilities as unavailable. No
server or runnerd factory selects this driver in this pull request.
> 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. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex with GPT-5.6, extended reasoning, repository 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 (e.g. `docs/...`) and contains
no internal Paperclip ticket id or instance-derived details
- [ ] 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P1/P2 findings, recommendations, or
follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package provides a provider-neutral execution boundary.
> - The admitted Codex ACPX runtime needs access to the run-scoped
semantic tool catalog.
> - The tool endpoint contains an authentication secret and must stay
outside durable session state.
> - ACPX permission requests must follow the same run policy as semantic
tool authorization.
> - The deny-all mode must reject every request, including requests for
runner-owned MCP tools.
> - This pull request composes the authenticated loopback bridge into
the admitted Codex runtime.
> - The benefit is a closed tool catalog with fail-closed permissions
and bounded cleanup.
## Linked Issues or Issue Description
Refs #12403
**Subsystem affected**
This change affects `packages/paperclip-runner` and its package-local
Codex ACPX runtime boundary.
**Problem or motivation**
The package has an authenticated semantic MCP bridge and an admitted
Codex ACPX session. The two components are not connected. A direct
connection must not persist the bridge token. It must not allow
unrelated MCP operations. The deny-all mode must remain closed for
runner-owned MCP requests.
**Proposed solution**
The runtime host starts one loopback bridge when semantic tools are
configured. It passes an ephemeral bearer binding to ACPX. The adapter
projects that binding into the ACP runtime configuration. It sends each
permission request through the existing ACPX permission policy. The
deny-all mode rejects every request. Other requests either receive the
policy result or delegate to an available coordinator.
**Alternatives considered**
Persisting MCP configuration with the ACPX session was rejected because
it would retain authentication material. A global MCP endpoint was
rejected because it would weaken run isolation.
**Roadmap alignment**
This is package-local hardening for the existing experimental runner
work. It does not enable a new user-facing adapter.
## What Changed
- Start and own one authenticated semantic MCP bridge when a host
receives semantic tool options.
- Pass one ephemeral loopback MCP binding to the Codex ACPX adapter.
- Keep the bridge token out of the persisted environment and ACPX
session options.
- Map the runner-owned HTTP MCP binding into ACPX runtime configuration
with a bearer header.
- Apply the existing ACPX permission policy to runtime permission
requests.
- Keep the deny-all mode closed for runner-owned MCP requests.
- Delegate only the permission decisions that require a coordinator.
- Revoke the tool bridge after the runtime close attempt settles,
including when runtime close fails.
- Release staged credentials only after the exact runtime close
succeeds.
- Add focused host and adapter tests for bridge dispatch, secret
isolation, fail-closed permissions, delegation, and cleanup.
## Verification
- Exact head: `8ec3bec234beb56dfe744099ff9a45109fc583bc`.
- Stack position: #12403 is merged. This pull request targets `master`.
#12405 is stacked on this pull request.
- The exact pull request delta contains four files:
- `packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts`
-
`packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts`
- `git diff --check` passed for the exact four-file delta.
- This delta does not change dependencies, `pnpm-lock.yaml`, workflows,
migrations, server selection, UI behavior, or production runner wiring.
- GitHub Actions: **PASS** for the exact head, including policy, build,
typecheck/release, server, workspace, serialized-server, canary, and e2e
lanes. An unrelated fixed-port `EADDRINUSE` failure in
`loopback-listener.test.ts` passed on the targeted GitHub rerun without
a patch change.
- Security checks: **PASS** for the exact head, including Superagent,
Snyk, contributor trust, and Socket.
- Greptile: **5/5** for the exact head with no open P2s,
recommendations, follow-ups, or review threads.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this revision.
## Risks
The main risk is secret or permission leakage at the ACP boundary. The
host passes the bearer token only in ephemeral runtime configuration. It
does not put the token in the persisted environment or ACPX session
options. The existing permission policy controls every ACPX permission
request. The deny-all mode rejects runner-owned MCP requests too.
Another risk is partial cleanup. The host revokes the tool bridge after
the runtime close attempt settles. It retains staged credentials if the
exact runtime close fails. This pull request stays inside the runner
package and does not select the experimental runner in the server.
> 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. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex with GPT-5.6, extended reasoning, repository 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 (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] 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
- [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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The admitted Codex ACPX runtime can open and recover a verified
session.
> - It cannot yet accept a provider prompt through the narrow host port.
> - Turn admission must bound durable identity and prompt payloads.
> - Shutdown must cancel an active turn and release runtime resources in
a bounded way.
> - A cancellation timeout must not leave the runtime, command lease, or
staged credentials alive indefinitely.
> - This pull request adds the package-local turn lifecycle and its
cleanup rules without production wiring.
> - The benefit is one explicit and testable prompt boundary for the
later harness driver.
## Linked Issues or Issue Description
Refs #12402
**What would you like to improve?**
The package-local ACPX host stops at session admission. A later driver
needs to submit a prompt, consume typed ACP events, wait for the
terminal result, cancel work, and close the session. Passing the full
third-party runtime through the host would bypass the existing trust and
cleanup boundary.
**Why is this important?**
Provider prompts can be large. Turn identifiers participate in durable
correlation. Concurrent turns can make replay and cancellation
ambiguous. Shutdown must also stop an active prompt before credentials
and verified command resources are released. A provider that does not
finish cancellation must not block all remaining cleanup indefinitely.
**Suggested approach**
Add a minimal turn interface to the admitted runtime port. Accept one
prompt turn at a time. Bound the request identity and text before the
runtime sees them. Map the call to ACPX prompt mode with the admitted
session handle. Track the active turn and request cancellation before
ordered runtime cleanup. Bound the cancellation wait. Continue runtime
and command cleanup after that timeout. Release staged credentials only
after the exact runtime close succeeds.
**Additional context**
This pull request builds on #12402. It does not attach semantic tools,
normalize provider events, create a harness driver, start runnerd,
register production execution, or change server, UI, or direct-adapter
behavior.
## What Changed
- Add a narrow ACPX turn input and result and event lifecycle to the
admitted runtime port.
- Map prompt turns to the exact persistent ACPX session handle.
- Support abort signals without adding steering or attachments.
- Reject empty, whitespace-normalized, or oversized request identities.
- Reject prompt text larger than one MiB before third-party code
executes.
- Permit only one active turn per host.
- Clear the active turn only after the canonical ACPX result settles.
- Reject new turns as soon as shutdown starts.
- Cancel an active turn before runtime, credential, and command cleanup.
- Bound the cancellation wait to two seconds.
- Continue runtime and command cleanup when turn cancellation fails or
reaches its timeout.
- Release staged credentials only after the exact runtime close
succeeds.
- Keep the cancellation handle and credential lease when runtime cleanup
remains retryable.
- Coalesce concurrent close calls and report all cleanup failures in one
aggregate error.
- Add focused host and adapter tests for turn mapping, bounds,
concurrency, cancellation, timeout cleanup, credential retention, and
late-turn rejection.
## Verification
- Exact corrected head: `57e1edfcfc496bd9688c1ecf22f2d402c6bb2079`.
- The pull request delta contains four files:
- `packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts`
-
`packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.ts`
- `packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts`
- `git diff --check` passed for the exact corrected delta.
- This delta does not change dependencies, `pnpm-lock.yaml`, workflows,
migrations, server selection, UI behavior, or production runner wiring.
- Full GitHub PR workflow passed in [run
33343457544](https://github.com/paperclipai/paperclip/actions/runs/33343457544):
28 successful checks, including runner verification/build, typecheck,
all test shards, canary, and e2e; Storybook skipped by path as expected.
- Greptile is 5/5 on the exact corrected head with no blocking failure
and zero unresolved review threads.
- Superagent Security, Snyk, contributor trust, and commitperclip passed
on the exact corrected head.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this revision.
## Risks
The primary risk is ambiguous concurrent execution. The host admits only
one active turn and releases that slot from the canonical ACPX terminal
result. Another risk is partial shutdown. The host requests cancellation
first and waits for at most two seconds. It then attempts runtime and
command cleanup even if cancellation fails or reaches the timeout. It
releases staged credentials only after the exact runtime close succeeds.
If runtime cleanup fails, the host keeps the cancellation handle and
credentials for a later cleanup attempt. This pull request does not
register the runtime for production use.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Native providers can receive only the semantic operations authorized
for one run.
> - Codex ACP consumes those operations through an MCP endpoint.
> - The endpoint must be private, authenticated, bounded, and
deterministic under retries.
> - It must not advertise runner-private operations or allow callers to
replace terminal-result schemas.
> - This pull request adds a provider-neutral loopback MCP bridge with
those controls.
## Linked Issues or Issue Description
**What would you like to improve?**
The runner has a run-scoped semantic catalog and dispatcher, but the
ACPX runtime needs a secure transport for that catalog. A generic local
MCP server could expose extra operations, accept ambiguous tool
definitions, or execute the same call twice after a retry.
**Why is this important?**
Semantic tool presence is part of the authorization boundary.
Undiscoverable operations must remain unavailable. Terminal completion
and blocked-result schemas must not be replaceable. Duplicate call
identities must be idempotent, and conflicting duplicates must fail
closed.
**Suggested approach**
Bind one MCP endpoint to `127.0.0.1` for each admitted runtime. Require
a random bearer secret. Compile the closed tool schemas before
listening. Keep private operations out of `tools/list`. Validate and
fingerprint each call before dispatch. Bound request size, result size,
time, and retained call identities. Abort active operations on timeout,
cancellation, or bridge close.
**Additional context**
#12401 is merged. This PR does not attach the bridge to ACPX, register a
provider, or change any server or direct-adapter behavior.
## What Changed
- Add a provider-neutral runner semantic MCP bridge bound only to IPv4
loopback.
- Require constant-time bearer authentication before MCP operations.
- Expose only the supplied public catalog plus fixed completion and
blocked-result tools.
- Keep runner-private operations callable by trusted extensions but
absent from discovery.
- Reject invalid names, duplicate definitions, public/private
collisions, and terminal schema replacement.
- Compile JSON Schema validators before accepting traffic.
- Validate calls before dispatch and replay identical duplicate
identities exactly once.
- Treat numeric and string JSON-RPC identities as distinct and reject
conflicting duplicates.
- Bound request bodies, result text, timeouts, retained identities, and
concurrent capacity.
- Terminate oversized request bodies, preserve successful mutation
outcomes, and keep complete semantic results.
- Propagate MCP cancellation and abort active calls during close.
## Verification
- Exact verified head: `e5070e235448680e480e8d3f66bb46ac62d71c8e`.
- Full GitHub PR workflow passed in [run
33342776925](https://github.com/paperclipai/paperclip/actions/runs/33342776925),
including runner verification/build, typecheck, all test shards, canary,
and e2e.
- Greptile is 5/5 on the exact head with zero unresolved review threads.
- Superagent Security, Snyk, contributor trust, and commitperclip passed
on the exact head.
- Storybook skipped by path as expected.
- The diff contains 2 files and does not change dependencies,
`pnpm-lock.yaml`, workflows, migrations, server selection, or UI
behavior.
- No additional local suite was run during the final restack; GitHub
Actions is the authoritative verification environment.
## Risks
The main risk is widening model-visible authority. The bridge exposes
only its closed public catalog and fixed terminal tools; private
operations are omitted from discovery and catalog ambiguity fails during
startup. Another risk is duplicate execution after a provider retry. The
bridge fingerprints each admitted JSON-RPC identity, reuses the first
promise for exact retries, and rejects changed payloads. The endpoint
uses loopback plus a per-runtime bearer secret and has no production
caller in this pull request.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have added or updated tests where applicable
- [x] I have documented the authorization, network, idempotency, and
rollout risks
- [x] All applicable GitHub Actions are green
- [x] Greptile is 5/5 with every actionable comment resolved
- [x] I have addressed all review findings before merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner admits a verified Codex ACPX profile before any provider
process can start.
> - The pinned ACPX library needs a narrow adapter to the admitted
runtime host.
> - That adapter must keep credentials and launch controls out of
durable session records.
> - It must preserve exact recovery identity, model controls, and
ownership of the complete provider process tree.
> - This pull request adds the Codex-only package adapter without
registering production execution.
## Linked Issues or Issue Description
**Agent or provider**
Codex through the exact ACPX and Codex ACP packages landed in #12400.
**Why this adapter is useful**
The package-local runtime host has an injected port, but no production
implementation. This implementation uses the verified executable lease
and private runtime sandbox without persisting managed credentials or
other launch-only state in ACPX recovery records.
**How the agent is invoked**
The adapter creates one persistent ACPX Codex session. ACPX receives a
placeholder registry command, while its patched spawn callback launches
through Paperclip's verified command lease. The private launch
environment is supplied only at spawn time. Durable session state
receives only the session key, workspace, model, and bounded system
instructions.
**Additional context**
#12400 is merged. This PR does not register an adapter, start runnerd,
expose a server route, or change any direct adapter. It supports Codex
only, rejects non-Codex profiles, and fails closed on Windows until
provider descendants can be contained with an owned Job Object or
equivalent.
## What Changed
- Add a Codex-only adapter from the pinned ACPX library to the admitted
runtime port.
- Create the ACPX store inside the private runtime state directory.
- Open one persistent session with the qualified model and bounded
system instructions.
- Route provider launches through the verified executable lease and a
dedicated POSIX process group.
- Retain cleanup ownership through asynchronous errors and late
termination.
- Supply the private launch environment at spawn time without persisting
it.
- Require all ACPX recovery identity fields before returning the runtime
port.
- Map status, exact model selection, and state-preserving close
operations.
- Add regression coverage for secret isolation, verified spawning,
process-tree cleanup, lifecycle mapping, identity failure, and the
Codex-only boundary.
## Verification
- Exact verified head: `dc89439d0b2e3dee46d212715caeefc8ae0c0959`.
- Full GitHub PR workflow passed in [run 33341468207, attempt
3](https://github.com/paperclipai/paperclip/actions/runs/33341468207/attempts/3),
including runner verification/build, typecheck, all test shards, canary,
and e2e.
- Greptile is 5/5 on the exact head with zero unresolved review threads.
- Superagent Security, Snyk, contributor trust, and commitperclip passed
on the exact head.
- Storybook skipped by path as expected.
- The diff contains 2 files and does not change `pnpm-lock.yaml`,
workflows, migrations, server selection, or UI behavior.
- No additional local suite was run during the final restack; GitHub
Actions is the authoritative verification environment.
## Risks
The primary risk is leaking launch credentials into durable ACPX state.
Session options are constructed explicitly and regression-tested; the
launch environment remains behind the spawn-time callback. Another risk
is orphaning credential-bearing descendants. Supported launches use a
retained POSIX process-group identity with bounded TERM-to-KILL cleanup.
Windows fails closed before runtime construction until equivalent
process-tree containment exists.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have added or updated tests where applicable
- [x] I have documented the process, credential, recovery, and rollout
risks
- [x] All applicable GitHub Actions are green
- [x] Greptile is 5/5 with every actionable comment resolved
- [x] I have addressed all review findings before merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The package-local host boundary is ready for a concrete ACP
implementation, but the first production profile is Codex only.
> - ACPX must not inherit the server process environment or choose an
executable by pathname after admission.
> - Codex must not re-enable ambient apps, memory, skills, MCP
configuration, or instructions inside its isolated home.
> - This pull request pins only the two required production packages and
applies narrowly tested host patches.
> - The benefit is a minimal dependency boundary that follows the
repository's CI-owned lockfile process.
## Linked Issues or Issue Description
**Agent or provider**
Codex through `acpx@0.13.1` and `@agentclientprotocol/codex-acp@1.6.2`.
**Why this adapter is useful**
The injected runtime host needs a concrete ACP session manager and the
exact reviewed Codex ACP server. Upstream ACPX does not yet expose a
host-owned spawn callback, and upstream Codex ACP does not yet apply
Paperclip's isolated instruction, MCP, app, memory, and skill boundary.
Both behaviors are required before the dependency can execute inside the
runner.
**How the agent is invoked**
The next pull request will adapt these pinned packages to the private
runtime host. ACPX receives a host-owned callback that consumes the
already verified executable lease. Codex receives only the isolated
environment, explicit base instructions, explicit MCP servers, and the
skills rooted in its private `CODEX_HOME`. This pull request alone does
not spawn either package or register an adapter.
**Additional context**
This pull request is stacked on #12399. It adds no Pi, Claude, AWS, SDK,
lab, browser, or UI dependency. It intentionally does not commit
`pnpm-lock.yaml`: the repository policy job regenerates a manifest-only
PR lockfile artifact for downstream frozen installs, and the lockfile
bot updates master separately.
## What Changed
- Pin `acpx` to `0.13.1` and the Codex ACP server to `1.6.2` in the
runner package.
- Register both patches in the pnpm 9 root configuration and newer-pnpm
workspace configuration.
- Preserve the existing embedded-Postgres and ACPX 0.12 patch entries
used by other packages.
- Patch ACPX to evaluate an allowlisted environment at child-spawn time
and keep spawn cwd out of provider-visible session identity.
- Patch ACPX to accept a host-owned spawn callback with the resolved
arguments and options, allowing the verified command lease to own
execution.
- Patch Codex ACP to retain runner-owned MCP server identity in
permission requests.
- Patch Codex ACP to pass explicit Paperclip base instructions on both
start and resume.
- In isolated mode, disable ambient apps, memory, and existing MCP
configuration; load skills only from `CODEX_HOME`; and configure only
requested servers.
- Add a package contract test that enforces exact versions, Codex-only
dependency scope, both pnpm patch registries, and every required patch
hook.
## Verification
- Both patch files dry-apply successfully to fresh published tarballs
for `acpx@0.13.1` and `@agentclientprotocol/codex-acp@1.6.2`.
- A local no-lockfile install applied both patches; their runtime
markers and exact installed versions were inspected.
- Runner TypeScript typecheck — passed against the patched packages.
- Runner package tests — passed: 16 Node protocol/package tests and 426
Vitest tests.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- `git diff --check` — passed.
- The diff contains 6 files and does not change `pnpm-lock.yaml`, a
GitHub workflow, server selection, or UI behavior.
## Risks
The primary risk is drift between published package contents and
checked-in compiled patches. Exact versions are pinned, both patches are
exercised by package-contract gates, and CI performs the authoritative
regenerated-lockfile frozen install. The spawn callback does not grant a
new executable path: the following adapter must consume the opaque
verified command lease. Codex isolation changes activate only when
`PAPERCLIP_ACPX_ISOLATED_CONTEXT=1`, so existing direct Codex adapters
are unaffected.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the dependency, patch, isolation, and lockfile
boundaries
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The ACPX pieces already verify profiles, installations, recovery
identity, permissions, runtime files, credentials, and models
independently.
> - A production host must compose those checks in one fail-closed order
and clean every acquired resource on partial startup.
> - Directly importing a third-party ACP runtime here would mix
dependency adoption with the security lifecycle.
> - This pull request defines a narrow injected runtime port and admits
it only after all package-local boundaries pass.
> - The benefit is a testable host lifecycle without adding `acpx`,
changing the lockfile, or making the adapter selectable.
## Linked Issues or Issue Description
**Agent or provider**
The qualified Pi, Claude, and Codex ACPX profiles; Codex additionally
uses the managed credential lease.
**Why this adapter is useful**
The runner needs one owner for startup ordering, immutable identity
checks, exact model verification, and cleanup. Otherwise a failure after
credential staging or command admission can leave secret files or
executable leases alive, and a resumed provider can attach to a
different profile, workspace, model, or permission mode.
**How the agent is invoked**
A later dependency-adapter pull request will implement the injected
runtime port with the pinned ACPX library. This host passes that adapter
an opaque verified command lease, canonical workspace, private state
directory, profile-bound session key, qualified permission policy,
launch-only environment, and bounded instructions. It does not expose
the runtime directly or add a user-selectable adapter.
**Additional context**
This pull request is stacked on #12398. Installation verification has a
production default; only the third-party runtime opener is injected.
Tests use a fake port so this boundary remains package-local and
dependency-free.
## What Changed
- Add a minimal ACP runtime port for identity, status, model selection,
and bounded shutdown.
- Derive the qualified profile and canonical recovery binding before any
provider startup.
- Reject expected-identity drift and irrelevant managed-Codex inputs
before opening the provider.
- Verify that even an injected installation result matches the closed
profile digest.
- Prepare the private sandbox and stage Codex credentials only for the
Codex profile.
- Acquire an opaque verified command lease and pass only the composed
launch boundary to the runtime port.
- Apply the canonical permission policy and collision-resistant provider
session key.
- Select and verify the exact effective model before returning an
admitted host.
- Create a strict versioned identity record and compare resumed provider
identifiers with the expected record.
- Keep the runtime private and expose only cloned identity, binding,
runtime-root, and persistence-safe environment views.
- On startup or shutdown failure, attempt runtime close, credential
cleanup, and command-lease cleanup in order and aggregate every error.
- Add tests for Codex secret isolation, Claude selector verification,
recovery drift, injected digest drift, partial-start cleanup, and
cleanup retry.
## Verification
- Runner TypeScript typecheck — passed.
- Runner protocol and TypeScript tests — passed: 12 protocol tests and
426 Vitest tests, including 6 runtime-host tests.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 2 files and does not change `pnpm-lock.yaml`, a
workflow, a dependency, a public package export, server selection, or UI
behavior.
## Risks
The main risk is leaking a partially admitted resource when a later
admission step fails. Resource acquisition is linear and all failure
paths use the same ordered cleanup routine. The runtime port is
deliberately minimal and privately owned by the host; it cannot bypass
profile, model, recovery, sandbox, credential, or command admission. The
actual ACPX implementation and its process-supervision behavior remain a
separate review unit.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the admission and cleanup boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Codex can authenticate through an API key or an `auth.json`
document.
> - Forwarding managed credentials in process arguments, durable session
options, or general environment state would leak them across the runner
boundary.
> - The ACPX sandbox therefore needs a private Codex home, bounded
staging, crash-safe cleanup intent, and cross-process ownership that
fails closed without relying on writable marker files.
> - This pull request establishes that credential boundary before later
PRs connect the Codex ACP process.
## Linked Issues or Issue Description
**Agent or provider**
The qualified Codex ACPX profile.
**Why this adapter is useful**
Managed installations may already have a Codex login document, while
service deployments may provide an API key or inline JSON. The runner
needs all three modes without copying ambient home state, accepting
ambiguous sources, persisting secret values in ordinary runner state,
following links, or allowing concurrent processes to mutate the same
credential home.
**How the agent is invoked**
A later runtime-host pull request acquires this credential lease before
opening Codex and closes it during shutdown and failed-start paths. API
keys remain launch-only environment values. JSON credentials are
atomically staged as `auth.json` inside the isolated Codex home. This
pull request does not spawn Codex, add a dependency, register an
adapter, or change execution selection.
**Additional context**
This is the lowest unmerged PR in the runner series and targets `master`
directly. It deliberately requires one explicit credential source and
never reads the Paperclip server user's ambient home by default.
## What Changed
- Add one-use managed Codex credential leases for API-key, inline-JSON,
and explicit managed-file modes.
- Reject missing and ambiguous source combinations.
- Require absolute external managed-file paths, private ownership and
permissions on POSIX, bounded documents, no-follow opens, and stable
file identity during reads.
- Stage JSON through a deterministic private no-follow staging path,
scrub stale staging state on admission, sync the file, rename
atomically, and sync the parent directory.
- Persist a bounded cleanup intent and remove staged or
provider-generated authentication files without following links.
- Fence each canonical credential home with a markerless 2-of-3
exclusive loopback quorum derived from the current UID and canonical
home. One unrelated occupied candidate is tolerated; two occupied
candidates fail closed before credential mutation.
- Bound stuck parent filesystem operations and cleanup helpers
process-wide so an unresponsive filesystem cannot create unbounded work.
- Zero temporary credential buffers and make cleanup retryable without
allowing a stale cleanup generation to affect a successor.
- Add focused tests for credential modes, permissions, malformed and
ambiguous sources, symlink rejection, deterministic staging, quorum
contention and crash release, stuck-operation bounds, and idempotent
cleanup.
## Verification
- Prettier and `git diff --check` passed for the exact pushed head.
- Greptile reviewed the exact head at 5/5 with no blocking finding;
independent static audits found no remaining correctness, security,
test-contract, or resource-bound blocker.
- GitHub Actions passed on the exact head
`29e75afb7b8529b9d070070e0c1462e795d115bb`, including Build, Typecheck,
the complete test matrix, e2e, verify, and security checks. One
unrelated hosted-runner `npm ENOENT` shard passed on its GitHub rerun.
- The diff contains 2 files and does not change `pnpm-lock.yaml`,
workflows, dependencies, public package exports, server selection, or UI
behavior.
## Risks
The primary risks are credential disclosure, concurrent ownership, and
cleanup that outlives its authority. Secret values never enter returned
identity or durable runner data. Source and destination operations are
bounded, no-follow, privately permissioned, and crash-durable. The
markerless kernel quorum prevents concurrent home mutation without
trusting a replaceable marker, while process-global operation/helper
caps prevent unresponsive filesystem work from growing without bound.
Cleanup is generation-scoped so a stale retry cannot remove a
successor's credential.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [ ] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the credential and cleanup boundary
- [x] All applicable GitHub Actions are green
- [x] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - ACPX agents read homes, configuration files, caches, and environment
variables.
> - Reusing the server user's ambient state would leak unrelated
credentials and make recovery nondeterministic.
> - Recovery identity already assigns each session a collision-resistant
runtime root.
> - This pull request materializes that root as a private, bounded
sandbox and separates launch-only secrets from persistable
configuration.
> - The benefit is an isolated runtime boundary before any ACP process
is hosted.
## Linked Issues or Issue Description
**Agent or provider**
The qualified Pi, Claude, and Codex ACPX profiles.
**Why this adapter is useful**
Each agent expects different home and configuration variables, but none
should inherit the Paperclip server user's general home, provider
credentials for another agent, or unrelated process secrets. Runtime
recovery also needs stable non-secret paths without persisting API keys,
OAuth tokens, proxy credentials, or MCP bootstrap tickets.
**How the agent is invoked**
A later runtime-host pull request will prepare this sandbox, then pass
its frozen launch environment and private directories to a verified ACPX
command lease. This pull request does not spawn an agent, add
dependencies, register an adapter, or alter server execution selection.
**Additional context**
This pull request is stacked on #12395. It uses that pull request's
canonical workspace and collision-resistant runtime binding. All
filesystem and environment behavior remains package-local.
## What Changed
- Create a normalized session root beneath the private `acpx` runtime
namespace.
- Create isolated home, configuration, data, cache, state, and
agent-specific directories with mode `0700`.
- Reject symbolic links, non-directory paths, namespace escapes, and
non-normalized roots.
- Write the canonical workspace record and Pi trust settings atomically
through exclusive no-follow temporary files with mode `0600`.
- Give Pi, Claude, and Codex only their qualified home and isolation
variables.
- Reuse the existing per-agent environment allowlist for launch-time
credentials and bound the final environment size.
- Return a separate persistence-safe environment containing only stable
paths, locale values, and non-secret agent flags.
- Explicitly exclude provider credentials, proxy URLs, MCP URLs, and MCP
tokens from the persisted projection.
- Add table-driven tests for all three agents, file modes, state
contents, secret splitting, idempotence, and symbolic-link rejection.
## Verification
- Runner TypeScript typecheck — passed.
- Runner protocol and TypeScript tests — passed: 12 protocol tests and
413 Vitest tests, including 5 runtime-sandbox tests.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 2 files and does not change `pnpm-lock.yaml`, a
workflow, a dependency, a public package export, server selection, or UI
behavior.
## Risks
The main risks are following attacker-controlled filesystem aliases or
persisting a credential under an unexpected variable name. Every created
path is checked against its physical parent, the session root must
already be absolute and normalized, temporary files use exclusive
no-follow opens, and the persisted projection is a positive allowlist
rather than a credential-name blacklist. The launch environment remains
available only in memory and is bounded before use.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the runtime isolation and secret-persistence
boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A durable ACPX session must resume only the workspace, profile,
model, policy, and provider session that created it.
> - Sanitized directory names can collide, and lexical workspace paths
can change meaning through symbolic links.
> - Schema-less draft records cannot prove workspace or
normalized-session provenance.
> - This pull request establishes one closed v1 identity format and
rejects records that cannot prove every immutable binding.
> - The benefit is fail-closed recovery without enabling or selecting
the ACPX runtime.
## Linked Issues or Issue Description
**Agent or provider**
Durable sessions for qualified Pi, Claude, and Codex ACP servers through
the internal ACPX driver.
**Why this adapter is useful**
The runner must prevent a persisted provider session from being reused
with another workspace, model, permission policy, profile, or normalized
session. It must also distinguish normalized session names that sanitize
to the same pathname.
**How the agent is invoked**
A later pull request will use this binding when the private ACPX runtime
opens or recovers a session. This pull request does not launch a
process, add a dependency, register an adapter, or change runtime
selection.
**Compatibility boundary**
No ACPX identity writer exists on master or in a shipped runtime. This
pull request establishes the first accepted persisted format. Draft
schema-less records and early-v1 command-digest records cannot prove
every immutable binding and are intentionally rejected; an affected
experimental session must start fresh.
## What Changed
- Resolve real workspace and runtime-directory paths and reject
filesystem roots or non-directories.
- Derive collision-resistant runtime roots and provider session keys.
- Bind the session key to workspace, complete qualified profile, model,
protocol, agent, and permission mode.
- Add a closed v1 ACPX identity record.
- Verify controller identity and persisted identity against every
immutable binding.
- Reject schema-less, early-digest, unknown-version, unknown-field, and
malformed records.
- Add tests for canonical paths, collision resistance, drift,
workspace/session replay, missing policy, malformed records, and unsafe
roots.
## Verification
- GitHub Actions are the authoritative typecheck, test, build, and
integration gate for the final head.
- Greptile, Superagent, and Snyk are required to pass on the final head.
- `git diff --check` passes for the two-file delta.
- The diff does not change `pnpm-lock.yaml`, a workflow, a dependency, a
public export, server selection, migration, or UI behavior.
## Risks
The main risk is accepting an identity under a different immutable
session configuration. Controller and v1 record fields are compared
exactly, including permission mode and the complete qualified-profile
digest. Records that lack workspace/session provenance or use an
obsolete partial digest fail closed. Because no writer for those draft
formats has shipped, requiring a fresh experimental session is safer
than synthesizing missing authority from the current request.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have added or updated tests where applicable
- [x] I have documented the recovery and compatibility boundary
- [ ] All applicable GitHub Actions are green on the final head
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A qualified ACPX profile binds exact provider and runtime package
versions.
> - Package metadata alone does not prove which executable will run.
> - A pathname, directory entry, or open inode can still change after
verification.
> - A verified launch therefore needs a one-use lease over entry bytes
and retained directories, with ambient loader and package authority
removed.
> - Provider compatibility is admitted later, per provider; this
primitive must fail closed when a provider needs an unqualified path or
dependency.
## Linked Issues or Issue Description
**Agent or provider**
Internal qualified ACPX profiles. The first production consumer remains
Codex-only in the follow-on dependency and adapter changes.
**Why this adapter is useful**
The runner needs to prove that installed package metadata and executable
bytes match a reviewed profile, then prevent pathname replacement,
symlink escape, host-package lookup, or loader injection from changing
what executes.
**How the agent is invoked**
A later provider-specific adapter requests an opaque one-use command
lease. On Linux, the lease starts Node with a synchronous hook, supplies
the verified entry snapshot over a private pipe, and retains only the
verified package directories needed by that profile. This pull request
does not register an adapter, change runtime selection, or make any
provider user-visible.
**Compatibility boundary**
The launched entry deliberately has a Linux descriptor-backed identity
such as `/proc/self/fd/4/...`; preserving a mutable canonical pathname
would reopen the replacement vulnerability. A provider that requires
canonical `import.meta.url`, `__filename`, or `process.argv[1]` is not
admitted by this primitive until its provider-specific adapter proves
compatibility. Likewise, arbitrary package-manager ancestors are not
retained. Hoisted dependencies must be explicitly qualified by a later
provider-specific layer; otherwise startup fails closed. The initial
production slice is Codex only, not Pi or Claude.
## What Changed
- Verify exact server and optional runtime package versions from bounded
metadata.
- Require one supported relative Node executable and reject ambiguous or
package-escaping paths.
- Canonicalize the command directory and open final components without
following symbolic links.
- Bound and hash the open entry file while checking device, inode, size,
and timestamps around the read.
- Return an opaque installation and one-use launch lease instead of an
executable pathname.
- Reopen and revalidate retained directory and executable identities
when acquiring a lease.
- Load the admitted entry bytes and package-contained modules through
retained Linux descriptors.
- Resolve CommonJS and ESM bare imports only from retained roots, reject
host ancestors, and make symlink escape terminal.
- Open module bytes with `O_NOFOLLOW`, bound each read, recheck
identity, and reject native or unsupported module formats.
- Strip Node, native dynamic-loader, glibc, and OpenSSL injection
variables before spawn.
- Add regressions for replacement races, direct resources, sibling and
ancestor imports, explicit runtime roots, host-ancestor denial,
descendant and final symlinks, bounded reads, and environment injection.
## Verification
- The authoritative GitHub Actions and exact-head Greptile review are
the merge gates for the final head.
- Prettier and `git diff --check` pass for the final two-file diff.
- The diff does not change `pnpm-lock.yaml`, workflows, dependencies,
public exports, server selection, or UI behavior.
## Risks
The security/compatibility tradeoff is explicit: descriptor identity
prevents a replaced lexical path from supplying resources, but
pathname-sensitive providers require a later adapter-specific
qualification. Unqualified or unsupported dependencies, native addons,
non-Linux launch, and unsupported module formats fail closed. No
production call path reaches this primitive in this pull request.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have described the issue and provider boundary above
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have added or updated affected tests
- [x] I have documented the trust, compatibility, dependency, and
rollout boundaries
- [ ] All applicable GitHub Actions are green on the final head
- [ ] Greptile is 5/5 on the final head with every actionable comment
resolved
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Each qualified ACPX profile binds one exact model and one reported
ACP selector.
> - A provider can start with a stale default or report a selector that
differs from the canonical model name.
> - The runner must select and verify the qualified model before it
accepts a billable prompt.
> - This pull request adds that verification boundary and normalizes a
verified selector for provider-neutral consumers.
> - The benefit is fail-closed model identity without enabling the ACPX
runtime.
## Linked Issues or Issue Description
**Agent or provider**
Qualified Pi, Claude, and Codex ACP servers through the internal ACPX
driver.
**Why this adapter is useful**
The runner must not assume that an ACP session uses the requested model.
It needs a status check, an exact model selection when required, and a
second status check before work can begin.
**How the agent is invoked**
A later pull request will provide the private ACP runtime control behind
this interface. This pull request does not launch a process, add a
dependency, register an adapter, or change runtime selection.
**Additional context**
This pull request is stacked on #12391. Claude's qualified canonical
model is `claude-sonnet-5`, while its pinned ACP server reports the
stable selector `sonnet`.
## What Changed
- Require ACP model status before accepting a qualified runtime.
- Select the exact canonical model when the session reports a stale
default.
- Reapply canonical selection when a qualified profile uses a distinct
ACP selector.
- Fail closed when status, model selection, or the expected reported
selector is unavailable.
- Normalize a verified selector back to the canonical model for
provider-neutral status consumers.
- Add tests for exact, stale, aliased, unavailable, and
ignored-selection cases.
## Verification
- Runner TypeScript typecheck — passed.
- Runner TypeScript tests — passed, including 5 new model-verification
tests.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 2 files and does not change `pnpm-lock.yaml`, a
workflow, a dependency, a public export, server selection, or UI
behavior.
## Risks
The main risk is treating a provider alias as proof of the requested
model. A distinct selector is accepted only when it is part of the
immutable qualified profile, after the runner sends the exact canonical
model through ACP and performs a second status check. All other
mismatches fail closed.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the model admission boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - ACP agents can request permission before reads, process execution,
and workspace mutation.
> - The runner must apply the configured policy without allowing
provider display text to grant authority.
> - Runner-owned semantic tools already have a separate run-scoped
authorization catalog.
> - This pull request defines the local permission decision and the
narrow metadata needed to recognize those authorized tools.
> - The benefit is a fail-closed permission boundary before an ACPX
process can use it.
## Linked Issues or Issue Description
**Agent or provider**
Qualified Pi, Claude, and Codex ACP servers through the internal ACPX
driver.
**Why this adapter is useful**
ACP providers use permission requests for both ordinary provider
operations and runner-owned semantic operations. Paperclip must apply
`approve-all`, `approve-reads`, or `deny-all` consistently while keeping
semantic authorization bound to structural MCP metadata.
**How the agent is invoked**
A later pull request will install this policy in the private ACPX
runtime host. This pull request does not launch a provider, add a
dependency, register an adapter, or change runtime selection.
**Additional context**
This pull request is stacked on #12390. Pi uses a different bridge and
never receives semantic auto-approval through this ACP permission path.
## What Changed
- Map each ACPX permission mode to a closed runtime policy.
- Decide local allow, reject, or coordinator delegation outcomes.
- Auto-approve only runner-owned semantic MCP calls identified by
structural metadata.
- Ignore provider display titles when determining semantic authority.
- Limit Codex blanket MCP approval to sessions where every configured
MCP server is runner-owned.
- Add table-driven tests for all modes, agents, metadata shapes, spoofed
titles, and non-runner servers.
## Verification
- Runner TypeScript typecheck — passed.
- Runner TypeScript tests — passed, including 10 new permission-policy
assertions.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 2 files and does not change `pnpm-lock.yaml`, a
workflow, a dependency, a public export, server selection, or UI
behavior.
## Risks
The main risk is mistaking a provider-controlled label for an authorized
semantic tool. The implementation ignores display titles and requires a
runner-owned MCP server name, a transport tool name, or provider
metadata. All other `approve-reads` mutations delegate to the
coordinator, and the caller must reject them when no delegate exists.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the permission and semantic-authorization
boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A native driver must declare its supported behavior before the
coordinator can select it.
> - ACP-compatible agents do not all expose the same event families.
> - A loose config could also select an unqualified model, permission
policy, or executable field.
> - This pull request defines the ACPX descriptor, capability matrix,
and strict configuration parser.
> - The benefit is one reviewable admission contract before any ACPX
runtime is wired.
## Linked Issues or Issue Description
**Agent or provider**
Qualified Pi, Claude, and Codex ACP servers through the internal ACPX
driver.
**Why this adapter is useful**
The runner needs a truthful capability descriptor and a closed
configuration boundary before it can create an ACPX session. The
boundary must reject arbitrary commands and unqualified models.
**How the agent is invoked**
A later pull request will implement the private runtime behind this
descriptor. This pull request does not launch a process, add a
dependency, register an adapter, or make ACPX selectable.
**Additional context**
This pull request is stacked on #12389. Pi reports plan events as
unsupported. Claude and Codex report structured plan support.
## What Changed
- Add the ACPX driver descriptor and native runtime-context capability
declaration.
- Add an agent-specific typed event capability matrix.
- Add strict config validation for agent, exact qualified model, and
permission mode.
- Default the permission mode to `approve-all` when the field is absent.
- Reject non-object config, unknown fields, unqualified models, and
unsupported permission values.
- Add table-driven tests for all qualified agents and failure cases.
## Verification
- Runner TypeScript typecheck — passed.
- Runner TypeScript tests — passed, including 8 new driver-profile
assertions.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 2 files and does not change `pnpm-lock.yaml`, a
workflow, a dependency, a public export, server selection, or UI
behavior.
## Risks
The main risk is advertising a capability that a qualified ACP server
cannot supply. The matrix is explicit per agent, and tests cover the one
current difference. Config validation rejects unknown fields so a caller
cannot smuggle an executable or an unsupported runtime setting into this
boundary.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the compatibility and admission boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - An ACPX sidecar will read asynchronous commands from one ordered
input stream.
> - Concurrent command handling could reorder bootstrap, turn, suspend,
and shutdown operations.
> - A failed diagnostic callback could also poison the input promise and
skip later frames.
> - This pull request adds a small serial queue and records the first
provider-bootstrap failure.
> - The benefit is deterministic input ordering and a stable fail-closed
bootstrap state before the sidecar exists.
## Linked Issues or Issue Description
**Agent or provider**
The internal ACPX sidecar for qualified ACP-compatible providers.
**Why this adapter is useful**
The sidecar must process input frames in order. It must drain accepted
input before shutdown, continue after an ordinary command error, and
reject dependent commands after initialization or session bootstrap
fails.
**How the agent is invoked**
A later pull request will connect this helper to a private sidecar
process. This pull request adds no executable, dependency, adapter
registration, or process launch.
**Additional context**
This pull request is stacked on #12388. The helper remains package-local
and does not affect direct adapters.
## What Changed
- Add a serial asynchronous input queue that remains usable after
operation and diagnostic failures.
- Add ACPX-specific input sequencing around the shared queue.
- Preserve the first `initialize` or `session.open` failure as the
bootstrap cause.
- Produce a deterministic blocked-command error after bootstrap fails.
- Test ordering, EOF-style draining, error isolation, sticky bootstrap
failure, and non-sticky turn failure.
## Verification
- Runner TypeScript typecheck — passed.
- Runner TypeScript tests — passed, including 4 new sequencing tests.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 3 files and does not change `pnpm-lock.yaml`, a
workflow, a dependency, a public export, server selection, or UI
behavior.
## Risks
The main risk is allowing one failed input operation to reorder or
suppress later input. Each operation runs only after the previous
promise settles. Both operation and diagnostic failures are contained.
Bootstrap failure is recorded separately so an ordinary turn failure
does not disable the sidecar session.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the compatibility and failure boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner uses one provider-neutral question contract for user
input.
> - ACP providers describe form input with provider-specific JSON Schema
values.
> - Passing those values through would couple the task page to ACP and
could bypass the existing response validator.
> - This pull request converts bounded ACP forms to the existing
Paperclip question contract and converts validated answers back to ACP
content.
> - The benefit is one question path that does not change any legacy
adapter behavior.
## Linked Issues or Issue Description
**Agent or provider**
ACP-compatible providers that use form elicitation.
**Why this adapter is useful**
ACP providers need structured user answers during a turn. Paperclip must
present those questions through its provider-neutral contract so the
existing task experience and validation rules remain consistent.
**How the agent is invoked**
A later pull request will connect this internal adapter to the ACPX
sidecar. This pull request only implements the conversion boundary. It
does not launch ACPX, add a dependency, or enable an adapter.
**Additional context**
This pull request is stacked on #12387. URL elicitation remains
unsupported and returns no form projection.
## What Changed
- Convert bounded ACP string, enum, multi-select, Boolean, number, and
integer fields to `paperclip.question_set.v1`.
- Validate every answer with the existing provider-neutral response
parser before conversion.
- Convert validated answers back to typed ACP form content.
- Bound provider-controlled field and option inventories.
- Use stable question identities and define arbitrary property names
without prototype mutation.
- Keep ACP runtime types and dependencies outside this package-local
conversion boundary.
## Verification
- Runner TypeScript typecheck — passed.
- Runner TypeScript tests — 41 files and 367 Vitest tests passed; 12
Node contract tests passed.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 2 files and does not change `pnpm-lock.yaml`, a
workflow, a package dependency, a public export, server selection, or UI
behavior.
## Risks
The main risk is accepting an ACP form that cannot be represented safely
by the Paperclip question contract. Unsupported field types fail closed.
Field and option inventories are bounded. The existing question parser
validates all text, selection, numeric, and required-field constraints
before any response returns to ACP.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the compatibility and security boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The Paperclip runner needs a safe boundary before it can launch
ACP-compatible agents.
> - A caller-controlled command, model, environment, or frame could
bypass that boundary.
> - The ACPX transport contract in #12386 defines the allowed messages
but does not bind a runtime profile.
> - This pull request defines closed, versioned profiles and validates
the launch inputs around that contract.
> - The benefit is a small and reviewable trust boundary before any ACPX
process can become available.
## Linked Issues or Issue Description
**Agent or provider**
ACPX sidecar support for the qualified Pi, Claude, and Codex ACP
servers.
**Why this adapter is useful**
The runner needs one bounded process boundary for ACP-compatible
providers. A closed profile prevents an untrusted run from selecting an
arbitrary executable, package version, or model.
**How the agent is invoked**
A later pull request will launch an internal sidecar from an exact
profile. This pull request only validates profiles, environment values,
and protocol frames. It does not add an executable dependency or enable
an adapter.
**Additional context**
This pull request is stacked on #12386. It keeps the existing direct
adapters and the Codex runner path unchanged.
## What Changed
- Add a closed profile table for the qualified Pi, Claude, and Codex ACP
servers.
- Require the exact qualified model and return an isolated profile value
to callers.
- Add an agent-specific environment allowlist with entry and aggregate
size limits.
- Add strict parsing for bounded sidecar requests and structured plan
values.
- Reject unknown fields, unsupported protocol versions, invalid
identifiers, null bytes, cyclic values, and oversized input.
## Verification
- Runner TypeScript typecheck — passed.
- Runner TypeScript tests — 40 files and 362 Vitest tests passed; 11
Node contract tests passed.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 6 files and does not change `pnpm-lock.yaml`, a
workflow, a package dependency, or a public export.
## Risks
The main risk is accepting more launch state than the sidecar needs. The
implementation uses an agent-specific allowlist, rejects null bytes, and
enforces per-entry and aggregate bounds. This pull request does not
launch a process or expose a new adapter, so production and
direct-adapter behavior remain unchanged.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the compatibility and security boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip Runner now has a complete guarded Codex vertical slice.
> - The next provider series must not start by importing a provider
implementation or dependency bundle.
> - ACPX needs one bounded, versioned process boundary shared by
TypeScript and Rust.
> - A schema is the authority; checked-in generated inventories keep
both languages in lockstep.
> - Unknown versions, commands, event types, and properties must fail
closed.
> - This pull request therefore lands only the sidecar wire contract and
its drift gate.
> - No ACPX runtime, dependency, executable, package export, or
production selection is added.
## Linked Issues or Issue Description
This is the first package-local unit in the post-Codex provider series.
**What happened?**
The integration branch contains an ACPX provider, but its TypeScript
sidecar and Rust client need a small shared authority before either
implementation can be reviewed safely. Importing the final integration
implementation directly would mix the protocol, runtime, third-party
dependencies, and production wiring.
**Expected behavior**
The schema defines every ACPX sidecar request, response, event, command,
event type, and protocol version. Generated TypeScript and Rust
inventories must drift-check against that schema. No runtime can select
or execute ACPX yet.
**Steps to reproduce**
1. Change the protocol version, command inventory, or event inventory in
the schema.
2. Run the runner protocol type check without regenerating the language
inventories.
3. Observe the drift gate fail.
**Paperclip version or commit**
Stacked on `runner-server-semantic-codex` at `ebd7f9df7`.
## What Changed
- Add the internal ACPX sidecar v2 JSON Schema outside the public PRP v1
schema catalog.
- Generate one TypeScript inventory and one Rust inventory from that
schema.
- Add generate and check hooks to the existing runner protocol-type
workflow.
- Add fail-closed AJV tests for all three message families, version
drift, unknown commands, and extra properties.
- Keep the generated Rust module unregistered until the Rust ACPX
transport exists.
## Compatibility Boundary
- Codex remains the only production runner provider.
- `paperclip_runner` selection and the default-off rollout flag are
unchanged.
- No ACPX package, patch, lockfile, binary entry point, root export,
server file, UI file, workflow, or dependency is added.
- The schema is shipped with the existing `protocol` directory but is
not added to the public PRP manifest.
- Existing direct adapters continue through their current paths.
- Diff against the actual stacked base: 6 files.
## Verification
- Runner TypeScript typecheck and both generated-contract drift gates —
passed.
- Runner TypeScript tests — 37 files and 355 Vitest tests passed; 11
Node contract tests passed.
- Rust provider-bridge regression suite after restacking — 14/14 passed.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- `pnpm test:run` — attempted; the local host reproduced unrelated
workspace/Postgres and port-exposure failures in unchanged server
suites. The changed runner contract suites pass, and the repository's
serialized/sharded GitHub checks remain authoritative for those
host-sensitive suites.
- Prettier, rustfmt, generated-source drift checks, and `git diff
--check` — passed.
- `pnpm-lock.yaml` is unchanged.
## Risks
The main risk is allowing schema and generated language inventories to
diverge. Build and typecheck now fail on any drift. The sidecar
implementation and third-party ACPX packages are deliberately absent, so
this PR cannot alter runtime behavior or expand the production attack
surface.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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
- [x] I have described the issue and expected behavior in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the compatibility and security boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The hidden native coordinator already computes a run-scoped semantic
tool projection.
> - The durable Codex backend now accepts and enforces that projection.
> - The server did not include the projection in its `run.prepare`
command.
> - Codex therefore received no production semantic tools even when the
server authorized them.
> - This pull request adds the deterministic wire projection and sends
it to runnerd.
> - The benefit is one fail-closed authorization catalog from the server
through Codex.
## Linked Issues or Issue Description
Refs #12384
**What existing behavior does this improve?**
This improves the existing flagged Paperclip Runner Codex path.
**Current behavior**
The server creates a run-scoped list of authorized read tools. It does
not pass that list to runnerd, so the production Codex session starts
with no tools.
**Proposed behavior**
The server maps the authorized definitions to the versioned runner
contract. It computes a cross-language catalog digest. It includes that
immutable contract in `run.prepare`.
**Reason and benefit**
Runnerd and the server now enforce the same catalog identity. Unknown,
duplicate, changed, or malformed tool contracts fail before Codex can
use them.
**Breaking changes**
None. Direct adapters are unchanged. A native run with an empty server
projection still starts with no dynamic tools.
## What Changed
- Add a deterministic semantic-definition to runner-authorization
projection.
- Match the Rust canonical digest with a shared test vector.
- Include the server coordinator projection in the native Codex
`run.prepare` command.
- Extend the native Codex vertical slice to require and execute a
semantic tool.
- Verify the production prepare payload in a host-independent server
test.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript` (354
tests pass)
- `pnpm --filter @paperclipai/server exec vitest run
src/services/native-runtime/native-codex-runner.test.ts`
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm -r typecheck`
- `pnpm build`
- The embedded-Postgres vertical slice is present for CI. This local
host reports that embedded Postgres is unavailable, so Vitest skips that
host-dependent test locally.
- Confirmed that the PR changes 7 files against
`runner-codex-durable-tools`.
- Confirmed that `pnpm-lock.yaml` is unchanged.
## Risks
The main risk is a catalog digest mismatch between TypeScript and Rust.
Both implementations use canonical JSON. They share the same fixed
digest vector. Runnerd also recomputes the digest and rejects a
mismatch.
The rollout flag and the existing native runtime selection rules remain
unchanged.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The Paperclip Runner gives an agent a durable execution boundary.
> - The Codex transport can now advertise a run-scoped semantic tool
catalog.
> - The durable backend did not yet persist tool calls or correlate
their results.
> - A restart could therefore lose the boundary between a provider call
and a Paperclip action.
> - This pull request binds authorized calls, durable events, results,
replay, and cancellation.
> - The benefit is safe semantic tool recovery without duplicate
Paperclip actions.
## Linked Issues or Issue Description
Refs #12382
**What existing behavior does this improve?**
This improves the durable Codex provider backend in
`@paperclipai/paperclip-runner`.
**Current behavior**
The Codex transport can project authorized dynamic tools. The durable
backend rejects their calls because it cannot persist and recover their
identities.
**Proposed behavior**
The durable backend records each authorized call before it emits the
semantic input event. It records each result before it sends the result
to Codex. It reconciles exact provider replays without another Paperclip
action.
**Reason and benefit**
This order prevents duplicate semantic actions after a process restart.
It also keeps unauthorized, changed, oversized, and late calls closed.
**Breaking changes**
None. A run without an authorized tool catalog still starts Codex with
no dynamic tools.
## What Changed
- Persist the authorized tool catalog with the Codex provider state.
- Emit correlated and redacted semantic input, reconciliation, and
result events.
- Reconcile exact pending and completed calls after a provider restart.
- Reject catalog drift, changed replay input, malformed results, and
unauthorized operations.
- Complete pending tool calls with a durable failure when a turn stops.
- Bound retained tool values and validate recovered state before
provider startup.
- Bind production runner events to the active run, session, turn, and
item identities.
## Verification
- `cargo fmt --all -- --check`
- `cargo test --workspace`
- `pnpm -r typecheck`
- `pnpm build`
- Confirmed that the PR changes 9 files against
`runner-codex-dynamic-tools`.
- Confirmed that dependency installation did not change
`pnpm-lock.yaml`.
## Risks
The main risk is a mismatch between recovered provider state and the
controller tool catalog. Recovery validates the complete catalog and its
digest before Codex starts. The backend persists a call before it emits
work and persists a result before it returns the result to Codex.
This PR does not enable the server adapter or change any direct adapter
path.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The native runner keeps provider execution separate from Paperclip
tool authority.
> - The Rust authorization bridge can now validate a run-scoped semantic
tool catalog.
> - Codex still needs a bounded protocol adapter for that validated
catalog.
> - The adapter must advertise the same catalog after provider recovery.
> - The adapter must reject unadvertised calls and mismatched results.
> - This pull request adds that Codex-only transport boundary.
> - The benefit is a fail-closed provider bridge that remains inactive
until durable wiring supplies tools.
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` and its Rust Codex app-server provider.
**Problem or motivation**
The native runner has a validated semantic tool catalog, but the Rust
Codex provider cannot project that catalog or correlate Codex tool calls
with Paperclip results. A resumed Codex thread also needs the same
run-scoped catalog.
**Proposed solution**
Add an explicit Codex start path that accepts validated tools. Send
those tools through `dynamicTools` for both thread start and thread
resume. Validate thread, turn, call, operation, result identity, and
size before data crosses the provider boundary.
**Roadmap alignment**
This work supports the shipped governed MCP Tool Gateway and
self-healing run milestones. It does not add a user-facing adapter or
enable the experimental runner.
## What Changed
- Add a Codex dynamic-tool projection for explicit authorized tool sets.
- Advertise the same tool set on new and resumed provider threads.
- Correlate bounded Codex tool calls and Paperclip semantic results.
- Reject calls outside the active thread or turn, unadvertised tools,
reused request identities, mismatched results, and oversized values.
- Keep the current durable backend on the zero-tool path until the next
wiring change.
- Extend the fake Codex app server and integration tests for success,
recovery, denial, and correlation behavior.
## Verification
- `cargo test --manifest-path
packages/paperclip-runner/runner/Cargo.toml --workspace`
- `cargo clippy --manifest-path
packages/paperclip-runner/runner/Cargo.toml --workspace --all-targets --
-D warnings -A clippy::manual_is_multiple_of -A
clippy::filter_map_bool_then`
- `pnpm -r typecheck`
- `pnpm build`
- The PR changes 4 files relative to `runner-rust-semantic-tool-bridge`.
## Risks
Low activation risk. The existing `CodexProvider::start` path still
supplies an empty tool set. The durable backend treats a tool event as
an error until a later PR attaches the durable authorization bridge. The
new transport rejects unknown tools and invalid provider bindings.
> 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 with GPT-5 and repository tool use.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The runner package has a reviewed semantic action catalog and
dispatcher
> - The Rust runner process needs the same fail-closed authorization
boundary
> - Provider calls must remain correlated and idempotent across durable
recovery
> - Input and result values must satisfy the authorized operation
schemas
> - This pull request adds a package-local durable semantic tool bridge
> - It does not advertise tools to Codex or enable the Paperclip Runner
adapter
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner/runner` semantic tool authorization and
correlation.
**Problem or motivation**
The Rust runner needs a durable representation of the run-scoped tools
that the control plane authorizes. It must reject unknown operations,
catalog drift, invalid values, and conflicting duplicate calls or
results before a provider integration can use those tools.
**Proposed solution**
Add a serialized provider tool bridge. Validate the authorized catalog
and its JSON Schemas. Validate each call and result. Keep pending and
completed identities so retries are idempotent and conflicts fail
closed.
**Alternatives considered**
Trusting provider arguments would bypass the run-scoped catalog.
Validating only in TypeScript would leave the Rust process without a
recovery-safe authorization boundary. Adding provider behavior in this
pull request would make the review unit too broad.
**Roadmap alignment**
This adds a package-local safety boundary for the Codex-first runner
path. It does not enable a new adapter or change an existing direct
adapter path.
## What Changed
- Added the versioned authorized-tool, pending-call, and result
contracts.
- Added canonical SHA-256 catalog binding and drift rejection.
- Added JSON Schema compilation and input and response validation.
- Added duplicate-call and duplicate-result idempotency with conflict
rejection.
- Added bounds for catalogs, schemas, values, and retained call
identities.
- Added the Rust `jsonschema` dependency and its Cargo lock entries.
- Added focused tests for authorization, recovery, envelopes, bounds,
and conflicts.
## Verification
- `cargo fmt --manifest-path packages/paperclip-runner/runner/Cargo.toml
--all -- --check`
- `cargo test --manifest-path
packages/paperclip-runner/runner/Cargo.toml -p paperclip-runner-core`
(64 tests)
- `cargo clippy --manifest-path
packages/paperclip-runner/runner/Cargo.toml -p paperclip-runner-core
--all-targets -- -D warnings -A clippy::manual_is_multiple_of -A
clippy::filter_map_bool_then`
- `pnpm -r typecheck`
- `pnpm build`
- The repository test runner also reached unrelated server worktree
suites. Those suites fail on the current macOS worktree with database
deadlocks and filesystem fixture assumptions. This pull request does not
change those files. The applicable GitHub checks remain the handoff
authority.
## Risks
The main risks are accepting a tool that the run did not authorize and
replaying a conflicting provider result. The bridge validates the
catalog, operation identity, JSON Schema, call identity, and result
identity before it changes durable state. The new Cargo dependency is
package-local. This pull request changes no GitHub workflow and no pnpm
lockfile.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The runner package now has a Codex-only native backend
> - A native Codex process needs an isolated runtime context before it
can start safely
> - Assigned skills, local authentication, and MCP bindings cross
separate trust boundaries
> - Runtime materialization must reject symlink escapes and unsafe
remote bindings
> - This pull request adds the package-local Codex runtime context
boundary
> - It does not start runnerd or enable the Paperclip Runner adapter
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` Codex runtime context materialization.
**Problem or motivation**
The runner needs a private Codex home for each native session. It must
stage only assigned skills, copy local Codex authentication safely, and
validate native MCP bindings before it exposes them to the child
process.
**Proposed solution**
Create an isolated runtime directory. Validate the skill tree before and
after copying it. Make staged skill files read-only. Read authentication
through a no-follow file descriptor with a size bound. Accept only HTTPS
or loopback MCP endpoints and bounded tokens.
**Alternatives considered**
Using the operator Codex home directly would expose unrelated state and
skills. Following symlinks while copying skills or authentication could
escape the assigned source. Accepting arbitrary MCP URLs could send a
bearer token to an untrusted endpoint.
**Roadmap alignment**
This adds a package-local safety boundary for the reviewed Codex runner
path. It does not enable a new adapter or change an existing direct
adapter path.
## What Changed
- Added the native MCP binding contract and strict validation.
- Added isolated Codex home materialization with shell snapshots
disabled.
- Added assigned-skill staging with lexical containment and two-pass
symlink checks.
- Added read-only permissions for staged skill trees.
- Added owner-only authentication staging with no-follow reads and a
size bound.
- Added cleanup for complete and partially materialized runtime
directories.
## Verification
- The focused runtime context suite has 7 passing cases.
- `pnpm --filter @paperclipai/paperclip-runner test:typescript` (36
files, 351 tests)
- `pnpm -r typecheck`
- `pnpm build`
## Risks
The main risks are filesystem escape, secret exposure, and token
delivery to an unsafe endpoint. The materializer rejects symlinks before
and after skill copying, resolves existing source paths, reads
authentication with `O_NOFOLLOW`, applies private permissions, and
restricts MCP URLs to HTTPS or loopback hosts. Existing direct adapters
do not use this package-local runtime context.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The runner package now has a complete Codex session driver
> - The driver needs a package-owned construction boundary before server
code can use it
> - Persisted provider contracts must not make deferred providers
executable
> - Provider selection must fail closed when an implementation is not
included
> - This pull request adds a Codex-only native backend and factory
> - It does not expose or enable the Paperclip Runner adapter
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` native backend construction.
**Problem or motivation**
The runner needs one normalized backend seam that constructs the
reviewed Codex driver. The seam must not route OpenCode, ACPX, Claude
Managed, or AWS AgentCore through an incomplete fallback.
**Proposed solution**
Add a Codex backend constructor and a Codex-first factory. Reject every
deferred provider at the factory and provider-specific constructor
boundaries.
**Alternatives considered**
Routing all provider contracts through the Codex protocol facade would
give deferred providers runtime behavior before their implementations
are reviewed. Including all provider backends would also broaden this
pull request beyond the Codex-first series.
**Roadmap alignment**
This connects reviewed runner package layers. It does not enable a new
adapter or change an existing direct adapter path.
## What Changed
- Added the Codex native backend constructor.
- Added the Codex-first native backend factory.
- Preserved the execution contract, runtime instructions, plan
constraints, dynamic tools, transport injection, and durable identity
requirements.
- Rejected every deferred provider with an explicit error.
- Added tests for lazy transport construction and both fail-closed
boundaries.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript` (35
files, 340 tests)
- `pnpm -r typecheck`
- `pnpm build`
- The focused native backend factory suite has 3 passing cases.
## Risks
The main risk is starting the wrong provider or starting a provider
before its runtime is ready. The factory and Codex constructor both
reject non-Codex inputs. Existing direct adapters do not call this
package-local factory.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The package now has bounded Codex transport, security, question,
diff, value, and thread helpers
> - Those isolated boundaries can now be composed into one provider
session lifecycle
> - The driver must preserve controller-owned identity, results,
terminals, and recovery invariants
> - Unsupported or mismatched provider traffic must fail closed without
weakening legacy adapters
> - This pull request adds only the Codex app-server driver and its
package-local tests
> - It does not expose or enable the Paperclip Runner adapter
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` Codex app-server session driver.
**Problem or motivation**
The runner needs a production-shaped Codex session implementation that
turns provider facts into canonical PRP events while keeping task
identity, semantic completion, runtime input, and recovery under
controller authority.
**Proposed solution**
Compose the previously reviewed transport and normalization boundaries
into a Codex-only harness driver with session open/resume, turns,
streaming events, semantic tools, structured questions, goals, lineage,
usage, cancellation, reconciliation, and deterministic persisted
snapshots.
**Alternatives considered**
Keeping the full implementation in one initial transport pull request
would obscure the trust boundaries. Adding the deferred ACPX or OpenCode
paths here would also broaden the provider scope beyond the Codex-first
series.
**Roadmap alignment**
This implements the Codex provider slice inside the package. It does not
enable the runner adapter or change any existing direct adapter path.
## What Changed
- Added the Codex app-server harness driver and session lifecycle.
- Added controller-bound semantic completion and terminal handling.
- Added runtime requests, structured questions, goals, lineage, usage,
steering, interruption, and recovery.
- Added workspace diff and file-reference projection.
- Connected bounded/redacted provider data and notification identity
checks.
- Kept deferred provider identities and replacement behavior out of the
Codex-only driver.
- Added 62 focused driver cases covering lifecycle, security, recovery,
and protocol failures.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript` (34
files, 337 tests)
- `pnpm -r typecheck`
- `pnpm build`
- The focused Codex driver suite has 62 passing cases.
## Risks
The main risks are accepting provider events from the wrong session,
duplicating terminal facts, retaining unsafe provider data, or resuming
a different session. Tests cover pre-turn, cross-thread, stale-turn,
post-terminal, duplicate-result, cancellation, transport loss, provider
identity, workspace, redaction, structured input, and recovery cases.
## Model Used
OpenAI Codex with GPT-5.6 and repository tool use.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Codex driver needs a controller-owned oracle for semantic
completion and replay
> - Provider proposals are advisory and must satisfy the exact task
envelope
> - Persisted events must be bounded and validated before deterministic
replay
> - Live provider behaviors also need one checked-in, schema-validated
fixture
> - This pull request adds that test and conformance layer before the
full driver
> - The runner adapter remains disabled and no production execution path
changes
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` Codex trace, result-validation, and replay
conformance.
**Problem or motivation**
A provider-completed turn is not sufficient authority to finalize a
Paperclip run. Results must match the controller-owned completion
contract, and persisted provider events must be validated before they
can rebuild controller state.
**Proposed solution**
Add a bounded Codex trace harness that validates result proposals, emits
controller decisions and terminals, verifies live/replay parity, and
rejects malformed persisted streams. Add a validated fixture for runtime
requests, goals, lineage, controls, reconnect identity, and redaction
cases.
**Alternatives considered**
Embedding these assertions only in the production driver would mix
controller authority with provider transport behavior and make
deterministic replay harder to review.
**Roadmap alignment**
This supports the Codex-first experimental runner. It does not enable
the runner adapter or add another provider.
## What Changed
- Added exact task-envelope result validation.
- Added bounded persisted-event validation and deterministic replay.
- Added a controller-owned Codex trace harness and parity assertions.
- Added and validated the checked-in Live console conformance fixture.
- Updated the generated protocol manifest with the fixture source.
- Added focused result and fixture tests.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- The focused trace-conformance test has 2 passing cases.
## Risks
The main risks are accepting a mismatched semantic result or replaying
corrupted provider history. Validation covers schema, contract revision,
criteria identity, disposition invariants, event identity, uniqueness,
ordering, terminal count, and byte limits.
## Model Used
OpenAI Codex with GPT-5.6 and repository tool use.
## 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Runner replies can refer to files produced inside an assigned
workspace
> - The task page needs stable file metadata without trusting arbitrary
Markdown paths
> - File verification must stay within the canonical workspace even
through symlinks
> - Reads and previews also need strict count and byte bounds
> - This pull request adds that provider-neutral file-reference boundary
> - A later pull request will connect it to the Codex session driver
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` workspace file-reference discovery.
**Problem or motivation**
Assistant-authored Markdown can contain external, absolute, escaping, or
symlinked paths. Reading those paths directly could disclose files
outside the assigned workspace or retain unbounded content.
**Proposed solution**
Parse a bounded set of local Markdown references, normalize them
relative to the workspace, verify canonical paths before reading, reject
symlink escapes, and retain bounded previews plus content digests.
**Alternatives considered**
Leaving path handling inside a provider driver would duplicate a
security-sensitive boundary and make it harder to test independently.
**Roadmap alignment**
This supports the Codex-first experimental runner and future
provider-neutral task projection. It does not enable the runner adapter.
## What Changed
- Added stable workspace file-reference records.
- Added local Markdown link extraction and path normalization.
- Added canonical-path and symlink-escape checks.
- Added bounded file reads, previews, and SHA-256 digests.
- Added focused path, preview, and symlink tests.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- The focused workspace-reference test has 3 passing cases.
## Risks
The main risk is reading outside the assigned workspace or retaining
excessive data. Tests cover absolute and external paths, symlink
escapes, preview bounds, and deterministic metadata.
## Model Used
OpenAI Codex with GPT-5.6 and repository tool use.
## 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
Dotta
Nicky Leach
Michael Nguyen
Devin Foley
dependabot[bot]
scotttong
Zannis Kalampoukis
