Files
PaperClipAI/packages
DottaandClaude Opus 5.5 c5e4b46d3f fix(acpx): shut down the per-port ACPX runtime when its session closes (#21151)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The experimental Runner starts ACP providers through ACPX, and each
runtime port owns one ACPX runtime
> - When the native provider dies during a turn, the port retires the
turn at once, but the turn stays queued inside the ACPX runtime
> - `port.close()` closed only the session handle, so that queued turn
wrote its final session record after close had returned
> - Any caller that removes the state directory after close races that
write; CI showed it as `ENOTEMPTY ... state/sessions` in an unrelated
test on 5 branches
> - This pull request makes close shut down the port's own ACPX runtime
after the session closes, inside the existing close bound
> - The benefit is that a closed port no longer writes into its state
directory, and the flaky test is fixed at its cause

## Linked Issues or Issue Description

**What happened?**
`packages/paperclip-runner` test `native-distribution-integrity.test.ts
> native ACPX execution closure > expires a real ACPX permission on
native child death without replaying its mutation` fails intermittently
with `Error: ENOTEMPTY: directory not empty, rmdir
'/tmp/native-acpx-test-XXXX/state/sessions'`. It failed 5 times on 5
unrelated branches in 48 hours.

**Steps to reproduce**
1. Run the test 30 times while two CPU-bound shell loops run.
2. 2 of 30 runs fail with ENOTEMPTY in `afterEach`.
3. Instrumenting the session store shows a `saveSessionOwner` write from
`finalizeRuntimeTurn` that starts after `port.close()` and `afterEach`
have begun.

**Paperclip version or commit**
`master` at the base of this branch (CI on unrelated pull requests,
2026-11-10 to 2026-11-12).

**Expected behavior**
After `port.close()` resolves, the ACPX runtime owned by that port does
no more work and writes no more state.

**Actual behavior**
The turn that native provider death retired is still queued in the ACPX
runtime manager. It finalizes after close and writes the session file
while the caller removes the directory.

## What Changed

- `acpx-runtime-adapter.ts`: after the final successful close, the port
calls `runtime.shutdown()` within `runtimeCloseTimeoutMs`. ACPX shutdown
waits for its pending turn tasks, so the abandoned turn finishes its
writes first.
- A close that succeeds late, after its bound, also starts the shutdown.
A concurrent or repeated `close()` waits for the same shutdown and gets
its failure too. A shutdown failure is reported in the existing `ACPX
runtime and provider cleanup failed` error. The shutdown attempt stays
in the retained cleanup owners.
- `acpx-runtime-adapter.test.ts`: regression tests. Close does not
resolve before runtime shutdown settles. A shutdown failure is reported
to every closer. A late close success starts the shutdown.

## Verification

- Red/green: both new tests fail on master (`expected "vi.fn()" to be
called once, but got 0 times`; `promise resolved "undefined" instead of
rejecting`) and pass with this change.
- Loop of the flaky test, 30 runs each, with 2 extra CPU-bound shell
loops on an already loaded 18-core Mac (load average about 30):
  - Before: 28 pass, 2 fail (both `ENOTEMPTY ... state/sessions`).
  - After: 30 pass, 0 fail.
- `npx vitest run src/drivers/acpx` in `packages/paperclip-runner`: 92
files, 1743 tests pass.
- `tsc --noEmit -p packages/paperclip-runner`: clean.

## Risks

- Low risk. The runtime is created per port and is not used after a
successful final close. Close can now take up to one more close bound if
the runtime's pending work is slow. A late reconciliation close never
runs after this point, because shutdown only starts when the port is
finally closed.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits) and extended reasoning.

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

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 12:29:36 -06:00
..