Files
PaperClipAI/tests/runner-e2e/chat-catalog-domains/runtime-queue-controls.test.ts
T
DottaandClaude Opus 5.5 db802d1230 fix(heartbeat): deliver a queued comment again unless the reading run cites it as handled (#21243)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A person can add a comment to a task while the agent's run on that
task is still working
> - #21175 made a `get_task_history` read of a queued comment's current
revision count as delivery
> - A read is not handling. In `agent-chat.multiple-handoffs`, Morgan's
running turn read the "Launch sooner" comment, set it aside, and saved
"Launch later". No continuation ran, so the instruction was lost.
> - This pull request counts a read as delivery only when the run's
accepted result cites the comment as handled. Otherwise one continuation
still delivers it, and that continuation is told the comment may already
be applied.
> - The benefit is that a person's comment is never silently lost, and
the #21175 protection against repeated completed work stays in place

## Linked Issue or Issue Description

Refs #21175
Refs #21203
Refs #21210

**What happened?**
Paid run 43321773136 (OpenCode,
`openrouter/deepseek/deepseek-v4.1-flash-1017`), case
`agent-chat.multiple-handoffs`. Morgan's running turn called
`get_task_history` and received the CEO's queued "Launch sooner" comment
at its current revision (`task_history.read` at seq 75). The model
judged the comment as an unauthenticated agent instruction and saved
"Launch later" from the brief. Its accepted result did not mention the
comment. `deliveredQueuedCommentIds` counted the read as delivery, the
release drain dropped the held comment, and no continuation ran.

**Expected behavior**
A read counts as delivery only when the run records the comment as
handled. A comment that was read but not recorded as handled is
delivered once in a new turn. The new turn's prompt says that an earlier
turn already read the comment and may have applied it.

**Steps to reproduce**
1. Start a native run on a task.
2. Queue a comment behind the run.
3. Let the run read `get_task_history` and finish without applying the
comment.
4. Before this change, no continuation runs and the comment is lost.

## What Changed

- `server/src/services/queued-comment-delivery.ts`: the history-read
delivery rule now also requires the reading run's `run.result.accepted`
event to cite `comment:<id>` (top-level `evidence[].ref` or a
criterion's `evidenceRefs`, prefix match so an annotated ref counts).
The read revision, succeeded-run and finished-after-revision rules are
unchanged. All consumers (release drain, stale-continuation save,
ownership reconciler, first-turn queued input, remote-Stop resume) use
this one rule.
- New `readByEarlierTurnCommentIds`, `commentsArrivedDuringRun` and
`taskHistoryHandlingGuidance`.
- `get_task_history` (both tool authorities) returns
`arrivedDuringThisTurn` (the `comment:<id>` refs of comments other
authors posted or edited after the run started) and a `handling`
instruction to cite each applied comment in `paperclip_finish` /
`paperclip_block` evidence. The comment list itself is unchanged. A
failure to compute the list returns no guidance, so the comment stays
owed.
- `buildPaperclipWakePayload` marks a wake comment `readByEarlierTurn`
when another finished run of the agent read its current revision.
`renderPaperclipWakePrompt` adds one line after that comment: check the
current task state first, and do not repeat work that is already done.
- `doc/run-log-events.md`: the delivery rule and the new fields.
- Evals: `agent-chat.multiple-handoffs` (oracle
`runtime-multiple-handoffs.v6`) and `steering.edit-queued-message`
(oracle `edit-queued-message.structural.v6`) accept in-turn consumption
only with a current-revision read and a citation. A read without a
citation must get exactly one continuation whose saved wake marks
`readByEarlierTurn`, and the final saved revision must hold the change
("Launch sooner"; blue). `runtime-queue.ts` reads citations from the
run's `run.result.accepted` event. No scenario YAML changed.

## Verification

- RED on master `b1ef1f3022`,
`server/src/__tests__/heartbeat-held-comment-wake.test.ts`: 10 of 41
fail. The key one: "settles a held message as soon as its run closes the
task (read mid-turn: true, cited: false)" delivered 0, expected 1.
- GREEN: 41/41. The three required shapes:
- read, not cited: one continuation, and its wake marks
`readByEarlierTurn` (`...read mid-turn: true, cited: false` and the
stale-queued-run variant).
  - read and cited: no continuation (`...cited: true`).
  - never read: one continuation, as before.
  - Edited after the read, or a failed reader: still owed.
- `server/src/services/queued-comment-history-read.test.ts` (remote-Stop
resume): succeeded+cited not owed; succeeded+uncited owed; failed+cited
owed. 4/4.
- `packages/adapter-utils/src/server-utils.test.ts`: the prompt line
renders only for `readByEarlierTurn`.
- Neighbouring suites: `muse-control`, `dot-runner`,
`paperclip-runner-tool-authority`, `paperclip-control-plane-port`,
`muse-native-follow-up`, `runner-prp-coordinator`,
`native-session-handoff`, `execution-continuation-history-read`,
`heartbeat-comment-wake-batching`, `ownership-reconciliation-report`,
`run-preparation`: all pass. Server and adapter-utils `tsc --noEmit`:
clean.
- Eval graders: `npx vitest run --config
tests/runner-e2e/vitest.config.ts tests/runner-e2e/chat-catalog
tests/runner-e2e/chat-catalog-domains`: 283 files pass. New calibration:
the observed lost-instruction case (read, not cited, no continuation)
fails; read-not-cited with one warned continuation passes; an unwarned
continuation, a missing final change, and a cited read plus a
continuation fail.
- `pnpm test:e2e:runner:typecheck`: pass. `node --test
tests/runner-e2e/chat-full-catalog-testops-manifest.test.mjs`: 10/10.
`node tests/runner-e2e/source-sdk-public-inputs.mjs <sha> --check`:
`changed: false`.
- Paid run: Runner Full-Stack E2E 43338695850 on throwaway branch
`chat-eval/qa-mr-paid` (this change plus the model-retry fix on master
19f8ed1ea2). Result to follow in a comment.

## Risks

- A run that applies a queued comment but does not cite it gets one more
turn on that task. That turn is told the comment may already be applied.
In the restart-chaos t005 shape (#21175) this can reopen a done task
when the agent does not cite the comment. This is the chosen tradeoff: a
lost comment is worse than one extra checked turn.
- Each `get_task_history` call adds one small indexed read of the run's
`started_at`.
- Upgrade-safe: runs saved by older builds have no citation, so a
read-only delivery from before this change stays owed and is delivered
once more. No migration.

> 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, used through Claude
Code with tool use and code execution.

## 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-12 21:07:08 -06:00

110 lines
11 KiB
TypeScript

import { expect, it } from "vitest";
import { gradeQueueEdit } from "./runtime-queue-controls.js";
function valid() {
const before = { issueId: "website", targetRunId: "prior", entries: [
{ position: 0, canEdit: true, comment: { id: "font", body: "Use a readable font with accessible labels.", authorUserId: "human", authorAgentId: null } },
{ position: 1, canEdit: true, comment: { id: "color", body: "Make the website red. Keep the existing note about accessible labels.", authorUserId: "human", authorAgentId: null } },
] };
return { scenarioId: "steering.edit-queued-message", origin: "http://fixture.invalid", companyId: "company", leadId: "ceo", agents: [], tasks: [], activity: [], links: [], humanQueries: [], reply: "",
runs: [{ id: "prior", agentId: "morgan", status: "succeeded" }, { id: "guide", agentId: "ceo", status: "succeeded" }, { id: "consumer", agentId: "morgan", status: "succeeded" }],
state: { task: { id: "website" }, worker: { id: "morgan" }, queueBefore: before, targetId: "color", workerRunId: "prior", humanId: "human", concurrentMarker: "Preserve the human note.",
queuedComments: [{ id: "color", updatedAt: "2026-11-12T21:52:30.494Z" }, { id: "font", updatedAt: "2026-11-12T21:50:24.404Z" }],
workerCommentReceipts: { reads: {} as Record<string, string>, cited: [] as string[] }, taskDone: true, inTurnOutcomeApplied: false,
finalOutcomeApplied: true, continuationWarnedEarlierReads: true,
queueAfter: { ...before, entries: [{ ...before.entries[1]!, position: 0, comment: { ...before.entries[1]!.comment,
body: "Make the website blue. Keep the existing note about accessible labels. Preserve the human note." } }, { ...before.entries[0]!, position: 1 }] },
queryReply: "Your pending red request is in the Website queue. Open its message menu, edit the full request to blue, then move it first.",
queryLinks: ["/COM/issues/website"], queueAtReply: structuredClone(before),
agentEditStatus: 403, agentOrderStatus: 403, concurrentStatus: 409, concurrentErrorVisible: true, concurrentSaveRetained: true,
dispatchedStatus: 409, dispatchedWarningVisible: true, originalCommentStillReadable: true, nativeDeliveryBound: true, queueEmptyAfterDelivery: true,
consumingRunCount: 1, initialRevisionRetained: true } };
}
it("accepts actual owned full-text edit, first position and independently observed conflicts/delivery", () => expect(gradeQueueEdit(valid()).passed).toBe(true));
it("accepts natural substantive control guidance", () => { const o = valid(); o.state.queryReply = "The waiting red message belongs to you. Use Edit in its menu and drag the resulting blue message to the first slot."; expect(gradeQueueEdit(o).passed).toBe(true); });
it("rejects missing runtime evidence", () => expect(gradeQueueEdit(undefined).passed).toBe(false));
it("rejects an agent-owned message presented as human-owned", () => { const o = valid(); o.state.queueBefore.entries[1]!.comment.authorUserId = "different-person"; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects changing only a fragment and dropping the concurrent note", () => { const o = valid(); o.state.queueAfter.entries[0]!.comment.body = "Make the website blue."; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects losing the other queued message", () => { const o = valid(); o.state.queueAfter.entries.pop(); expect(gradeQueueEdit(o).passed).toBe(false); });
// Full cohort 4: correct guidance worded as "change ... and drag it above" failed the old edit|control|menu keyword list.
it("accepts reworded guidance that links the task, on the same saved evidence", () => {
const o = valid(); o.state.queryReply = "Changing a queued message's text and order is board-only, so I couldn't apply it. On [COM-1](/COM/issues/COM-1), change that queued message to blue and drag it above the font note.";
o.state.queryLinks = ["/COM/agents/ceo/overview", "/COM/issues/website"]; expect(gradeQueueEdit(o).passed).toBe(true);
});
it("rejects guidance without a rendered link to the task", () => { const o = valid(); o.state.queryLinks = ["/COM/agents/ceo/overview"]; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects an empty reply", () => { const o = valid(); o.state.queryReply = " "; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects an edit or reorder applied before the person acted", () => {
const edited = valid(); edited.state.queueAtReply.entries[1]!.comment.body = "Make the website blue. Keep the existing note about accessible labels."; expect(gradeQueueEdit(edited).passed).toBe(false);
const reordered = valid(); reordered.state.queueAtReply.entries[0]!.position = 1; reordered.state.queueAtReply.entries[1]!.position = 0; expect(gradeQueueEdit(reordered).passed).toBe(false);
const missing = valid(); delete (missing.state as Record<string, unknown>).queueAtReply; expect(gradeQueueEdit(missing).passed).toBe(false);
});
it("rejects an agent that can edit or reorder the person's message", () => {
const edit = valid(); edit.state.agentEditStatus = 200; expect(gradeQueueEdit(edit).passed).toBe(false);
const order = valid(); order.state.agentOrderStatus = 200; expect(gradeQueueEdit(order).passed).toBe(false);
});
it("rejects stale concurrent acceptance", () => { const o = valid(); o.state.concurrentStatus = 200; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects silently overwriting an already-consumed message", () => { const o = valid(); o.state.dispatchedStatus = 200; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects a plausible wrong consumer without exact saved input and order", () => { const o = valid(); o.state.nativeDeliveryBound = false; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects losing the initial native work", () => { const o = valid(); o.state.initialRevisionRetained = false; expect(gradeQueueEdit(o).passed).toBe(false); });
it.each([200, 403, 500])("rejects late edit status %s rather than replacing the real 409 assertion", status => {
const o = valid(); o.state.dispatchedStatus = status; expect(gradeQueueEdit(o).passed).toBe(false);
});
function inTurn() {
const o = valid(); o.runs.pop();
o.state.workerCommentReceipts = { reads: { color: "2026-11-12T21:52:30.494Z", font: "2026-11-12T21:50:24.404Z" }, cited: ["color", "font"] };
Object.assign(o.state, { consumingRunCount: 0, nativeDeliveryBound: false, inTurnOutcomeApplied: true });
return o;
}
it("accepts the running turn consuming the current edited revision with no continuation", () => expect(gradeQueueEdit(inTurn()).passed).toBe(true));
it("accepts an in-turn read made after the last edit", () => { const o = inTurn(); o.state.workerCommentReceipts.reads.color = "2026-11-12T21:52:39.000Z"; expect(gradeQueueEdit(o).passed).toBe(true); });
it("still accepts one continuation when the running turn read only the earlier revision", () => {
const o = valid(); o.state.workerCommentReceipts = { reads: { color: "2026-11-12T21:50:32.657Z" }, cited: ["color"] }; expect(gradeQueueEdit(o).passed).toBe(true);
});
it("rejects an in-turn read of the earlier revision only", () => { const o = inTurn(); o.state.workerCommentReceipts.reads.color = "2026-11-12T21:50:32.657Z"; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects an in-turn read of only one queued message", () => { const o = inTurn(); delete (o.state.workerCommentReceipts.reads as Record<string, string>).font; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects an in-turn read whose change was never saved", () => { const o = inTurn(); o.state.inTurnOutcomeApplied = false; expect(gradeQueueEdit(o).passed).toBe(false); });
it("rejects in-turn reads of both messages that cite only one, with no continuation", () => {
const o = inTurn(); o.state.workerCommentReceipts.cited = ["color"]; expect(gradeQueueEdit(o).passed).toBe(false);
});
it("rejects a double application: an in-turn read cited as handled and a continuation", () => {
const o = valid(); o.state.workerCommentReceipts = { reads: { color: "2026-11-12T21:52:30.494Z", font: "2026-11-12T21:50:24.404Z" }, cited: ["color", "font"] }; o.state.inTurnOutcomeApplied = true;
expect(gradeQueueEdit(o).passed).toBe(false);
});
it("rejects two continuations", () => {
const o = valid(); o.runs.push({ id: "again", agentId: "morgan", status: "succeeded" }); o.state.consumingRunCount = 2; expect(gradeQueueEdit(o).passed).toBe(false);
});
it("rejects consumption that leaves the queue or task unfinished", () => {
const queued = inTurn(); queued.state.queueEmptyAfterDelivery = false; expect(gradeQueueEdit(queued).passed).toBe(false);
const open = inTurn(); open.state.taskDone = false; expect(gradeQueueEdit(open).passed).toBe(false);
});
function mixed() {
const o = valid() as ReturnType<typeof valid> & { state: Record<string, unknown> };
Object.assign(o.state, { workerCommentReceipts: { reads: { color: "2026-11-12T21:52:30.494Z" }, cited: ["color"] }, inTurnOutcomeApplied: false, inTurnOutcomeSaved: true, latestOutcomeKept: true,
finalOutcomeApplied: false });
return o;
}
it("grades the whole limit-1 partial read: the turn saved blue, the continuation got only the font note and saved the latest revision", () => {
const result = gradeQueueEdit(mixed()); expect(result.checks.filter(check => !check.passed)).toEqual([]); expect(result.passed).toBe(true);
});
it("rejects a partial read whose later continuation dropped the saved blue change", () => { const o = mixed(); o.state.latestOutcomeKept = false; expect(gradeQueueEdit(o).passed).toBe(false); });
it("accepts the running turn reading only the edited message and one continuation delivering the unread one", () => expect(gradeQueueEdit(mixed()).passed).toBe(true));
it("rejects the edited message read in the running turn whose change was never saved, even with a continuation", () => {
const o = mixed(); o.state.inTurnOutcomeSaved = false; expect(gradeQueueEdit(o).passed).toBe(false);
});
it("rejects a continuation that re-delivers the message the running turn already read", () => { const o = mixed(); o.state.nativeDeliveryBound = false; expect(gradeQueueEdit(o).passed).toBe(false); });
function readNotCited() {
const o = valid(); o.state.workerCommentReceipts = { reads: { color: "2026-11-12T21:52:30.494Z", font: "2026-11-12T21:50:24.404Z" }, cited: [] };
return o;
}
it("accepts reads the running turn did not cite, delivered once to a continuation told about the earlier reads", () => expect(gradeQueueEdit(readNotCited()).passed).toBe(true));
it("rejects that continuation when it was not told the running turn already read the messages", () => {
const o = readNotCited(); o.state.continuationWarnedEarlierReads = false; expect(gradeQueueEdit(o).passed).toBe(false);
});
it("rejects that continuation when it saves no latest revision", () => {
const o = readNotCited(); o.state.finalOutcomeApplied = false; expect(gradeQueueEdit(o).passed).toBe(false);
});
it("rejects messages the running turn read but did not cite, with no continuation", () => {
const o = inTurn(); o.state.workerCommentReceipts.cited = []; expect(gradeQueueEdit(o).passed).toBe(false);
});