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