Files
PaperClipAI/server/src/services/native-runtime/status-arbiter.test.ts
T
DottaandClaude Opus 5.5 7f9c115cc2 fix(github): let a queued push start the next review turn instead of a blocker continuation (#22223)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A GitHub review bot reviews each PR in a task. Each push sends a new
review request to that task as a chat message.
> - A push that arrives during a review waits as a deferred chat wake.
That wake starts a new turn. The turn binds its tools to the newest
pushed commit.
> - #21959 and #22140 continue a run that reports a blocker in a fresh
session. That continuation keeps the source binding of the blocked run.
It also holds the task, so the waiting push request does not run.
> - On staging, a push during a review made the publication fail with
"requested for an older pull request head". The agent reported a
blocker. Paperclip then continued twice with the old binding. Each
continuation finished the review and could not publish it.
> - A second failure mode: a complete re-review that listed only the
files changed since the prior review got a short rejection. The
rejection named no files, and a small model stopped instead of
correcting the submission.
> - This pull request lets a queued chat request take the next turn
instead of a blocker continuation. It also names the missing files in
the coverage rejection.
> - The benefit is that reviews publish for the newest push without a
person, and agents can correct incomplete coverage on the next call.

## Linked Issues or Issue Description

**What happened?**
On staging, automatic GitHub reviews stopped publishing. The bots posted
"Publication is currently blocked" and "Paperclip must authorize the
review for <newest commit>". The run history showed this sequence: a
review run started for the first commit. Two pushes arrived during the
run. Steering into the active run was rejected for both pushes, so they
waited as deferred chat wakes. The run reported a blocker. Paperclip
then started two `native_environment_blocker` continuations. Each
continuation had no message of its own, so its GitHub tools resolved to
the first commit's request and refused the current head. The waiting
push requests did not run until a later push.

**What did you expect?**
A push request that waits behind a run starts the next turn, bound to
that push. The agent then reviews and publishes for the current head.

**Steps to reproduce**
1. Start an automatic review on a PR.
2. Push a new commit while the review runs, so the review request waits
as a deferred chat wake.
3. Let the run report a blocker (for example after the stale-head
publication refusal).
4. See that a fresh-session retry starts with the old binding and the
push request stays deferred.

Refs #21959, #22140, #22066

## What Changed

- `status-arbiter.ts`: new rule before the blocker continuation lanes.
When a blocked run has a queued chat request for the same task and
agent, the decision is `preserve` with only `release_checkout` (reason
`native_blocker_superseded_by_queued_request`). The normal release drain
then starts the queued request. A pause hold or a board-owned blocker
keeps the existing behavior.
- `native-runtime/queued-chat-request.ts`: new `hasQueuedChatRequest`
query. It uses the same chat-wake test that keeps chat wakes out of
first turns (`chatConversationId` or `externalChatProvider`).
- `native-run-finalizer.ts`: supplies `hasQueuedChatRequest` to the
arbiter, only for a blocked report.
- `chat-github-review-policy.ts` / `chat-github-reviews.ts`:
`githubCompleteCoverageGap` replaces the inline check. The rejection now
names the missing files (up to 20), says that a complete review covers
all changed files, and gives the two corrections (add them to
`reviewedPaths`, or submit `complete: false` with `omittedPaths`).

## Verification

- Red/green: `cd server && npx vitest run
src/services/native-runtime/native-environment-blocker.integration.test.ts`.
The new case failed before the fix with reason
`native_environment_blocker` and one scheduled retry, as on staging.
After the fix it passes: no retry, the task stays `in_progress`, and the
chat wake stays deferred for the release drain.
- Red/green: `npx vitest run
src/services/native-runtime/status-arbiter.test.ts -t "queued chat
request"`.
- Red/green: `npx vitest run
src/services/chat-github-review-policy.test.ts -t
githubCompleteCoverageGap`.
- `native-agent-blocker.integration.test.ts` and the full arbiter and
review-policy suites pass.
- `cd server && npx tsc --noEmit -p .` passes.
- `pnpm verify` on the changed files (results in the CI checks below).

## Risks

- Low to medium. The new rule changes only blocked reports that would
otherwise auto-continue while a chat request waits behind the run.
Without a waiting chat request, the behavior does not change.
- The waiting request now starts the next turn instead of the
continuation. If the blocker is real, that turn can report it again, and
the existing lanes apply.
- The finalizer does one more indexed read, only for blocked reports.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code with tool use: code
search, editing, shell, test runs, and staging run inspection through
the browser.

## 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
- [ ] 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-18 15:00:57 -06:00

813 lines
34 KiB
TypeScript

import { describe, expect, it } from "vitest";
import type { NativeEvidenceAssessment } from "./evidence-classifier.js";
import { arbitrateNativeStatus } from "./status-arbiter.js";
function assessment(
overrides: Partial<NativeEvidenceAssessment> = {},
): NativeEvidenceAssessment {
return {
objectiveClaimSatisfied: true,
objectiveSatisfied: true,
allCriteriaSatisfied: true,
verificationPassed: true,
hasFailedVerification: false,
hasBlockingRemainingWork: false,
reportedDisposition: "done",
summary: "Complete",
contractRevisionMatches: true,
criterionAssessments: [],
verificationAssessments: [],
verificationCaveats: [],
acceptedEvidenceRefs: ["event:2"],
missingRequirements: [],
rejectedEvidence: [],
unverifiableEvidence: [],
blocker: null,
continuation: null,
attentionRequests: [],
ignoredAttentionRequests: [],
...overrides,
};
}
function arbitrate(
overrides: Partial<Parameters<typeof arbitrateNativeStatus>[0]> = {},
) {
return arbitrateNativeStatus({
assessment: assessment(),
terminalState: "succeeded",
workspaceFinalizeStatus: "succeeded",
agentId: "agent",
priorIssueStatus: "in_progress",
...overrides,
});
}
describe("native status authority", () => {
it("completes a reviewer's done report from its own recorded final-stage approval", () => {
// Retained live failure: the reviewer approved its stage, then cited free-text
// evidence; the report was graded as incomplete and the task reopened.
const freeText = assessment({ objectiveSatisfied: false, allCriteriaSatisfied: false, verificationPassed: false });
expect(arbitrate({ assessment: freeText, priorIssueStatus: "in_review" }))
.toMatchObject({ toStatus: "in_progress", reasonCode: "completion_evidence_incomplete" });
expect(arbitrate({ assessment: freeText, priorIssueStatus: "in_review", executionStageApprovedByRun: true }))
.toMatchObject({ toStatus: "done", reasonCode: "execution_stage_approved" });
// The decision authorizes completion only for a clean done report.
expect(arbitrate({ assessment: { ...freeText, hasBlockingRemainingWork: true }, priorIssueStatus: "in_review", executionStageApprovedByRun: true }))
.not.toMatchObject({ toStatus: "done" });
expect(arbitrate({ assessment: { ...freeText, hasFailedVerification: true }, priorIssueStatus: "in_review", executionStageApprovedByRun: true }))
.not.toMatchObject({ toStatus: "done" });
expect(arbitrate({ assessment: { ...freeText, reportedDisposition: "needs_review" }, priorIssueStatus: "in_review", executionStageApprovedByRun: true }))
.not.toMatchObject({ toStatus: "done" });
// A still-pending stage keeps governing the task.
expect(arbitrate({ assessment: freeText, priorIssueStatus: "in_review", executionStageApprovedByRun: true, governanceGate: { kind: "execution_stage", id: "run" } }))
.toMatchObject({ toStatus: "in_review", reasonCode: "governed_gate_pending" });
});
it("cannot complete an explicitly required quality review from claims or file evidence", () => {
expect(arbitrate({ completionClaimPolicyAccepted: true, requiredQualityReviewSatisfied: false }))
.toMatchObject({ toStatus: "in_progress", reasonCode: "required_quality_review_incomplete" });
expect(arbitrate({ completionClaimPolicyAccepted: false, requiredQualityReviewSatisfied: false }))
.toMatchObject({ toStatus: "in_progress", reasonCode: "required_quality_review_incomplete" });
expect(arbitrate({ requiredQualityReviewSatisfied: true })).toMatchObject({ toStatus: "done" });
expect(arbitrate()).toMatchObject({ toStatus: "done" });
expect(arbitrate({ requiredQualityReviewSatisfied: false, governanceGate: { kind: "interaction", id: "quality" } }))
.toMatchObject({ toStatus: "in_review", reasonCode: "governed_gate_pending" });
});
it("waits on a published external review without creating human attention", () => {
const wait = assessment({ reportedDisposition: "yielded",
continuation: { kind: "response_wake", summary: "Wait for the PR update", idempotencyKey: "pr-wait" } });
expect(arbitrate({ assessment: wait, publishedExternalReview: true, externalChatResponseWaitAuthorization: "authorized" }))
.toMatchObject({ toStatus: "in_review", reasonCode: "external_chat_response_waiting", effects: [] });
expect(arbitrate({ assessment: wait, publishedExternalReview: true, externalChatResponseWaitAuthorization: "revoked" }))
.toMatchObject({ statusAction: "preserve", effects: [] });
expect(arbitrate({ assessment: wait, publishedExternalReview: true,
externalChatResponseWaitAuthorization: "authorized", governanceGate: { kind: "approval", id: "access" } }))
.toMatchObject({ reasonCode: "governed_response_waiting", effects: [{ kind: "create_interaction" }] });
const monitor = { ...wait, continuation: { ...wait.continuation!, kind: "monitor" as const } };
expect(arbitrate({ assessment: monitor, publishedExternalReview: true, monitorWaitAuthorized: true }))
.toMatchObject({ toStatus: "in_review", reasonCode: "scheduled_monitor_waiting", effects: [{ kind: "release_checkout" }] });
expect(arbitrate({ assessment: monitor, publishedExternalReview: true }))
.toMatchObject({ statusAction: "preserve", reasonCode: "monitor_wait_authority_lost" });
});
it("preserves an open task after an accepted case handoff even if the departing model claims done", () => {
expect(arbitrate({ caseHandoffAuthorized: true })).toMatchObject({
statusAction: "preserve", toStatus: "in_progress", reasonCode: "case_handoff_waiting_for_release",
effects: [{ kind: "release_checkout" }],
});
});
it("preserves the task status after a context compaction run", () => {
for (const priorIssueStatus of ["in_progress", "in_review", "blocked", "todo"] as const) {
expect(arbitrate({
contextCompactionRun: true,
priorIssueStatus,
assessment: assessment({ reportedDisposition: "yielded", objectiveSatisfied: false, allCriteriaSatisfied: false }),
})).toMatchObject({
statusAction: "preserve", toStatus: priorIssueStatus, reasonCode: "context_compaction_status_preserved", effects: [],
});
}
});
it("keeps workspace repair ahead of an accepted case handoff", () => {
expect(arbitrate({ caseHandoffAuthorized: true, workspaceFinalizeStatus: "failed" })).toMatchObject({
statusAction: "preserve", reasonCode: "finalization_failed_claim_preserved",
});
});
it("keeps a verified accepted Cursor plan passive without completing or replaying work", () => {
const passive = assessment({ reportedDisposition: "yielded", objectiveSatisfied: false,
allCriteriaSatisfied: false, hasBlockingRemainingWork: true,
continuation: { kind: "response_wake", summary: "Explicit continuation needed", idempotencyKey: "cursor-plan-wait:event" } });
expect(arbitrate({ assessment: passive, planWaitAuthorized: true })).toMatchObject({
toStatus: "in_progress", reasonCode: "native_plan_accepted_waiting_for_continuation", effects: [],
});
expect(arbitrate({ assessment: passive })).toMatchObject({
toStatus: "in_progress",
reasonCode: "completion_evidence_incomplete",
effects: [expect.objectContaining({
kind: "enqueue_continuation",
continuationKind: "same_agent",
idempotencyKey: "native-completion-incomplete",
})],
});
expect(arbitrate({ assessment: passive, planWaitAuthorized: true, terminalState: "failed" }).reasonCode).not.toBe("native_plan_accepted_waiting_for_continuation");
expect(arbitrate({ assessment: passive, planWaitAuthorized: true, priorIssueStatus: "cancelled" }).toStatus).toBe("cancelled");
expect(arbitrate({ assessment: passive, planWaitAuthorized: true, governanceGate: { kind: "interaction", id: "pending" } }).toStatus).toBe("in_review");
});
it("a reviewer finishes its decision without completing rejected or still-reviewed work", () => {
for (const priorIssueStatus of ["in_progress", "in_review"] as const) {
const decision = arbitrate({ priorIssueStatus, nativeReviewOutcome: "resolved" });
expect(decision).toMatchObject({ statusAction: "preserve", toStatus: priorIssueStatus });
expect(decision.effects).not.toContainEqual(expect.objectContaining({ kind: "enqueue_continuation" }));
}
});
it("routes an unfinished reviewer action to bounded recovery instead of retrying the worker task", () => {
const decision = arbitrate({ priorIssueStatus: "in_review", nativeReviewOutcome: "pending" });
expect(decision).toMatchObject({ statusAction: "preserve", toStatus: "in_review" });
expect(decision.effects).toContainEqual(expect.objectContaining({
kind: "record_recovery", cause: "native_review_unresolved", agentId: "agent",
}));
expect(decision.effects.some((effect) => ["enqueue_continuation", "schedule_retry"].includes(effect.kind))).toBe(false);
});
it("lets a reviewer stopped by a tool-call loop continue through its queued review wake instead of a resume recovery", () => {
const decision = arbitrate({ priorIssueStatus: "in_review", nativeReviewOutcome: "pending", toolCallLoopContinuation: true });
expect(decision).toMatchObject({ statusAction: "preserve", toStatus: "in_review", reasonCode: "native_review_unresolved" });
expect(decision.effects).toEqual([{ kind: "release_checkout" }]);
});
it("continues a turn stopped at its tool receipt limit in a fresh session, within its bound", () => {
const stopped = arbitrate({ terminalState: "cancelled", toolReceiptLimitStopped: true });
expect(stopped).toMatchObject({ statusAction: "preserve", toStatus: "in_progress", reasonCode: "semantic_tool_turn_receipt_limit" });
expect(stopped.effects).toEqual([
{ kind: "schedule_retry", cause: "semantic_tool_turn_receipt_limit", summary: "Continue the task in a fresh session.", agentId: expect.any(String) },
{ kind: "release_run_resources" },
]);
expect(arbitrate({ terminalState: "failed", toolReceiptLimitStopped: true }).effects)
.toEqual([expect.objectContaining({ kind: "schedule_retry", cause: "semantic_tool_turn_receipt_limit" })]);
expect(arbitrate({ terminalState: "cancelled", toolReceiptLimitStopped: true, failureRetryCount: 2 }).reasonCode).toBe("cancellation_run_only");
expect(arbitrate({ terminalState: "cancelled", toolReceiptLimitStopped: true, priorIssueStatus: "blocked" }).reasonCode).toBe("cancellation_run_only");
expect(arbitrate({ terminalState: "cancelled" }).reasonCode).toBe("cancellation_run_only");
});
it("treats only the authorized Board response_wake as passive and preserves governance", () => {
const passive = assessment({
reportedDisposition: "yielded",
continuation: {
kind: "response_wake",
summary: "Wait for the next request",
idempotencyKey: "board-wait",
},
});
expect(
arbitrate({ assessment: passive, boardResponseWaitAuthorized: true }),
).toMatchObject({
reasonCode: "board_response_waiting",
toStatus: "in_progress",
effects: [],
});
expect(arbitrate({ assessment: passive })).toMatchObject({
reasonCode: "response_wake_waiting_for_input",
toStatus: "in_progress",
effects: [],
});
expect(
arbitrate({ assessment: passive, boardResponseWaitOrigin: true }),
).toMatchObject({
reasonCode: "board_response_wait_superseded",
statusAction: "preserve",
effects: [],
});
expect(
arbitrate({
assessment: passive,
boardResponseWaitAuthorized: true,
governanceGate: { kind: "approval", id: "approval" },
}),
).toMatchObject({
reasonCode: "governed_response_waiting",
toStatus: "in_review",
effects: [expect.objectContaining({ kind: "create_interaction" })],
});
for (const kind of ["same_agent", "retry"] as const) {
expect(
arbitrate({
assessment: {
...passive,
continuation: { ...passive.continuation!, kind },
},
boardResponseWaitAuthorized: true,
}),
).toMatchObject({
reasonCode: "live_continuation_registered",
effects: [expect.objectContaining({ continuationKind: kind })],
});
}
});
it("repairs unfinished response waits once using the server continuation budget", () => {
const unfinished = assessment({
reportedDisposition: "yielded", hasBlockingRemainingWork: true,
continuation: { kind: "response_wake", summary: "Answered status; await next message", idempotencyKey: "model-key" },
});
for (const boardResponseWaitAuthorized of [true, false]) {
expect(arbitrate({ assessment: unfinished, boardResponseWaitAuthorized })).toMatchObject({
reasonCode: "completion_evidence_incomplete",
toStatus: "in_progress",
effects: [{ kind: "enqueue_continuation", continuationKind: "same_agent", idempotencyKey: "native-completion-incomplete" }],
});
expect(arbitrate({ assessment: unfinished, boardResponseWaitAuthorized, allowIncompleteContinuation: false })).toMatchObject({
reasonCode: "prior_status_preserved_no_live_path",
effects: [{ kind: "record_finalization_error", cause: "completion_evidence_incomplete" }],
});
}
expect(arbitrate({ assessment: unfinished, boardResponseWaitOrigin: true, boardResponseWaitAuthorized: true }))
.toMatchObject({ reasonCode: "completion_evidence_incomplete" });
expect(arbitrate({ assessment: unfinished, boardResponseWaitOrigin: true, boardResponseWaitAuthorized: false }))
.toMatchObject({ reasonCode: "board_response_wait_superseded", effects: [] });
expect(arbitrate({ assessment: unfinished, hasActivePauseHold: true }))
.toMatchObject({ reasonCode: "response_wait_pause_preserved", effects: [] });
expect(arbitrate({ assessment: unfinished, hasUnresolvedIssueBlockers: true }))
.toMatchObject({ toStatus: "blocked", reasonCode: "durable_dependency_blocker_bound", effects: [] });
expect(arbitrate({ assessment: unfinished, governanceGate: { kind: "interaction", id: "question" } }))
.toMatchObject({ reasonCode: "governed_response_waiting", effects: [{ kind: "create_interaction" }] });
expect(arbitrate({ assessment: unfinished, externalChatResponseWaitAuthorization: "authorized" }))
.toMatchObject({ reasonCode: "external_chat_response_waiting", effects: [] });
expect(arbitrate({ assessment: unfinished, externalChatResponseWaitAuthorization: "revoked" }))
.toMatchObject({ reasonCode: "external_chat_response_wait_authorization_lost", effects: [] });
expect(arbitrate({ assessment: unfinished, isConversation: true, boardResponseWaitAuthorized: true }))
.toMatchObject({ reasonCode: "board_response_waiting", effects: [] });
});
it("marks done only from successful finalization and complete durable evidence", () => {
expect(arbitrate()).toEqual(
expect.objectContaining({
statusAction: "done",
toStatus: "done",
reasonCode: "completion_contract_satisfied",
effects: [{ kind: "release_checkout" }],
}),
);
expect(arbitrate({ completionClaimPolicyAccepted: true })).toEqual(
expect.objectContaining({
statusAction: "done",
reasonCode: "completion_claim_policy_accepted",
}),
);
expect(
arbitrate({
assessment: assessment({
verificationPassed: false,
missingRequirements: ["test"],
}),
}),
).toEqual(
expect.objectContaining({
statusAction: "in_progress",
toStatus: "in_progress",
reasonCode: "completion_evidence_incomplete",
effects: [expect.objectContaining({ kind: "enqueue_continuation" })],
}),
);
const claimOnly = assessment({
objectiveSatisfied: false,
allCriteriaSatisfied: false,
verificationPassed: false,
criterionAssessments: [
{
criterionId: "objective",
claimStatus: "satisfied",
outcome: "missing",
evidenceRefs: [],
reasonCode: "criterion_evidence_missing",
},
],
verificationAssessments: [
{
commandOrCheck: "Answered the question",
claimStatus: "passed",
outcome: "unverifiable",
evidenceRef: null,
reasonCode: "verification_has_no_durable_reference",
reportedReasonCode: null,
detail: null,
},
],
acceptedEvidenceRefs: [],
missingRequirements: ["objective"],
});
expect(arbitrate({ assessment: claimOnly })).toEqual(
expect.objectContaining({
toStatus: "in_progress",
reasonCode: "completion_evidence_incomplete",
}),
);
expect(
arbitrate({ assessment: claimOnly, completionClaimPolicyAccepted: true }),
).toEqual(
expect.objectContaining({
toStatus: "done",
reasonCode: "completion_claim_policy_accepted",
}),
);
});
it("creates explicit liveness paths for review, continuation, cancellation, and governance", () => {
expect(
arbitrate({
assessment: assessment({ reportedDisposition: "needs_review" }),
}),
).toEqual(
expect.objectContaining({
toStatus: "in_progress",
effects: [expect.objectContaining({ kind: "enqueue_continuation" })],
}),
);
expect(
arbitrate({
assessment: assessment({
reportedDisposition: "yielded",
continuation: {
kind: "retry",
summary: "Retry the task",
idempotencyKey: "retry-task",
},
}),
}),
).toEqual(
expect.objectContaining({
toStatus: "in_progress",
effects: [
expect.objectContaining({
kind: "enqueue_continuation",
continuationKind: "retry",
}),
],
}),
);
const externalChatWait = assessment({
reportedDisposition: "yielded",
continuation: {
kind: "response_wake",
summary: "Wait for the next authorized provider message",
idempotencyKey: "external-chat-wait",
},
});
expect(
arbitrate({
assessment: externalChatWait,
externalChatResponseWaitAuthorization: "authorized",
}),
).toEqual(
expect.objectContaining({
statusAction: "in_progress",
toStatus: "in_progress",
reasonCode: "external_chat_response_waiting",
effects: [],
}),
);
expect(
arbitrate({
assessment: externalChatWait,
externalChatResponseWaitAuthorization: "revoked",
}),
).toEqual(
expect.objectContaining({
statusAction: "preserve",
toStatus: "in_progress",
reasonCode: "external_chat_response_wait_authorization_lost",
effects: [],
}),
);
expect(
arbitrate({
assessment: externalChatWait,
externalChatResponseWaitAuthorization: "not_applicable",
}),
).toEqual(
expect.objectContaining({
statusAction: "in_progress",
reasonCode: "response_wake_waiting_for_input",
effects: [],
}),
);
expect(arbitrate({ terminalState: "cancelled" })).toEqual(
expect.objectContaining({
toStatus: "in_progress",
effects: [expect.objectContaining({ kind: "release_run_resources" })],
}),
);
expect(
arbitrate({ governanceGate: { kind: "interaction", id: "interaction" } }),
).toEqual(
expect.objectContaining({
toStatus: "in_review",
reasonCode: "governed_gate_pending",
effects: [
{
kind: "create_interaction",
gate: { kind: "interaction", id: "interaction" },
},
{
kind: "notify_owner",
agentId: "agent",
reason: "governed_gate_pending",
},
],
}),
);
expect(
arbitrate({
governanceGate: { kind: "interaction", id: "interaction" },
assessment: assessment({
reportedDisposition: "yielded",
continuation: {
kind: "response_wake",
summary: "Resume from the response",
idempotencyKey: "interaction-response:interaction",
},
}),
}),
).toEqual(
expect.objectContaining({
toStatus: "in_review",
reasonCode: "governed_response_waiting",
effects: [
{
kind: "create_interaction",
gate: { kind: "interaction", id: "interaction" },
},
],
}),
);
});
it("accepts low-risk completion claims with unrun verification caveats", () => {
const withCaveat = assessment({
verificationPassed: false,
criterionAssessments: [
{
criterionId: "objective",
claimStatus: "satisfied",
outcome: "missing",
evidenceRefs: [],
reasonCode: "criterion_evidence_missing",
},
],
verificationAssessments: [
{
commandOrCheck: "Run npm test",
claimStatus: "not_run",
outcome: "missing",
evidenceRef: null,
reasonCode: "verification_not_run",
reportedReasonCode: "tool_unavailable",
detail: "Node and npm are unavailable in this environment.",
},
],
verificationCaveats: [
{
commandOrCheck: "Run npm test",
reasonCode: "tool_unavailable",
detail: "Node and npm are unavailable in this environment.",
},
],
});
expect(
arbitrate({
assessment: withCaveat,
completionClaimPolicyAccepted: true,
}),
).toEqual(
expect.objectContaining({
toStatus: "done",
reasonCode: "completion_claim_policy_accepted",
}),
);
});
it("keeps failed verification with the agent and routes explicit attention to its owner", () => {
const failed = assessment({
verificationPassed: false,
hasFailedVerification: true,
verificationAssessments: [
{
commandOrCheck: "Run npm test",
claimStatus: "failed",
outcome: "rejected",
evidenceRef: null,
reasonCode: "verification_reported_failed",
reportedReasonCode: null,
detail: "One test failed.",
},
],
});
expect(
arbitrate({
assessment: failed,
completionClaimPolicyAccepted: true,
reviewOwnerUserId: "user-1",
}),
).toEqual(
expect.objectContaining({
toStatus: "in_progress",
reasonCode: "completion_evidence_incomplete",
effects: [
expect.objectContaining({
kind: "enqueue_continuation",
agentId: "agent",
}),
],
}),
);
const withAttention = assessment({
attentionRequests: [
{
kind: "approval",
summary: "Approve publication",
ownerClass: "human",
targetAgentId: null,
sourceIndex: 0,
sourceKind: "approval",
legacy: false,
},
],
});
expect(
arbitrate({
assessment: withAttention,
completionClaimPolicyAccepted: true,
}),
).toEqual(
expect.objectContaining({
toStatus: "in_review",
reasonCode: "actionable_attention_pending",
}),
);
});
it("blocks only for a task-wide blocker with a named owner and action", () => {
expect(
arbitrate({
assessment: assessment({
reportedDisposition: "blocked",
blocker: {
boardOwned: true,
scope: "task_wide",
unblockAction: "Approve access",
},
}),
}),
).toEqual(
expect.objectContaining({
toStatus: "blocked",
unblockDescriptor: { owner: "board", action: "Approve access" },
effects: [
{ kind: "bind_blocker", owner: "board", action: "Approve access" },
{
kind: "notify_owner",
agentId: "agent",
reason: "task_wide_blocker_bound",
},
],
}),
);
});
it("waits for an explicit unblock instead of inventing another productive track", () => {
expect(
arbitrate({
assessment: assessment({
reportedDisposition: "blocked",
objectiveClaimSatisfied: false,
objectiveSatisfied: false,
allCriteriaSatisfied: false,
verificationPassed: false,
hasBlockingRemainingWork: true,
blocker: {
boardOwned: false,
scope: "current_track",
unblockAction:
"Grant access to the current Board comment attachment, then explicitly retry.",
},
}),
}),
).toEqual(
expect.objectContaining({
statusAction: "blocked",
toStatus: "blocked",
policyVersion: "phase6-v14",
reasonCode: "current_track_blocker_waiting",
unblockDescriptor: {
owner: "board",
action:
"Grant access to the current Board comment attachment, then explicitly retry.",
},
effects: [
{
kind: "bind_blocker",
owner: "board",
action:
"Grant access to the current Board comment attachment, then explicitly retry.",
},
],
}),
);
});
it("blocks a current-track result when a durable dependency already gates the issue", () => {
expect(
arbitrate({
assessment: assessment({
reportedDisposition: "blocked",
blocker: {
boardOwned: false,
scope: "current_track",
unblockAction: "Wait for child task DOT-52",
},
}),
hasUnresolvedIssueBlockers: true,
}),
).toEqual(
expect.objectContaining({
statusAction: "blocked",
toStatus: "blocked",
reasonCode: "durable_dependency_blocker_bound",
unblockDescriptor: {
owner: { agentId: "agent" },
action: "Wait for child task DOT-52",
},
effects: [],
}),
);
});
it("lets a durable dependency override an optimistic done result", () => {
expect(
arbitrate({
assessment: assessment({ reportedDisposition: "done", blocker: null }),
completionClaimPolicyAccepted: true,
hasUnresolvedIssueBlockers: true,
}),
).toEqual(
expect.objectContaining({
statusAction: "blocked",
toStatus: "blocked",
reasonCode: "durable_dependency_blocker_bound",
effects: [],
}),
);
});
it("does not create a duplicate review after this run's review was already accepted", () => {
expect(
arbitrate({
assessment: assessment({
reportedDisposition: "needs_review",
attentionRequests: [
{
kind: "review",
summary: "Accept the plan",
ownerClass: "human",
targetAgentId: null,
sourceIndex: 0,
sourceKind: "review",
legacy: false,
},
],
}),
governanceResolvedForRun: true,
}),
).toEqual(
expect.objectContaining({
statusAction: "in_review",
reasonCode: "governance_response_continuation_queued",
effects: [],
}),
);
});
it("does not create a duplicate review after this run's planning confirmation was already accepted", () => {
expect(
arbitrate({
assessment: assessment({
reportedDisposition: "blocked",
attentionRequests: [
{
kind: "approval",
summary: "Accept the pinned plan revision.",
ownerClass: "human",
targetAgentId: null,
sourceIndex: 0,
sourceKind: "approval",
legacy: false,
},
],
}),
governanceResolvedForRun: true,
}),
).toEqual(
expect.objectContaining({
statusAction: "in_review",
reasonCode: "governance_response_continuation_queued",
effects: [],
}),
);
});
it("preserves authoritative terminal statuses", () => {
expect(arbitrate({ priorIssueStatus: "done" })).toEqual(
expect.objectContaining({
toStatus: "done",
reasonCode: "terminal_status_preserved",
effects: [],
}),
);
});
it("routes each explicit request to its own reviewer", () => {
const decision = arbitrate({ assessment: assessment({ attentionRequests: [
{ kind: "approval", summary: "Approve release", ownerClass: "human", targetAgentId: null, sourceIndex: 0, sourceKind: "approval", legacy: false },
{ kind: "review", summary: "Review code", ownerClass: "agent", targetAgentId: "review-agent", sourceIndex: 1, sourceKind: "review", legacy: false },
] }), reviewOwnerUserId: "release-owner" });
expect(decision.effects).toEqual([
expect.objectContaining({ kind: "bind_reviewer", requestKey: "attention-0", prompt: "Approve release", ownerUserId: "release-owner", ownerAgentId: null }),
expect.objectContaining({ kind: "bind_reviewer", requestKey: "attention-1", prompt: "Review code", ownerUserId: null, ownerAgentId: "review-agent" }),
]);
});
it("continues a system environment blocker in a fresh session, bounded, and never for a paused task or chat", () => {
const blocked = assessment({ reportedDisposition: "blocked", objectiveSatisfied: false, allCriteriaSatisfied: false,
blocker: { unblockAction: "Retry the run.", boardOwned: false, ownerKind: "system", scope: "task_wide" } });
expect(arbitrate({ assessment: blocked, environmentBlocker: true })).toMatchObject({ statusAction: "preserve",
reasonCode: "native_environment_blocker", effects: [{ kind: "schedule_retry", cause: "native_environment_blocker", agentId: "agent" }] });
expect(arbitrate({ assessment: blocked, environmentBlocker: true, failureRetryCount: 2 })).toMatchObject({ toStatus: "blocked",
reasonCode: "native_environment_blocker_exhausted", unblockDescriptor: { owner: "board" } });
for (const held of [{ hasActivePauseHold: true }, { isConversation: true }, { environmentBlocker: false }]) {
expect(arbitrate({ assessment: blocked, environmentBlocker: true, ...held })).toMatchObject({ reasonCode: "task_wide_blocker_bound" });
}
});
it("hands the next turn to a queued chat request instead of continuing a blocker in a fresh session", () => {
// A GitHub push that arrives during a review waits as a chat wake. A
// self-continuation would keep the older request's head and never publish.
const blocked = (ownerKind: "system" | "agent") => assessment({ reportedDisposition: "blocked", objectiveSatisfied: false,
allCriteriaSatisfied: false, blocker: { unblockAction: "Publish the review.", boardOwned: false, ownerKind, scope: "task_wide" } });
const superseded = { statusAction: "preserve", toStatus: "in_progress",
reasonCode: "native_blocker_superseded_by_queued_request", unblockDescriptor: null, effects: [{ kind: "release_checkout" }] };
expect(arbitrate({ assessment: blocked("system"), environmentBlocker: true, hasQueuedChatRequest: true })).toMatchObject(superseded);
expect(arbitrate({ assessment: blocked("agent"), agentBlockerRecoverable: true, hasQueuedChatRequest: true })).toMatchObject(superseded);
// Spent automatic continuations bind the blocker to the board, as without a queued request.
expect(arbitrate({ assessment: blocked("system"), environmentBlocker: true, hasQueuedChatRequest: true, failureRetryCount: 2 }))
.toMatchObject({ reasonCode: "native_environment_blocker_exhausted", toStatus: "blocked", unblockDescriptor: { owner: "board" } });
expect(arbitrate({ assessment: blocked("agent"), agentBlockerRecoverable: true, hasQueuedChatRequest: true, failureRetryCount: 1 }))
.toMatchObject({ reasonCode: "native_agent_blocker_needs_person", toStatus: "blocked" });
expect(arbitrate({ assessment: blocked("system"), environmentBlocker: true, hasQueuedChatRequest: true, hasActivePauseHold: true }))
.toMatchObject({ reasonCode: "task_wide_blocker_bound" });
// A blocker for a person or an external owner is bound now, as without a queued request.
for (const ownerKind of ["user", "external"] as const) {
const owned = assessment({ reportedDisposition: "blocked", objectiveSatisfied: false, allCriteriaSatisfied: false,
blocker: { unblockAction: "Add the deploy key.", boardOwned: false, ownerKind, scope: "task_wide" } });
expect(arbitrate({ assessment: owned, agentBlockerRecoverable: true, hasQueuedChatRequest: true }))
.toMatchObject({ reasonCode: "native_agent_blocker_needs_person", toStatus: "blocked" });
}
});
it("continues a blocker the agent owns once, then hands it to the board, and never binds it back to the agent", () => {
const blocked = (ownerKind: "agent" | "external") => assessment({ reportedDisposition: "blocked", objectiveSatisfied: false,
allCriteriaSatisfied: false, blocker: { unblockAction: "Save the ledger.", boardOwned: false, ownerKind, scope: "task_wide" } });
expect(arbitrate({ assessment: blocked("agent"), agentBlockerRecoverable: true })).toMatchObject({ statusAction: "preserve",
reasonCode: "native_agent_blocker_continuation", effects: [{ kind: "schedule_retry", cause: "native_agent_blocker_continuation", agentId: "agent" }] });
const handoff = { toStatus: "blocked", reasonCode: "native_agent_blocker_needs_person",
unblockDescriptor: { owner: "board", action: "Save the ledger." },
effects: [{ kind: "bind_blocker", owner: "board", action: "Save the ledger." }] };
expect(arbitrate({ assessment: blocked("agent"), agentBlockerRecoverable: true, failureRetryCount: 1 })).toMatchObject(handoff);
expect(arbitrate({ assessment: blocked("agent"), agentBlockerRecoverable: true, hasActivePauseHold: true })).toMatchObject(handoff);
expect(arbitrate({ assessment: blocked("external"), agentBlockerRecoverable: true })).toMatchObject(handoff);
for (const held of [{ isConversation: true }, { agentBlockerRecoverable: false }]) {
expect(arbitrate({ assessment: blocked("agent"), agentBlockerRecoverable: true, ...held })).toMatchObject({ reasonCode: "task_wide_blocker_bound" });
}
});
});