## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Native Runner executions can be suspended, for example by a server
restart, and then resumed from their saved admitted input
> - On resume, runtime selection checks that every saved skill in the
admitted runtime context is still available
> - The check treated a permitted skill whose saved version could not be
prepared on this host the same as a skill the agent can no longer read
> - The run failed as `configuration_incomplete` with "Project skill
access changed while this execution was suspended", the task went to the
board, and the real preparation error was lost
> - This pull request separates the two cases: an absent saved skill is
still an access change, and a present skill with a missing source fails
with its actual preparation detail
> - The benefit is a correct failure message and recovery route, and a
recorded cause for the underlying preparation fault
## Linked Issues or Issue Description
**What happened?**
Two resumed native runs on staging failed right after a server restart
with `ConfigurationIncompleteFailure: Project skill access changed while
this execution was suspended. Restore access or start a new execution.`
Skill access did not change. The first attempt of each run prepared all
four saved skills. After the restart, the resumed attempt failed. The
tasks went to board recovery with a "secret is not set" next action and
stayed blocked.
**Expected behavior**
Preparation already refuses a saved skill that the agent can no longer
read ("A pinned skill is unavailable or no longer permitted"). So, at
the resume guard, a saved skill that is absent from the current entries
is an access change. A saved skill that is present but whose source is
`missing` had a preparation failure (cache, storage or materialization).
That run must fail with the actual `missingDetail`, as a fresh admission
does in `materializeSelectedSkills`. It must not claim an access change.
**Steps to reproduce**
1. Admit a native run whose saved `skillVersions` pin a skill.
2. Resume it with the same skill entry, but with `sourceStatus:
"missing"` and a materialization `missingDetail`.
3. Before this change, the resume rejects with
`ConfigurationIncompleteFailure` "Project skill access changed".
## What Changed
- `selectHeartbeatRuntime` resume guard: a saved skill that is absent
from the current runtime skill entries still raises
`skill_access_changed`.
- A saved skill that is present with `sourceStatus: "missing"` now
throws a plain error that names the skill key and its preparation
detail. The admitted revision and saved skill pins stay unchanged.
- Regression test for both the unprepared case (red before, green after)
and the available case. The existing revoked-access test is unchanged
and still passes.
## Verification
- `cd server && npx vitest run
src/services/heartbeat/runtime-selection.test.ts`: 92 passed. The new
`missing` case failed before the fix with `expected
ConfigurationIncompleteFailure ... to not be an instance of
ConfigurationIncompleteFailure`.
- `cd server && npx vitest run
src/__tests__/heartbeat-runtime-skills.test.ts
src/__tests__/heartbeat-execution-configuration.test.ts`: 56 passed.
- `pnpm run typecheck` (server): passed.
- The broad `pnpm verify` selection did not finish within the local time
limit. Required CI supplies that coverage.
## Risks
- Low risk. The change is in one guard. Real access revocation keeps its
existing error and board route.
- An unprepared skill on resume now follows the ordinary failed-run path
(`adapter_failed`) instead of `configuration_incomplete`. This is the
same as a fresh admission with a missing skill source.
- This change does not fix the underlying host-side preparation fault.
It records its actual cause so that the next occurrence identifies it.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution,
through Claude Code.
## 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: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>