## Thinking Path
> - Paperclip uses durable task sessions so local adapters can resume
work across sequential heartbeat runs.
> - `execution_review_requested` and `execution_changes_requested` are
issue-local execution-policy handoffs, not new task assignments.
> - The existing `agent_task_sessions` lookup, adapter session codec,
workspace resolution, and effective config freshness checks already
decide whether reuse is safe.
> - Treating those two handoff wake reasons as unconditional
fresh-session boundaries discards a valid saved task session before
adapter resume can be attempted.
> - This makes Dev → CodeReview → Dev loops repeatedly cold-start even
when task, issue, agent, adapter, workspace, and config identity are
unchanged.
> - The fix is to let normal review/change-request handoffs reach the
durable task-session path while preserving explicit fresh-session and
unsafe-boundary resets.
## Linked Issues or Issue Description
Fixes#8246.
cc @cryppadotta — this is the narrow handoff-session policy change
discussed there: normal `execution_review_requested` /
`execution_changes_requested` wakes no longer force a fresh task session
by wake reason alone, while assignment, approval, review-participant
recovery, timer wakes, explicit `forceFreshSession`, and
config/workspace/model/session freshness still keep their safety
boundaries.
## What Changed
- Removed normal `execution_review_requested` and
`execution_changes_requested` from the unconditional task-session reset
policy.
- Kept fresh-session boundaries for:
- `issue_assigned`
- `execution_approval_requested`
- `execution_review_participant_recovery`
- `heartbeat_timer`
- explicit `forceFreshSession`
- existing config/model/workspace/session freshness reset paths
- Updated heartbeat session-policy tests so execution handoffs are
resume-eligible by wake reason alone.
- Preserved PF-4 timer-wake behavior and its explicit reset reason.
## Verification
- `npx pnpm@9.15.4 exec vitest run
server/src/__tests__/heartbeat-workspace-session.test.ts
server/src/__tests__/heartbeat-timer-wake-session-reset-pf4.test.ts
server/src/__tests__/codex-local-execute.test.ts
server/src/__tests__/issue-comment-reopen-routes.test.ts
--reporter=verbose` — 220 tests passed.
- `npx pnpm@9.15.4 --filter @paperclipai/server typecheck` — passed.
- `git diff --check` — passed.
- `coderabbit review --agent -t committed --base origin/master` — 0
findings.
## Risks
- Moderate behavior change in session-boundary policy: normal
review/change-request handoffs may now reuse a saved per-task session
when the existing identity/freshness checks pass.
- Safety boundaries remain in place for new assignments, approval gates,
review-participant recovery, timer/discovery wakes, explicit
fresh-session requests, and config/model/workspace/session drift.
- If a saved session is stale or incompatible, existing freshness/resume
fallback behavior still handles reset/fresh execution.
> For core feature work, check 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.5. Tool use and local verification 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
- [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 — N/A,
server policy/test-only change
- [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: santastabber <184111696+santastabber@users.noreply.github.com>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents make progress in heartbeats: the server wakes an agent
session, it does a slice of work on an issue, records a disposition, and
exits
> - Benchmarking identical coding tasks run as Paperclip-orchestrated
agent pairs vs invoking the same agent harness directly measured a
1.8–2.2× wall-clock slowdown for the Paperclip pairs, dominated by
per-heartbeat orchestration overhead rather than model time
> - Two contributors stood out: (1) since PF-4 (#4838) every
`heartbeat_timer` wake starts a brand-new task session, so continuation
work on a specific issue repays the full session-start and
re-orientation cost on every heartbeat; (2) in degraded environments
agents burn many tool calls retrying the same failing control-plane
write before giving up
> - This pull request reuses the task session for issue-scoped timer
wakes (keeping the PF-4 fresh-session rule only for unscoped exploratory
wakes, which were the original context-bloat case) and adds a
bounded-retry rule to the wake prompt and core skill: after 2
consecutive failures of the same control-plane write, stop retrying it
for the rest of the heartbeat and rely on the adapter/runtime status
channel
> - The benefit is materially less wall-clock and token overhead per
heartbeat while preserving the context-bloat protection PF-4 was added
for
## Linked Issues or Issue Description
Refs #4838 (merged PF-4 change whose reset rule this refines), Refs
#5287, Refs #1907 (related timer-heartbeat session work).
No public GitHub issue exists for the slowdown itself; bug-report
fields:
- **What happened:** Agent pairs orchestrated through Paperclip
heartbeats complete identical task sets 1.8–2.2× slower (wall-clock)
than the same harness invoked directly. Profiling attributed the gap to
per-heartbeat orchestration overhead: every timer wake discards the task
session (full session start + re-orientation), and in degraded
environments agents repeatedly retry the same failing control-plane
write.
- **Expected behavior:** Heartbeat orchestration should add minimal
wall-clock overhead on top of the underlying harness; issue-scoped
continuation work should not pay a fresh-session tax each interval.
- **Steps to reproduce:** Run a fixed benchmark task set once through
Paperclip issue heartbeats and once via direct harness invocation with
the same model/config; compare wall-clock totals.
- **Version/commit:** master @ 3d23c3b2c3, self-hosted deployment.
## What Changed
- `server/src/services/heartbeat.ts`: `shouldResetTaskSessionForWake`
now resets only for `heartbeat_timer` wakes with no derivable task key
(unscoped exploratory wakes). Issue-scoped timer wakes reuse the issue's
task session. `describeSessionResetReason` updated to stay in exact
agreement.
- `server/src/__tests__/heartbeat-timer-wake-session-reset-pf4.test.ts`:
new cases for scoped vs unscoped timer wakes, plus the scoped case added
to the reset/reason agreement invariant.
- `packages/adapter-utils/src/server-utils.ts`: wake prompt template and
execution contract gain a bounded-retry rule — after 2 consecutive
failures of the same control-plane write, stop retrying it for the rest
of the heartbeat, continue useful work, report the failure in the final
response, and use the adapter/runtime status channel as the sanctioned
fallback.
- `packages/adapter-utils/src/server-utils.test.ts`: asserts the new
prompt lines are present in both the template and the rendered wake
prompt.
- `skills/paperclip/SKILL.md`: documents the same bounded write-retry
rule in the core Paperclip skill.
## Verification
- `node_modules/.bin/vitest run
packages/adapter-utils/src/server-utils.test.ts` — 1 file, 83 tests
passed
- `cd server && node_modules/.bin/vitest run
src/__tests__/heartbeat-timer-wake-session-reset-pf4.test.ts` — 1 file,
14 tests passed
- Both run on this branch rebased onto current master (3d23c3b2c3)
## Risks
- Behavioral shift: issue-scoped timer wakes now reuse sessions, so a
long-lived issue session can grow across heartbeats. Mitigated by
keeping the PF-4 reset for unscoped wakes (the originally observed bloat
case) and by existing session compaction.
- Prompt/skill text changes alter agent guidance; the new rule is scoped
narrowly to repeated failures of the same control-plane write.
- No migrations, no API or schema changes, no dependency changes.
## Model Used
- Claude (Anthropic) — `claude-fable-5` (Fable 5), extended reasoning
with tool use, driven via Claude Code / Claude Agent SDK.
## 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 orchestrates AI agents for zero-human companies
> - Each agent is woken via the heartbeat scheduler — `heartbeat_timer`
for periodic interval wakes, `issue_assigned` / `execution_*` /
`issue_commented` for event-driven wakes
> - The heartbeat reuses the prior task session by default; only
specific wake reasons trigger a fresh session via
`shouldResetTaskSessionForWake` (assignment, review, approval,
changes-requested) or explicit `forceFreshSession`
> - In CEO run `292a5fd1`, repeated context compaction warnings appeared
near the 64k threshold for the long-lived manager session — symptomatic
of repeated `heartbeat_timer` wakes accumulating low-value "checked,
nothing new" inbox-scan traces inside one ever-growing session
> - PF-4 in the 2026-04-16 hangeul-school operational issue set asks for
a compaction-aware session freshness policy: "manager sessions can
rotate before low-value compaction pressure accumulates" and "repeated
timer wakes do not indefinitely bloat the same session"
> - This pull request adds `wakeReason === "heartbeat_timer"` to both
`shouldResetTaskSessionForWake` and `describeSessionResetReason`, so
each interval wake starts fresh and the run log explicitly records why.
Event-driven wakes (`issue_commented`, `transient_failure_retry`, etc.)
keep their existing reuse behavior.
> - The benefit is that timer wakes — which are exploratory and carry no
continuation state — stop bloating long-lived manager sessions.
Compaction pressure that previously accumulated across N timer wakes is
now bounded to a single interval's worth of context.
## Linked Issues or Issue Description
No external GitHub issue is linked. Describing the problem inline
following the bug-report template:
**What happened:** Long-lived manager/CEO agent sessions hit the 64k
context-compaction threshold after many `heartbeat_timer` wakes
accumulated low-value inbox-scan traces inside one ever-growing task
session. Reproduced in CEO run `292a5fd1`.
**Expected behavior:** Periodic timer wakes — which carry no
continuation state — should not indefinitely bloat the same session. The
heartbeat should rotate sessions on timer wakes the way it already does
on assignment/review/approval/changes-requested wakes.
**Actual behavior:** `shouldResetTaskSessionForWake` only reset on
`issue_assigned`, `execution_review_requested`,
`execution_approval_requested`, `execution_changes_requested`, or
explicit `forceFreshSession`. `heartbeat_timer` reused the prior session
indefinitely, causing compaction pressure.
**Scope of fix:** Add `heartbeat_timer` to the reset list and to
`describeSessionResetReason` so the run log records why. Event-driven
wakes keep their existing reuse behavior.
## What Changed
- `shouldResetTaskSessionForWake` (`server/src/services/heartbeat.ts`)
now also returns `true` when `wakeReason === "heartbeat_timer"`. The
existing reset reasons (`issue_assigned`, `execution_review_requested`,
`execution_approval_requested`, `execution_changes_requested`,
`forceFreshSession`) are unchanged.
- `describeSessionResetReason` returns a paired explanation `"wake
reason is heartbeat_timer (timer-driven wake starts fresh)"` so run logs
make session reset behavior legible.
- `describeSessionResetReason` was promoted from internal to `export` so
the paired contract can be unit-tested directly alongside
`shouldResetTaskSessionForWake`. This is the only API surface change in
this PR.
Wake reasons whose reuse behavior is intentionally **unchanged**:
- `issue_commented` — the comment is the reason to engage; continuation
context matters
- `issue_comment_mentioned` — same rationale
- `transient_failure_retry` — resuming a previously-failed run; want
continuity
- `process_lost_retry` — resuming after process loss; want continuity
- `missing_issue_comment`, recovery reasons — out of scope; can be
revisited as follow-ups if observed bloat shows up
## Verification
```bash
cd server
pnpm vitest run src/__tests__/heartbeat-timer-wake-session-reset-pf4.test.ts
# 12/12 pass
pnpm vitest run \
src/__tests__/heartbeat-stale-queue-invalidation.test.ts \
src/__tests__/heartbeat-process-recovery.test.ts \
src/__tests__/heartbeat-comment-wake-batching.test.ts
# 48/48 adjacent heartbeat tests pass
```
The 12 new tests assert:
1. `shouldResetTaskSessionForWake` resets on `heartbeat_timer`
2. `shouldResetTaskSessionForWake` still resets on the four existing
reasons
3. `forceFreshSession === true` still triggers reset
4. `issue_commented`, `transient_failure_retry`, unknown reasons, and
null/undefined context do **not** trigger reset
5. `describeSessionResetReason` describes `heartbeat_timer` explicitly
so logs are legible
6. `describeSessionResetReason` keeps the exact wording for the four
existing reasons
7. `describeSessionResetReason` returns the `forceFreshSession` message
8. `describeSessionResetReason` returns `null` for non-resetting reasons
9. **Parity invariant**: the two functions agree on every input —
`describeSessionResetReason(ctx)` is non-null iff
`shouldResetTaskSessionForWake(ctx)` returns true. This locks the pair
so future changes to one must update the other.
## Risks
- **Low–medium.** This changes behavior for every `heartbeat_timer` wake
on every agent: the prior task session is no longer reused.
- For **manager / CEO agents** (the documented case): this is the
intended improvement. Timer wakes carry no continuation state for these
roles.
- For **worker agents** that may have used timer wakes to resume
in-flight work: any genuine continuation should already be triggered by
issue/execution wake reasons (which still reuse) or by an active
checkout being resumed via `process_lost_retry` /
`transient_failure_retry`. Timer wakes themselves do not create
checkouts.
- If a deployment relied on timer wakes to preserve mid-task context —
which is fragile by design — the right path is to switch to a non-timer
wake reason or accept the reset. The PR doesn't add a new opt-out flag
because the goal is to bound session size; introducing an opt-out would
re-open the bloat path this PR is closing.
- No schema or API surface change beyond exporting
`describeSessionResetReason`. No migration. No client-visible API
change.
## Model Used
Claude Opus 4.7 (1M context), model ID `claude-opus-4-7[1m]`. Used in
interactive Claude Code session with extended reasoning, tool use
(Read/Edit/Write/Bash), and verification gates between exploration → fix
→ tests → push.
## 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 the open PR list for similar/duplicate work —
distinct from #4080 (force-fresh follow-up wake — codex/general) and
#4195 (codex session reset on model change); this PR specifically
targets the `heartbeat_timer` reuse path
- [x] I have run tests locally and they pass (12 new + 48 adjacent = 60
tests, no regressions)
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots — N/A, server-only change
- [x] I have updated relevant documentation to reflect my changes — none
needed; the new export carries clear semantics and the run log message
is self-explanatory
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Irene <irene@users.noreply.github.com>
Co-authored-by: Devin Foley <devin@devinfoley.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Devin Foley <devin@paperclip.ing>
santastabber
Dotta
Reasonofmoon