## Thinking Path
> - Paperclip is the control plane that coordinates autonomous agent
work.
> - Agents need to collaborate on issues beyond their current
assignment.
> - Cross-issue comments and updates are useful, but an unbounded run
can create cascading side effects.
> - The control plane must preserve company-wide collaboration while
containing each run's influence.
> - Comment attribution must also show the responsible user and the
acting agent in audits.
> - This pull request adds run-bound cross-issue containment,
attribution, and agent-class wake rules.
> - The benefit is safer collaboration without restoring issue-assignee
ownership restrictions.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
Agent-authenticated issue comments, updates, reopen behavior, and
assignee wake routing.
**Subsystem affected**
Cross-cutting: server routes and services, shared contracts, database
schema and migration, and implementation documentation.
**Current behavior**
An authenticated agent can collaborate across company issues, but one
heartbeat run has no per-run side-effect boundary. Comment records also
do not persist the responsible user separately from the acting agent.
**Proposed behavior**
Require a valid heartbeat run for agent cross-issue comments and
updates. Audit each attempt and cap a run at 20 cross-issue effects.
Keep the cap in log-only mode until it automatically changes to
enforcement at 2026-08-11 00:00 UTC. Preserve same-issue writes. Use
agent-class wakes for agent comments. Keep same-run completion comments
from reopening completed work. Record the responsible user on
agent-authored comments and activity.
**Reason and benefit**
Agents can collaborate on other issues without an assignment gate, while
each run has an atomic and inspectable side-effect limit. Operators can
identify both the acting agent and the responsible user.
**Breaking changes**
After 2026-08-11 00:00 UTC, the twenty-first cross-issue comment or
update from one heartbeat run returns a containment error. Agent
cross-issue writes without valid run context are rejected. The migration
is additive and backfills existing agent-authored comment attribution
where the source data is available.
## What Changed
- Added an atomic per-run counter for cross-issue agent comments and
updates.
- Added audit events for allowed and rejected cross-issue effects.
- Added the automatic log-only to enforcement flip at 2026-08-11 00:00
UTC.
- Added responsible-user attribution to agent-authored comments,
activity records, shared types, and validators.
- Added an additive migration and migration coverage for existing
comments.
- Updated reopen, resume, and wake behavior so agent comments create
agent-class wakes and same-run completion comments remain inert.
- Updated the implementation specification and regression coverage.
## Verification
- `pnpm exec vitest run
server/src/__tests__/cross-issue-influence-limit.test.ts
server/src/__tests__/issue-comment-attribution-audit-routes.test.ts
server/src/__tests__/issue-comment-reopen-routes.test.ts
packages/db/src/issue-comment-on-behalf-migration.test.ts` — 97 tests
passed.
- `pnpm -r typecheck` — passed, including migration safety checks.
- `pnpm test:run` — server batch: 3,364 passed and 2 skipped; UI batch:
3,504 passed. One unrelated CLI doctor test warned because this agent
runtime injects static AWS credentials.
- `env -u AWS_ACCESS_KEY_ID -u AWS_SECRET_ACCESS_KEY pnpm exec vitest
run cli/src/__tests__/secrets.test.ts` — 8 tests passed and confirmed
the CLI failure was ambient-environment sensitive.
- `pnpm build` — passed.
## Risks
- The fixed enforcement timestamp changes production behavior
automatically on 2026-08-11 00:00 UTC. Audit logs before that time
provide rollout visibility.
- The per-run counter serializes on the heartbeat-run row. This prevents
concurrent attempts from racing past the cap but adds a small lock scope
for cross-issue writes.
- Existing comments can only be backfilled when their acting run or
agent attribution is recoverable.
> For core feature work, check [`ROADMAP.md`](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 in the Codex agent runtime. The runtime did not expose a
context-window size. Reasoning, shell tools, code editing, and test
execution 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 (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 is the open source control plane people use to coordinate
AI agents and their work
> - Heartbeat admission decides when an agent should start another
adapter session for an issue
> - After process-loss recovery, assignment pollers and reconcilers can
repeatedly request another wake while the issue remains `in_progress`
> - When the preceding runs succeeded without issue-visible progress,
those event-free wakes provide no new information but still pay the full
cost of an adapter session
> - Existing liveness evidence is too broad for this case because
workspace tool calls can make a run look active without moving the issue
> - This pull request adds an issue-scoped admission throttle for
consecutive no-progress re-wakes while preserving every wake that
carries new information or recovery intent
> - The benefit is bounded recovery cost without delaying comments,
operator actions, failures, or other meaningful events
## Linked Issues or Issue Description
No public GitHub issue exists for this bug.
**What happened?**
After a process died, external wake drivers could re-wake the same agent
for the same `in_progress` issue every few seconds. Each succeeded run
that produced no issue-visible progress could be followed by another
full adapter session despite no new issue input. In the observed
recovery smoke, one recovery consumed 25 sessions and 2.4× the
direct-run cost.
**Expected behavior**
Repeated event-free re-wakes should back off after consecutive
successful runs produce no issue-visible progress. Any new information,
explicit operator intent, or failed-run recovery should continue
immediately.
**Steps to reproduce**
1. Start an issue heartbeat and simulate process loss while the issue
remains `in_progress`.
2. Allow assignment/reconciliation drivers to request repeated
event-free wakes for the same agent and issue.
3. Complete each follow-up run successfully without adding a comment,
issue mutation, document, work product, interaction, or continuation.
4. Observe repeated adapter sessions starting every few seconds without
new issue input.
**Environment**
- Version: reproduced on `master` before this change
- Deployment: local development, built from source
- Adapter scope: core bug; not adapter-specific
- Database: reproduced and tested with embedded Postgres
## What Changed
- Add a pure issue re-wake throttle that detects consecutive succeeded
runs without issue-visible progress and applies a 120-second exponential
cooldown capped at 30 minutes.
- Gate event-free `enqueueWakeup` requests and return the explicit skip
reason `issue_rewake_throttled` while the cooldown is active.
- Always bypass throttling for comment wakes, new issue activity,
explicit resumes, `forceFreshSession`, event-shaped reasons, and
post-failure recovery.
- Add focused pure unit coverage and database-backed heartbeat admission
coverage for throttle and bypass behavior.
## Verification
- `cd server && pnpm vitest run
src/__tests__/issue-rewake-throttle.test.ts` — 12 passed.
- `cd server && pnpm vitest run
src/__tests__/heartbeat-issue-rewake-throttle.test.ts` — 6 passed with
embedded Postgres.
- `cd server && pnpm run typecheck` — passed.
- Neighbor suites previously verified:
`heartbeat-dependency-scheduling`, `heartbeat-process-recovery`,
`run-continuations`, `heartbeat-issue-liveness-escalation`,
`recovery-stale-issue-lock-sweep`, and `heartbeat-comment-wake-batching`
— 131 tests passed.
## Risks
- A progress classifier that is too narrow could defer a legitimate
event-free poll; the cooldown is bounded and new issue activity bypasses
it immediately.
- A progress classifier that is too broad could allow the original
heartbeat storm; tests intentionally distinguish issue-visible mutations
from workspace-only activity.
- Low compatibility risk: no schema, API contract, or migration changes.
> For core feature work, check [`ROADMAP.md`](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 Codex coding agent. The runtime does not expose the exact
underlying model ID or context-window size; reasoning, terminal tool
use, code inspection, GitHub CLI access, and test execution 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 (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My public PR branch name describes the change 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>
Dotta