## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies.
> - Heartbeats wake agents and resume prior adapter task sessions so
work is continuous.
> - A persisted task session can contain adapter-specific state (for
Codex, a resumable thread/session) created under the agent's
then-current model.
> - When an operator changes an agent's configured model, the next run
should not blindly reuse a session created under a different model —
context window, capabilities, and prompt assumptions may differ.
> - The existing wake reset logic handles wake reasons
(forceFreshSession, comment wakes, etc.) but not model drift between
current agent config and persisted task-session metadata.
> - This pull request adds model-aware task-session reset and persists
the configured model into task-session metadata.
> - The benefit is that heartbeat runs reliably honor the current agent
model configuration and avoid stale session/model mismatches.
## Linked Issues or Issue Description
**What happened?**
After an operator changes an agent's configured model (for example,
swapping a Codex agent from one model variant to another), the heartbeat
reuses the persisted adapter task session that was created under the
previous model. The new model never takes effect on resume — the run
continues on the prior session and prior model assumptions.
**Expected behavior**
A model change in agent configuration should invalidate the persisted
task session for that agent and force a fresh session start on the next
run, so the configured model is the one actually used.
**Steps to reproduce**
1. Run an agent with model `A` so it persists an adapter task session
under model `A`.
2. Change the agent's configured model to `B`.
3. Trigger a heartbeat for the same issue/agent.
4. Observe: the run resumes the prior task session (still under model
`A`) instead of starting fresh under model `B`.
## What Changed
- Added task-session model metadata support in heartbeat session
handling via `__paperclipConfiguredModel`.
- Persisted the current configured adapter model into
`agent_task_sessions.sessionParamsJson` whenever heartbeat upserts
task-session state.
- Added `shouldResetTaskSessionForModelChange(...)` to explicitly detect
model drift between current config and persisted session metadata.
- Updated run startup logic to force a fresh session when model drift is
detected, with a clear reason message in runtime warnings.
- Strips the internal `__paperclipConfiguredModel` key from
`sessionParamsJson` before it is forwarded to adapters so the metadata
stays internal.
- Added focused tests in
`server/src/__tests__/heartbeat-workspace-session.test.ts` covering
model-drift reset behavior, non-reset cases, and the strip helper.
## Verification
- `pnpm --filter @paperclipai/server test
src/__tests__/heartbeat-workspace-session.test.ts`
- `pnpm --filter @paperclipai/server typecheck`
## Risks
Low. Sessions without persisted model metadata are not reset (backward
compatible). The model key is namespaced (`__paperclip...`) to avoid
colliding with adapter-forwarded params. Drift detection only fires when
both current config and persisted metadata are present and differ.
## Model Used
Claude (Opus 4.6) — used to design the metadata persistence, add the
drift detection helper, and write unit coverage.
## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots (N/A — no UI changes)
- [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 (in progress)
- [ ] 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>
Co-authored-by: Devin Foley <devin@paperclip.ing>
Nir Arazi
b853ce5183