Files
PaperClipAI/server/src/services/native-runtime/status-arbiter.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

974 lines
40 KiB
TypeScript

import { COMPLETION_REVIEW_STAGE_REASON, COMPLETION_REVIEW_STAGE_REJECTED_REASON, type CompletionReviewStageEntry } from "../issue-execution-policy.js";
import type { NativeEvidenceAssessment } from "./evidence-classifier.js";
import { NATIVE_MODEL_REJECTION_MESSAGE, NATIVE_PROVIDER_CAPACITY_MAX_RETRIES, NATIVE_PROVIDER_OVERLOADED_CODE, NATIVE_PROVIDER_OVERLOADED_MESSAGE } from "./native-provider-failure.js";
import { NATIVE_TOOL_RECEIPT_LIMIT_CODE, NATIVE_TOOL_RECEIPT_LIMIT_MAX_CONTINUATIONS } from "./native-tool-receipt-limit.js";
import { NATIVE_ENVIRONMENT_BLOCKER_CODE, NATIVE_ENVIRONMENT_BLOCKER_EXHAUSTED_ACTION, NATIVE_ENVIRONMENT_BLOCKER_EXHAUSTED_CODE,
NATIVE_ENVIRONMENT_BLOCKER_MAX_RETRIES } from "./native-environment-blocker.js";
import { NATIVE_AGENT_BLOCKER_CONTINUATION_CODE, NATIVE_AGENT_BLOCKER_HANDOFF_CODE,
NATIVE_AGENT_BLOCKER_MAX_CONTINUATIONS } from "./native-agent-blocker.js";
export const NATIVE_STATUS_ARBITER_POLICY_VERSION = "phase6-v14";
/** The automatic continuation after a failed turn is used once per chain. */
export const NATIVE_RUN_FAILED_RETRY_CAUSE = "native_run_failed";
export const NATIVE_RESPONSE_WAKE_WAITING_REASON = "response_wake_waiting_for_input";
export const NATIVE_BLOCKER_SUPERSEDED_BY_QUEUED_REQUEST_CODE = "native_blocker_superseded_by_queued_request";
export const NATIVE_RUN_FAILED_CONTINUATION_EXHAUSTED_ACTION =
"The agent's turn failed again after Paperclip continued it automatically. The saved work is kept. Check the failed run, then Retry the task.";
export type NativeAuthoritativeIssueStatus =
| "backlog"
| "todo"
| "in_progress"
| "in_review"
| "blocked"
| "done"
| "cancelled";
export type NativeGovernanceGate = {
kind: "approval" | "interaction" | "execution_stage";
id: string;
};
export type NativeStatusEffect =
| { kind: "create_interaction"; gate?: NativeGovernanceGate; prompt?: string }
| {
kind: "bind_reviewer";
requestKey?: string;
prompt: string;
detailsMarkdown?: string | null;
ownerUserId?: string | null;
ownerAgentId?: string | null;
}
| { kind: "notify_owner"; agentId: string; reason: string }
| {
kind: "enqueue_continuation";
continuationKind:
| "same_agent"
| "retry"
| "delegated_issue"
| "response_wake"
| "monitor";
summary: string;
idempotencyKey: string;
agentId: string;
}
| {
kind: "bind_blocker";
owner: { agentId: string } | "board";
action: string;
}
| { kind: "schedule_retry"; cause: string; summary: string; agentId: string }
| {
kind: "record_finalization_error";
cause: string;
nextAction: string;
agentId: string;
}
| { kind: "release_run_resources" }
| { kind: "create_delegated_issue"; agentId: string; summary: string }
| { kind: "accept_replacement_turn" }
| { kind: "cancel_continuations" }
| { kind: "append_superseding_assessment" }
| { kind: "dispatch_pending_effect" }
| { kind: "increment_status_version" }
| { kind: "schedule_reconciliation" }
| { kind: "record_shadow_decision" }
| { kind: "render_four_layers" }
| { kind: "materialize_contract" }
| { kind: "record_mode_labeled_divergence" }
| { kind: "record_mode_native" }
| { kind: "record_policy_version" }
| { kind: "finish_as_native" }
| { kind: "resume_workspace_operation" }
| { kind: "record_expiry" }
| { kind: "record_stale_response" }
| { kind: "link_canonical_request" }
| {
kind: "record_recovery";
cause: string;
nextAction: string;
agentId: string;
}
| { kind: "release_checkout" };
export interface NativeStatusDecision {
policyVersion: typeof NATIVE_STATUS_ARBITER_POLICY_VERSION;
statusAction: NativeAuthoritativeIssueStatus | "preserve";
toStatus: NativeAuthoritativeIssueStatus;
reasonCode: string | null;
unblockDescriptor: {
owner: { agentId: string } | "board";
action: string;
} | null;
effects: NativeStatusEffect[];
blockerOwnerKind?: string;
}
/**
* Completion is the current owner's decision. A run whose task was reassigned
* away (to another agent or to a user) keeps its accepted result as history,
* but its done report cannot close the new owner's task.
*/
export function ownsNativeTaskCompletion(
issue: { assigneeAgentId: string | null; assigneeUserId: string | null },
agentId: string,
) {
return issue.assigneeAgentId === agentId && !issue.assigneeUserId;
}
export function heldByAnotherRun(issue: { executionRunId?: string | null }, runId: string) {
return Boolean(issue.executionRunId && issue.executionRunId !== runId);
}
/**
* The configured review policy decides a Done exactly as the issue route does:
* a stage that starts turns Done into its review, and a refused transition
* keeps the task open with a recovery note. Every Done-producing path applies it.
*/
export function gateDoneOnConfiguredReview(
decision: NativeStatusDecision,
stage: CompletionReviewStageEntry,
agentId: string,
): NativeStatusDecision {
if (decision.statusAction !== "done" || stage.kind === "none") return decision;
if (stage.kind === "starts") {
return { ...decision, statusAction: "in_review", toStatus: "in_review", reasonCode: COMPLETION_REVIEW_STAGE_REASON,
unblockDescriptor: null, effects: [{ kind: "release_checkout" }] };
}
return { ...decision, statusAction: "in_progress", toStatus: "in_progress", reasonCode: COMPLETION_REVIEW_STAGE_REJECTED_REASON,
unblockDescriptor: null, effects: [{ kind: "release_checkout" }, { kind: "record_recovery", cause: COMPLETION_REVIEW_STAGE_REJECTED_REASON,
nextAction: `The task's configured review policy cannot start its review: ${stage.message} Correct the review stages or participants; do not mark the task done.`,
agentId }] };
}
export function supersedeStaleOwnerCompletion(
decision: NativeStatusDecision,
issue: { status: string; assigneeAgentId: string | null; assigneeUserId: string | null;
executionRunId?: string | null },
agentId: string,
runId?: string,
): NativeStatusDecision {
if (decision.statusAction !== "done" && decision.reasonCode !== COMPLETION_REVIEW_STAGE_REASON) return decision;
const ownerSuperseded = !ownsNativeTaskCompletion(issue, agentId);
if (!ownerSuperseded && !(runId && heldByAnotherRun(issue, runId))) return decision;
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: issue.status as NativeAuthoritativeIssueStatus,
reasonCode: ownerSuperseded ? "completion_owner_superseded" : "completion_run_superseded",
unblockDescriptor: null,
effects: [],
};
}
/**
* Effects that give the outgoing agent more work on the task, wake it, or bind
* a blocker or reviewer to the task. None of them is valid once the task
* belongs to a person.
*/
const OUTGOING_AGENT_TASK_EFFECTS: ReadonlySet<NativeStatusEffect["kind"]> = new Set([
"enqueue_continuation", "schedule_retry", "notify_owner", "record_recovery",
"bind_blocker", "bind_reviewer", "create_delegated_issue", "accept_replacement_turn",
]);
/**
* A run that handed its own task to a person keeps running and finishes its
* turn. Its result is history: it cannot move the person's task, wake or
* retry the outgoing agent, or bind a blocker to the task. This also applies
* to decisions that already preserve the status.
*
* Two effects stay. A governed request still opens its interaction: the gate
* belongs to the request, not to the task owner. A failed workspace
* finalization still records its repair, so the run's saved work is not lost.
*/
export function supersedeHandedOffDecision(
decision: NativeStatusDecision,
issue: { status: string; assigneeAgentId: string | null; assigneeUserId: string | null },
): NativeStatusDecision {
if (issue.assigneeAgentId !== null || !issue.assigneeUserId) return decision;
// A finalization error only stays for a failed workspace save: it repairs
// and re-runs the save of the run's work. Other causes are task recovery.
const effects = decision.effects.filter(effect => !OUTGOING_AGENT_TASK_EFFECTS.has(effect.kind)
&& !(effect.kind === "record_finalization_error" && effect.cause !== "workspace_finalization_failed"));
const governed = effects.some(effect => effect.kind === "create_interaction");
if (decision.statusAction === "preserve" || governed) {
return effects.length === decision.effects.length ? decision : { ...decision, effects };
}
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: issue.status as NativeAuthoritativeIssueStatus,
reasonCode: "completion_owner_superseded",
unblockDescriptor: null,
effects,
};
}
/** Pure authority boundary: model prose is evidence, never a status command. */
export function arbitrateNativeStatus(input: {
assessment: NativeEvidenceAssessment;
terminalState: "succeeded" | "failed" | "cancelled";
workspaceFinalizeStatus: "succeeded" | "failed";
governanceGate?: NativeGovernanceGate | null;
completionClaimPolicyAccepted?: boolean;
/** Canonical exact-output human verdicts, only for an explicitly opted-in requirement. */
requiredQualityReviewSatisfied?: boolean;
allowIncompleteContinuation?: boolean;
/**
* True when the issue already has a durable unresolved dependency edge.
* A "current_track" result cannot remain in_progress in that state because
* checkout is intentionally gated until the dependency resolves.
*/
hasUnresolvedIssueBlockers?: boolean;
/** A newer native child result still has an undelivered parent wake. */
hasPendingChildCompletion?: boolean;
/** A governance interaction created by this run was accepted before the run settled. */
governanceResolvedForRun?: boolean;
externalChatResponseWaitAuthorization?:
"authorized" | "revoked" | "not_applicable";
hasUnprovenPreservedResultStatus?: boolean;
publishedExternalReview?: boolean;
/** Server-verified accepted plan request and normal provider terminal. */
planWaitAuthorized?: boolean;
monitorWaitAuthorized?: boolean;
caseHandoffAuthorized?: boolean;
/** The saved timer already admitted another run and this run no longer owns checkout. */
monitorWaitDispatched?: boolean;
monitorWaitPreserved?: boolean;
monitorWaitSuperseded?: boolean;
boardResponseWaitAuthorized?: boolean;
boardResponseWaitOrigin?: boolean;
isConversation?: boolean;
hasActivePauseHold?: boolean;
/** The run only compacted the agent's context; it carries no task outcome. */
contextCompactionRun?: boolean;
reviewOwnerUserId?: string | null;
/** Review decisions own task state; a reviewer's finish report cannot override them. */
nativeReviewOutcome?: "resolved" | "pending" | "stale";
toolCallLoopContinuation?: boolean;
/**
* This run, as the configured participant, recorded the approval that
* completed the task's final execution-policy stage. That durable decision is
* the completion authority for its done report, as the policy intends.
*/
executionStageApprovedByRun?: boolean;
/**
* Done would start the task's configured review stage. That reviewer, not
* the worker's evidence references, accepts the work, as on the issue route.
*/
executionReviewStageStarts?: boolean;
/** Re-derived from the committed runner terminal and pinned execution identity. */
providerModelRejected?: boolean;
providerOverloaded?: boolean;
providerFailureSuperseded?: boolean;
toolReceiptLimitStopped?: boolean;
/** The current owner's blocked report names a system-owned environment or tool outage. */
environmentBlocker?: boolean;
agentBlockerRecoverable?: boolean;
/** A chat request for this task and agent is waiting as a deferred wake behind this run. */
hasQueuedChatRequest?: boolean;
failureRetryCount?: number;
/**
* This run was itself the automatic continuation of an earlier failed turn.
* Another failure needs a person's Retry, never another automatic wake.
*/
failedTurnContinuationUsed?: boolean;
agentId: string;
priorIssueStatus: NativeAuthoritativeIssueStatus;
}): NativeStatusDecision {
if (input.contextCompactionRun) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "context_compaction_status_preserved",
unblockDescriptor: null,
effects: [],
};
}
if (["done", "cancelled"].includes(input.priorIssueStatus)) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "terminal_status_preserved",
unblockDescriptor: null,
effects: [],
};
}
if (input.workspaceFinalizeStatus !== "succeeded") {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "finalization_failed_claim_preserved",
unblockDescriptor: null,
effects: [
{
kind: "record_finalization_error",
cause: "workspace_finalization_failed",
nextAction:
"Repair and re-run workspace finalization for the persisted native result.",
agentId: input.agentId,
},
],
};
}
if (input.providerFailureSuperseded) return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: "provider_failure_authority_superseded", unblockDescriptor: null, effects: [],
};
if (input.caseHandoffAuthorized) return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: "case_handoff_waiting_for_release", unblockDescriptor: null,
effects: [{ kind: "release_checkout" }],
};
if (input.providerModelRejected && input.terminalState === "failed" &&
input.nativeReviewOutcome !== "stale" && input.nativeReviewOutcome !== "resolved") {
if (input.nativeReviewOutcome === "pending") {
// The pending review is bound to the worker's status decision and
// version. Preserve that authority so an explicit retry after a
// configuration repair can resolve the same review. In particular,
// do not create the normal unresolved-review recovery action.
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "native_provider_model_rejected",
unblockDescriptor: null,
effects: [{ kind: "release_checkout" }],
};
}
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "blocked",
toStatus: "blocked",
reasonCode: "native_provider_model_rejected",
unblockDescriptor: { owner: "board", action: NATIVE_MODEL_REJECTION_MESSAGE },
effects: [{ kind: "bind_blocker", owner: "board", action: NATIVE_MODEL_REJECTION_MESSAGE }],
};
}
if (input.providerOverloaded && input.terminalState === "failed" &&
input.nativeReviewOutcome !== "stale" && input.nativeReviewOutcome !== "resolved") {
const held = input.governanceGate || input.hasUnresolvedIssueBlockers || input.hasActivePauseHold || input.priorIssueStatus === "blocked";
const exhausted = (input.failureRetryCount ?? 0) >= NATIVE_PROVIDER_CAPACITY_MAX_RETRIES;
if (held || (exhausted && input.nativeReviewOutcome === "pending")) return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: held ? "native_provider_overloaded_held" : "native_provider_overloaded_exhausted",
unblockDescriptor: null, effects: [{ kind: "release_checkout" }],
};
if (exhausted) {
const action = `${NATIVE_PROVIDER_OVERLOADED_MESSAGE} Automatic retries exhausted; retry later or choose a different model.`;
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "blocked", toStatus: "blocked", reasonCode: "native_provider_overloaded_exhausted",
unblockDescriptor: { owner: "board", action },
effects: [{ kind: "bind_blocker", owner: "board", action }],
};
}
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: NATIVE_PROVIDER_OVERLOADED_CODE, unblockDescriptor: null,
effects: [
{ kind: "schedule_retry", cause: NATIVE_PROVIDER_OVERLOADED_CODE, summary: "Retry after model capacity becomes available.", agentId: input.agentId },
...(input.nativeReviewOutcome === "pending" ? [{ kind: "release_checkout" as const }] : []),
],
};
}
if (input.toolReceiptLimitStopped && input.terminalState !== "succeeded" && !input.nativeReviewOutcome &&
!input.governanceGate && !input.hasUnresolvedIssueBlockers && !input.hasActivePauseHold &&
input.priorIssueStatus !== "blocked" &&
(input.failureRetryCount ?? 0) < NATIVE_TOOL_RECEIPT_LIMIT_MAX_CONTINUATIONS) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: NATIVE_TOOL_RECEIPT_LIMIT_CODE, unblockDescriptor: null,
effects: [
{ kind: "schedule_retry", cause: NATIVE_TOOL_RECEIPT_LIMIT_CODE, summary: "Continue the task in a fresh session.", agentId: input.agentId },
...(input.terminalState === "cancelled" ? [{ kind: "release_run_resources" as const }] : []),
],
};
}
if (input.nativeReviewOutcome) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: input.nativeReviewOutcome === "pending" ? "native_review_unresolved" : "native_review_action_finished",
unblockDescriptor: null,
effects: [
{ kind: "release_checkout" },
...(input.nativeReviewOutcome === "pending" && !input.toolCallLoopContinuation ? [{
kind: "record_recovery" as const, cause: "native_review_unresolved",
nextAction: "The named reviewer must resolve the pending completion review or explain the concrete blocker. Do not restart the worker's assignment or create another review request.",
agentId: input.agentId,
}] : []),
],
};
}
if (input.terminalState !== "succeeded") {
if (input.terminalState === "cancelled") {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "cancellation_run_only",
unblockDescriptor: null,
effects: [{ kind: "release_run_resources" }],
};
}
if (input.failedTurnContinuationUsed) {
// The automatic continuation already ran and failed too. Keep the work
// and hand the next attempt to a person instead of waking again.
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "blocked",
toStatus: "blocked",
reasonCode: "native_run_failed_continuation_exhausted",
unblockDescriptor: { owner: "board", action: NATIVE_RUN_FAILED_CONTINUATION_EXHAUSTED_ACTION },
effects: [{ kind: "bind_blocker", owner: "board", action: NATIVE_RUN_FAILED_CONTINUATION_EXHAUSTED_ACTION }],
};
}
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "run_failed_partial_evidence_preserved",
unblockDescriptor: null,
effects: [
{
kind: "schedule_retry",
cause: NATIVE_RUN_FAILED_RETRY_CAUSE,
summary:
"Resume the persisted native run without opening a second provider session.",
agentId: input.agentId,
},
],
};
}
if (input.governanceGate) {
if (
input.assessment.reportedDisposition === "yielded" &&
input.assessment.continuation?.kind === "response_wake"
) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_review",
toStatus: "in_review",
reasonCode: "governed_response_waiting",
unblockDescriptor: null,
// The existing interaction is the liveness path. Its authoritative
// resolution owns the response wake; dispatching one now would start a
// duplicate provider turn before the human has answered.
effects: [{ kind: "create_interaction", gate: input.governanceGate }],
};
}
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_review",
toStatus: "in_review",
reasonCode: "governed_gate_pending",
unblockDescriptor: null,
effects: [
{ kind: "create_interaction", gate: input.governanceGate },
{
kind: "notify_owner",
agentId: input.agentId,
reason: "governed_gate_pending",
},
],
};
}
if (
input.governanceResolvedForRun === true &&
["needs_review", "blocked"].includes(
input.assessment.reportedDisposition,
) &&
input.assessment.attentionRequests.length > 0 &&
input.assessment.attentionRequests.every(
(request) =>
request.ownerClass === "human" &&
["review", "approval"].includes(request.kind),
)
) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_review",
toStatus: "in_review",
reasonCode: "governance_response_continuation_queued",
unblockDescriptor: null,
// The accepted interaction already queued the response wake. Creating a
// second completion-review interaction here would strand that continuation.
// Planning turns commonly report `blocked` while awaiting their own
// confirmation; once accepted, that response wake is authoritative too.
effects: [],
};
}
const unfinishedResponseWait =
!input.isConversation &&
!["authorized", "revoked"].includes(input.externalChatResponseWaitAuthorization ?? "") &&
input.assessment.reportedDisposition === "yielded" &&
input.assessment.continuation?.kind === "response_wake" &&
input.assessment.hasBlockingRemainingWork;
if (
input.hasUnresolvedIssueBlockers === true &&
(["done", "blocked"].includes(input.assessment.reportedDisposition) || unfinishedResponseWait || input.assessment.continuation?.kind === "monitor")
) {
const owner = input.assessment.blocker?.boardOwned
? ("board" as const)
: { agentId: input.agentId };
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "blocked",
toStatus: "blocked",
reasonCode: "durable_dependency_blocker_bound",
unblockDescriptor: {
owner,
action:
input.assessment.blocker?.unblockAction ??
"Wait for the issue's durable dependency blockers to complete.",
},
// Dependency completion owns the wake. Do not immediately rerun the
// blocked issue merely because the provider mislabeled its scope/status.
effects: [],
};
}
if (input.requiredQualityReviewSatisfied === false && input.assessment.reportedDisposition === "done") {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_progress", toStatus: "in_progress",
reasonCode: "required_quality_review_incomplete", unblockDescriptor: null,
effects: [{ kind: "release_checkout" }, { kind: "record_recovery", cause: "required_quality_review_incomplete",
nextAction: "Request or resume the task's required quality review for exact output versions; do not repeat completed work or create a generic completion approval.", agentId: input.agentId }],
};
}
const evidenceComplete =
input.assessment.reportedDisposition === "done" &&
input.assessment.objectiveSatisfied &&
input.assessment.allCriteriaSatisfied &&
input.assessment.verificationPassed &&
!input.assessment.hasFailedVerification &&
input.assessment.attentionRequests.length === 0 &&
!input.assessment.hasBlockingRemainingWork;
const policyClaimComplete =
input.completionClaimPolicyAccepted === true &&
input.assessment.reportedDisposition === "done" &&
input.assessment.contractRevisionMatches &&
input.assessment.objectiveClaimSatisfied &&
input.assessment.criterionAssessments.length > 0 &&
input.assessment.criterionAssessments.every(
(entry) => entry.claimStatus === "satisfied",
) &&
!input.assessment.hasFailedVerification &&
input.assessment.attentionRequests.length === 0 &&
!input.assessment.hasBlockingRemainingWork;
const stageApprovalComplete =
input.executionStageApprovedByRun === true &&
input.assessment.reportedDisposition === "done" &&
!input.assessment.hasFailedVerification &&
input.assessment.attentionRequests.length === 0 &&
!input.assessment.hasBlockingRemainingWork;
const reviewStageClaim =
input.executionReviewStageStarts === true &&
input.assessment.reportedDisposition === "done" &&
input.assessment.objectiveClaimSatisfied &&
!input.assessment.hasFailedVerification &&
input.assessment.attentionRequests.length === 0 &&
!input.assessment.hasBlockingRemainingWork;
const complete = evidenceComplete || policyClaimComplete || stageApprovalComplete || reviewStageClaim;
if (complete && input.hasPendingChildCompletion) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_progress",
toStatus: "in_progress",
reasonCode: "native_child_completion_pending",
unblockDescriptor: null,
// The durable outbox/deferred wake already owns exactly one continuation.
effects: [{ kind: "release_checkout" }],
};
}
if (complete && input.executionReviewStageStarts === true) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_review",
toStatus: "in_review",
reasonCode: COMPLETION_REVIEW_STAGE_REASON,
unblockDescriptor: null,
effects: [{ kind: "release_checkout" }],
};
}
if (complete) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "done",
toStatus: "done",
reasonCode: !evidenceComplete && !policyClaimComplete
? "execution_stage_approved"
: input.completionClaimPolicyAccepted
? "completion_claim_policy_accepted"
: "completion_contract_satisfied",
unblockDescriptor: null,
effects: [{ kind: "release_checkout" }],
};
}
// A completion claim is not a request for human approval. Only a concrete,
// explicitly reported attention request may create a review interaction.
if (input.assessment.attentionRequests.length > 0) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_review",
toStatus: "in_review",
reasonCode: "actionable_attention_pending",
unblockDescriptor: null,
effects: input.assessment.attentionRequests.map((request, index) => ({
kind: "bind_reviewer",
requestKey: `attention-${index}`,
prompt: request.summary.slice(0, 1_000),
detailsMarkdown: input.assessment.summary,
ownerUserId: request.ownerClass === "agent" ? null : (input.reviewOwnerUserId ?? null),
ownerAgentId: request.ownerClass === "agent" ? request.targetAgentId : null,
})),
};
}
// A newer chat request waits behind this run. It starts the next turn with
// its own source binding and the full task history. A fresh-session
// continuation would inherit this run's older request instead, and would
// hold the task so the newer request never runs. Only a blocker that the
// lanes below would continue automatically yields. A blocker for a person or
// an external owner, or one whose automatic continuations are spent, is still
// bound now.
const blocker = input.assessment.blocker;
const retries = input.failureRetryCount ?? 0;
const continuesAutomatically = Boolean(blocker) && !input.isConversation && !input.hasActivePauseHold && (
(input.environmentBlocker === true && retries < NATIVE_ENVIRONMENT_BLOCKER_MAX_RETRIES) ||
(input.agentBlockerRecoverable === true && blocker!.scope === "task_wide" && !blocker!.boardOwned &&
blocker!.ownerKind === "agent" && retries < NATIVE_AGENT_BLOCKER_MAX_CONTINUATIONS));
if (input.assessment.reportedDisposition === "blocked" && input.hasQueuedChatRequest && continuesAutomatically) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: NATIVE_BLOCKER_SUPERSEDED_BY_QUEUED_REQUEST_CODE, unblockDescriptor: null,
effects: [{ kind: "release_checkout" }],
};
}
if (
input.assessment.reportedDisposition === "blocked" &&
input.assessment.blocker &&
input.environmentBlocker &&
!input.isConversation &&
!input.hasActivePauseHold
) {
if ((input.failureRetryCount ?? 0) < NATIVE_ENVIRONMENT_BLOCKER_MAX_RETRIES) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: NATIVE_ENVIRONMENT_BLOCKER_CODE, unblockDescriptor: null,
effects: [{ kind: "schedule_retry", cause: NATIVE_ENVIRONMENT_BLOCKER_CODE,
summary: "Continue the task in a fresh session.", agentId: input.agentId }],
};
}
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "blocked", toStatus: "blocked",
reasonCode: NATIVE_ENVIRONMENT_BLOCKER_EXHAUSTED_CODE,
blockerOwnerKind: input.assessment.blocker.ownerKind,
unblockDescriptor: { owner: "board", action: NATIVE_ENVIRONMENT_BLOCKER_EXHAUSTED_ACTION },
effects: [{ kind: "bind_blocker", owner: "board", action: NATIVE_ENVIRONMENT_BLOCKER_EXHAUSTED_ACTION }],
};
}
if (
input.assessment.reportedDisposition === "blocked" &&
input.assessment.blocker?.scope === "task_wide" &&
!input.assessment.blocker.boardOwned &&
input.agentBlockerRecoverable &&
!input.isConversation
) {
if (input.assessment.blocker.ownerKind === "agent" && !input.hasActivePauseHold &&
(input.failureRetryCount ?? 0) < NATIVE_AGENT_BLOCKER_MAX_CONTINUATIONS) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: NATIVE_AGENT_BLOCKER_CONTINUATION_CODE, unblockDescriptor: null,
effects: [{ kind: "schedule_retry", cause: NATIVE_AGENT_BLOCKER_CONTINUATION_CODE,
summary: "Continue the task once in a fresh session.", agentId: input.agentId }],
};
}
const action = input.assessment.blocker.unblockAction;
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "blocked", toStatus: "blocked",
reasonCode: NATIVE_AGENT_BLOCKER_HANDOFF_CODE,
blockerOwnerKind: input.assessment.blocker.ownerKind,
unblockDescriptor: { owner: "board", action },
effects: [{ kind: "bind_blocker", owner: "board", action }],
};
}
if (
input.assessment.reportedDisposition === "blocked" &&
input.assessment.blocker
) {
const owner = input.assessment.blocker.boardOwned
? ("board" as const)
: { agentId: input.agentId };
if (input.assessment.blocker.scope === "task_wide") {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "blocked",
toStatus: "blocked",
reasonCode: "task_wide_blocker_bound",
blockerOwnerKind: input.assessment.blocker.ownerKind,
unblockDescriptor: {
owner,
action: input.assessment.blocker.unblockAction,
},
effects: [
{
kind: "bind_blocker",
owner,
action: input.assessment.blocker.unblockAction,
},
{
kind: "notify_owner",
agentId: input.agentId,
reason: "task_wide_blocker_bound",
},
],
};
}
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "blocked",
toStatus: "blocked",
reasonCode: "current_track_blocker_waiting",
blockerOwnerKind: input.assessment.blocker.ownerKind,
// A provider's current_track label is not evidence that another
// authorized, productive track exists. Bind the actual unblock request
// without waking the same agent to repeat the blocked work or old title.
unblockDescriptor: {
owner: "board",
action: input.assessment.blocker.unblockAction,
},
effects: [
{
kind: "bind_blocker",
owner: "board",
action: input.assessment.blocker.unblockAction,
},
],
};
}
if (input.assessment.reportedDisposition === "yielded" && input.assessment.continuation?.kind === "monitor") {
if (input.monitorWaitDispatched) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: "scheduled_monitor_dispatched", unblockDescriptor: null,
// Delivery already happened. Preserve successor ownership and never
// re-arm its timer or repeat the completed provider turn.
effects: [],
};
}
if (input.monitorWaitSuperseded) return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: "scheduled_monitor_superseded", unblockDescriptor: null, effects: [],
};
if (input.monitorWaitPreserved) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: "scheduled_monitor_preserved", unblockDescriptor: null, effects: [],
};
}
if (input.monitorWaitAuthorized) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: input.publishedExternalReview ? "in_review" : "preserve",
toStatus: input.publishedExternalReview ? "in_review" : input.priorIssueStatus,
reasonCode: "scheduled_monitor_waiting", unblockDescriptor: null,
// The persisted timer owns delivery, never enqueue an immediate wake.
effects: [{ kind: "release_checkout" }],
};
}
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: "monitor_wait_authority_lost", unblockDescriptor: null,
effects: [{ kind: "record_finalization_error", cause: "monitor_wait_authority_lost",
nextAction: "The scheduled monitor was cleared or became ineligible. Re-establish a valid task action path.",
agentId: input.agentId }],
};
}
if (
input.assessment.reportedDisposition === "yielded" &&
input.assessment.continuation?.kind === "response_wake" &&
input.externalChatResponseWaitAuthorization === "authorized"
) {
if (input.hasUnprovenPreservedResultStatus) return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve", toStatus: input.priorIssueStatus,
reasonCode: "preserved_result_status_unproven", unblockDescriptor: null, effects: [],
};
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: input.publishedExternalReview ? "in_review" : "in_progress",
toStatus: input.publishedExternalReview ? "in_review" : "in_progress",
reasonCode: "external_chat_response_waiting",
unblockDescriptor: null,
// The active, authorized provider conversation is the durable liveness
// path. Only its next admitted message may enqueue the response wake.
effects: [],
};
}
if (
input.assessment.reportedDisposition === "yielded" &&
input.assessment.continuation?.kind === "response_wake" &&
input.externalChatResponseWaitAuthorization === "revoked"
) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "external_chat_response_wait_authorization_lost",
unblockDescriptor: null,
// Revocation cannot be converted into an unrequested background run.
effects: [],
};
}
if (unfinishedResponseWait && input.hasActivePauseHold) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "response_wait_pause_preserved",
unblockDescriptor: null,
effects: [],
};
}
if (
input.assessment.reportedDisposition === "yielded" &&
input.assessment.continuation?.kind === "response_wake" &&
input.boardResponseWaitAuthorized === true &&
!unfinishedResponseWait
) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_progress",
toStatus: "in_progress",
reasonCode: "board_response_waiting",
unblockDescriptor: null,
// The committer proves the current Board cause again before persisting
// the wait. Only a new user cause may wake this completed response.
effects: [],
};
}
if (
input.assessment.reportedDisposition === "yielded" &&
input.assessment.continuation?.kind === "response_wake" &&
input.boardResponseWaitOrigin &&
!input.boardResponseWaitAuthorized
) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "board_response_wait_superseded",
unblockDescriptor: null,
effects: [],
};
}
if (
input.planWaitAuthorized === true &&
input.assessment.reportedDisposition === "yielded" &&
input.assessment.continuation?.kind === "response_wake"
) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_progress", toStatus: "in_progress",
reasonCode: "native_plan_accepted_waiting_for_continuation",
unblockDescriptor: null,
// An answered native plan is not task completion or permission to
// change modes. Only a new explicit user cause may continue the work.
effects: [],
};
}
if (
input.assessment.reportedDisposition === "yielded" &&
input.assessment.continuation?.kind === "response_wake" &&
!unfinishedResponseWait
) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_progress",
toStatus: "in_progress",
reasonCode: NATIVE_RESPONSE_WAKE_WAITING_REASON,
unblockDescriptor: null,
effects: [],
};
}
if (
input.assessment.reportedDisposition === "yielded" &&
input.assessment.continuation &&
input.assessment.continuation.kind !== "case_handoff" &&
!unfinishedResponseWait
) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_progress",
toStatus: "in_progress",
reasonCode: "live_continuation_registered",
unblockDescriptor: null,
effects: [
{
kind: "enqueue_continuation",
continuationKind: input.assessment.continuation.kind,
summary: input.assessment.continuation.summary,
idempotencyKey: input.assessment.continuation.idempotencyKey,
agentId: input.agentId,
},
],
};
}
// A current response that admits blocking work must use the server's bounded
// repair path, not a passive wait or a model-chosen continuation retry key.
if (input.allowIncompleteContinuation === false) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "prior_status_preserved_no_live_path",
unblockDescriptor: null,
effects: [
{
kind: "record_finalization_error",
cause: "completion_evidence_incomplete",
nextAction:
"Bind a durable continuation or a named recovery owner before changing issue status.",
agentId: input.agentId,
},
],
};
}
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "in_progress",
toStatus: "in_progress",
reasonCode: "completion_evidence_incomplete",
unblockDescriptor: null,
effects: [
{
kind: "enqueue_continuation",
continuationKind: "same_agent",
summary:
"Finish the remaining work and report done, or explicitly request a named reviewer decision. Waiting for checks or an incomplete completion report does not require human approval.",
idempotencyKey: "native-completion-incomplete",
agentId: input.agentId,
},
],
};
}