Files
PaperClipAI/server
DottaandClaude Opus 5.5 94cb7ad359 fix(recovery): stop an agent configuration write from re-checking every task of the company (#21861)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The recovery queues check each assigned task to find work that has
no live run and no queued wake
> - On a nearly idle hosted instance, these queues still re-check almost
every task of a company in bursts, at about 22 read-only statements per
task
> - #21831 stopped a run start from re-checking all of its agent's
tasks, but bursts continued after writes to an agent row during a long
run
> - The cause is not the changed-rows backstop. An agent configuration
write publishes the company-wide task recovery hint, so every task queue
reloads and checks every assigned task of the company
> - This pull request makes an agent configuration write signal only the
company-level recovery queues and the run dispatch queues, not the
per-task queues
> - The benefit is that a configuration write during a long run no
longer re-checks hundreds of settled tasks

## Linked Issues or Issue Description

Refs #21831

**What happened?**
A write to an agent's configuration (for example `PATCH /agents/:id`, an
instructions save that rebinds the entry file, a skill or connection
change) calls `notifyRunDispatch({ companyId })`. That function sends
the company hint to the task queues (`stranded-assignments`,
`assigned-work-invariant`, `resolved-dependencies`,
`stale-issue-locks`). A company hint is not a backstop hint, so the
queue loads every eligible task of the company with no changed-rows
filter and checks each one. In a staging-shaped fixture (780 settled
reviews), each configuration write caused 780 checks and about 16,000
statements. The agent row keeps status `running` and its old
`last_heartbeat_at`, which matches the writes seen on staging.

**Expected behavior**
A configuration write does not re-check tasks. Only a change that can
strand a task (pause, resume, hold release, termination) re-checks
tasks, and those changes keep their own lifecycle hint.

**Steps to reproduce**
1. Seed one agent with 700 settled in-review tasks and a second agent
with 80, each with one live native run.
2. Start the recovery workers with the debug flag
`PAPERCLIP_DEBUG_WORK_SIGNALS=stranded-assignments:1`.
3. Update the agent's `runtimeConfig` or `adapterConfig` through
`agentService(db).update`.
4. See 780 `check` events with `wake: "company"`.

**Paperclip version or commit**
`master` at c5218f5ec4.

## What Changed

- `run-dispatch-notifications.ts`: split the dispatch queue hints out of
`notifyRunDispatch` and add `notifyAgentConfigurationDispatch`. It sends
the company-level recovery hints and the dispatch hints, but no
task-queue hint.
- `issue-recovery-notifications.ts`: add `notifyCompanyRecovery`, which
signals only the company-level recovery queues (orphan blockers, active
recovery actions, task watchdogs).
- `agent-configuration.ts`: a configuration write uses
`notifyAgentConfigurationDispatch` instead of `notifyRunDispatch`.
- New census test `issue-recovery-agent-row-write-census.test.ts`. It
uses real workers, a fake clock and a staging-shaped fixture. It drives
five agent-row writers through their real code paths over 35 simulated
minutes, and it adds guard tests.

## Verification

Red/green census (`issue-recovery-agent-row-write-census.test.ts`, 35
simulated minutes, five writes: runtime config on the big agent, adapter
config on the second agent, execution start rewrite, permissions,
adapter config on the big agent):

| | Settled-task checks | Stranded checks by wake | Statements |
| --- | --- | --- | --- |
| Before | 2,340 | company 2,346, hint 204, backstop 6 | 51,497 |
| After | 0 | hint 210, backstop 7 | 4,580 |

The execution start rewrite and the permissions write caused 0 settled
checks before and after. Only the three configuration writes caused the
whole-company reloads.

Guard tests (pass before and after):
- A task of the running agent that becomes stranded after a
configuration write is checked within the backstop bound.
- An idle agent's tasks are still checked within the backstop bound
after its configuration is written (the agent clause of the changed-rows
backstop).
- A hold release through the lifecycle status-change effect checks the
waiting task within one minute.
- Pause and termination through the lifecycle check the agent's tasks
within one minute.
- The hourly full pass still checks every settled task.

Focused suites: `cd server && npx vitest run` on 19 files (recovery
work, census, backstop, debug attribution, signal fanout, run dispatch,
agent configuration, budget configuration, agent timers, lifecycle): 278
passed, 1 skipped. `pnpm verify` returned exit 2 (opaque setup
dependency), so required CI supplies broad coverage. Server `tsc
--noEmit` passed.

## Risks

- A configuration write no longer re-checks the company's tasks at once.
Agent status changes still send the company hint through the lifecycle
effect. For a non-running agent, the changed-rows backstop still picks
up its tasks within the existing 5-minute bound. The hourly full pass is
unchanged.
- The stranded check reads agent status, holds and budget, not
configuration, so a configuration change cannot strand a task by itself.
- Low risk otherwise. No schema change.

> 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

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in 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: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 23:46:49 -06:00
..