Files
PaperClipAI/ui/src/components/ExecutionBlockerNotice.test.tsx
T
DottaandClaude Opus 5.5 1c556d5340 fix(native): never rest a task blocked on the agent's own blocker (#22140)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A native run ends with one semantic report. A `paperclip_block`
report names a blocker, its owner and the unblock action
> - The status arbiter binds a task-wide blocker. When the owner is not
a person, it binds the blocker to the same agent and wakes that agent
> - The dispatcher refuses those self-wakes
(`chat_control_recovery_proof_unresolved`), because only continuation
and retry effects are proof for a native wake. The task then rests
blocked with no owner, no wake and no Retry
> - #21959 continues a system blocker in a fresh session, but only for
the reason codes `environment_unavailable` and `tool_unavailable`. A
restart-chaos rerun showed the same dead end with the reason code
`tool_output_failure`
> - This pull request makes sure that a blocker that the agent reports
for itself always has a next owner: the automatic environment lane, one
bounded self-continuation, or a person with a Retry that works
> - The benefit is that no task rests blocked with nobody to act, and no
path wakes the agent in a loop

## Linked Issues or Issue Description

Refs #21959

**What happened?**

A native OpenCode run (DeepSeek) said that every tool call returned the
text "cryptic". It reported `paperclip_block` with owner `{kind:
system}`, scope `task_wide`, reason code `tool_output_failure`, and an
unblock action about the tool-output failure. The run succeeded with
disposition `blocked`. The arbiter bound the blocker to the same agent
(`task_wide_blocker_bound`). The `notify-owner` wake coalesced, and the
`blocker-owner` wake was skipped as
`chat_control_recovery_proof_unresolved`. The task rested blocked
(`needs_attention`, 0 blockers), with no Retry and no wake. An earlier
rerun showed the same shape with reason code `environment_unavailable`,
which #21959 fixed for those two codes only.

**Expected behavior**

A blocker that the agent reports for its own tools or environment is a
harness problem. Paperclip continues it automatically, with a bound. A
blocker that the agent says it owns gets one fresh session. A blocker
that needs a person goes to a person, with a clear prompt and a Retry
that starts the task again. Nothing is left with nobody.

**Steps to reproduce**

1. Run a native task. Make the agent call `paperclip_block` with owner
kind `system`, scope `task_wide` and a reason code other than
`environment_unavailable` or `tool_unavailable` (for example
`tool_output_failure`).
2. See the decision `task_wide_blocker_bound` with the agent as the
unblock owner.
3. See both owner wakes refused, and the task blocked with no Retry.

**Paperclip version or commit**

`master` at 9e1a85fb46.

## What Changed

- `native-environment-blocker.ts`: a system-owned blocker now uses the
bounded fresh-session environment lane for any reason code, except the
person-only codes `permission_denied`, `credential_missing`,
`policy_restricted` and `budget_exhausted`. An agent-owned blocker with
`environment_unavailable` or `tool_unavailable` also uses it. The lane
is unchanged: at most 2 retries on the shared failure counter, then a
board blocker.
- New `native-agent-blocker.ts` and a new arbiter branch for a task-wide
blocker that is not person-owned, from the current owner's own succeeded
run (not a chat, not a review):
- Owner kind `agent`: one fresh-session continuation
(`native_agent_blocker_continuation`). It uses the shared failure
counter with a maximum of 1, so it never runs after another automatic
retry in the same chain. A paused task does not get it.
- All other cases, and a repeated blocker: the blocker goes to the board
with the agent's unblock action (`native_agent_blocker_needs_person`).
There is no self-wake.
- `native-provider-capacity-retry.ts`, `status-decision-committer.ts`,
`native-run-finalizer.ts`: materialize the continuation through the
existing fresh-session retry lane (`forceFreshSession`, `retryOfRunId`,
30 s delay, refuses a stopped run). Both new reason codes need the
provider-failure owner recheck under the issue lock. The finalizer reads
the pause hold for every blocked result.
- `heartbeat.ts`, `run-dispatch/adapters/postgres.ts`: the continuation
gets the same dispatch ownership checks as the environment retry.
- `task-interruption-presentation.ts`, shared
`TaskInterruptionPresentation.userAction`: a task that is blocked by a
`native_agent_blocker_needs_person` decision on its latest run shows
`userAction: "unblock"` with `canRetry: true`. `ExecutionBlockerNotice`
shows "The agent stopped and needs your help to continue. Read its last
comment, do what it asks, then Retry." with a Retry button. The inbox
label is "The agent needs your help". The assigned-work invariant reads
it as `assignee_declared_block`.
- `blocked-question-answer.ts`: an answer to the agent's open question
still wakes it after the new hand-off.
- Runner `completion-result.ts`: the "Paperclip continues this blocker
automatically" message now matches the server's environment lane.
- I did not change `readChatControlNativeParent`. The fix removes the
self-bound blocker wakes instead of accepting them as proof, so a
self-wake loop cannot form.

## Verification

- `cd server && npx vitest run
src/services/native-runtime/native-agent-blocker.integration.test.ts`
(new, embedded Postgres, real executor, finalizer and committer). Red
before the fix (3 of 3 fail with `task_wide_blocker_bound`), green
after:
- The t205 shape (system owner, `tool_output_failure`) gets one
fresh-session retry, no owner wakes, and the retry run that reports done
moves the task to `done`.
- An agent-owned blocker continues once. The same blocker in the
continuation goes to the board, with no further retry and no owner
wakes.
- A system blocker with `credential_missing` goes to the board with no
automatic retry.
- An external-owned blocker goes to the board. The task shows
`userAction: "unblock"` and `canRetry: true`. `requestTaskRetry` accepts
the Retry and `resumeTaskRetry` starts exactly one new run of the task.
- `npx vitest run src/services/native-runtime/status-arbiter.test.ts`:
new case for the once-only continuation, the hand-off, the pause hold,
the chat exclusion and the non-owner exclusion.
- `cd ui && npx vitest run
src/components/ExecutionBlockerNotice.test.tsx`: new case for the help
prompt and its Retry.
- `cd packages/paperclip-runner && npx vitest run
src/contracts/completion-result.test.ts`: new cases for the conflict
message.
- Related suites pass (11 files, 523 tests): arbiter corpus,
task-interruption presentation and query, assigned-work invariant,
blocked-question answer, liveness escalation, run-dispatch adapter,
failed-turn continuation, tool-receipt limit and provider capacity.
- `tsc --noEmit` passes for `server`, `packages/shared`,
`packages/paperclip-runner` and `ui` (only the existing generated
Storybook catalog errors). `scripts/check-token-gates.mjs` is clean.
- `pnpm verify` exits 2: the source SDK pin refresh is a global CI
input, so required CI supplies the broad coverage.

## Risks

- More automatic runs: an agent-owned blocker can add 1 run per chain,
and a system blocker with a new reason code can add up to 2 (the
existing lane). Both share the failure-retry counter, so a chain never
gets more than the existing maximum. The company-wide automatic-run
brake admits these runs like any other recovery run. Judge the change by
company-wide automatic run starts per hour and their success rate.
- A blocker that only a person can resolve, but that the agent labels as
its own, now takes one extra run (about 30 s later) before it reaches a
person. This is intended.
- Board-owned blockers now show an attention card and a Retry, where
before they named the agent and showed nothing. A Retry starts a new run
of the task; the person decides when.
- Previous release: no persisted shape changes. The new reason codes are
new values in existing text columns. Decisions saved by the previous
release keep their saved effects.
- Chats keep their current behavior, because the person in the chat
answers directly.

> 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 (Anthropic), model ID `claude-opus-5-5`, used through
Claude Code with tool use (code search, editing, shell, test runs).

## 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-18 02:43:28 -06:00

225 lines
16 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// @vitest-environment jsdom
import { act } from "react";
import { createRoot, type Root } from "react-dom/client";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { TaskInterruptionPresentation } from "@paperclipai/shared";
import type { AnchorHTMLAttributes } from "react";
import { ExecutionBlockerNotice } from "./ExecutionBlockerNotice";
vi.mock("@/lib/router", () => ({
Link: ({ children, to, ...props }: AnchorHTMLAttributes<HTMLAnchorElement> & { to: string }) => <a href={to} {...props}>{children}</a>,
}));
const failed: TaskInterruptionPresentation = {
intentId: "intent", responsibility: "system", state: "failed", nextRetryAt: null,
canRetry: true, userAction: null, sourceRunIds: ["source"], observedRunId: "source",
};
describe("ordinary task interruption", () => {
let root: Root;
let container: HTMLDivElement;
const retry = vi.fn();
beforeEach(() => {
retry.mockReset(); container = document.createElement("div"); document.body.append(container);
root = createRoot(container);
});
afterEach(async () => { await act(async () => root.unmount()); container.remove(); vi.useRealTimers(); });
const render = async (presentation = failed, options: { canRetry?: boolean; optimistic?: boolean; takingLonger?: boolean; error?: Error } = {}) => {
await act(async () => root.render(<ExecutionBlockerNotice presentation={presentation} canRetry onRetry={retry} {...options} />));
};
it("offers one Retry without delegating infrastructure chores", async () => {
await render();
expect(container.textContent).toContain("Couldn’t finish this attempt. Your message is saved.");
expect(container.querySelectorAll("button")).toHaveLength(1);
// A stable handle for the task's own Retry, the supported path after
// automatic recovery stops.
expect(container.querySelector('[data-testid="task-execution-retry"]')?.textContent).toBe("Retry");
await act(async () => container.querySelector<HTMLButtonElement>("button")!.click());
expect(retry).toHaveBeenCalledOnce();
expect(container.querySelector("a, details, input, textarea")).toBeNull();
expect(container.textContent).not.toMatch(/service attention|process|receipt|workspace/i);
});
it("asks the person to help a blocked agent and offers Retry", async () => {
await render({ ...failed, responsibility: "user", state: "waiting_for_user", userAction: "unblock" });
expect(container.textContent).toContain("needs your help to continue");
expect(container.textContent).not.toMatch(/blocker_|native|owner kind/i);
await act(async () => container.querySelector<HTMLButtonElement>('[data-testid="task-execution-retry"]')!.click());
expect(retry).toHaveBeenCalledOnce();
});
it("keeps the failure visible and names the gate while a saved Retry waits on the budget", async () => {
await render({ ...failed, responsibility: "user", state: "waiting_for_user", userAction: "budget", canRetry: false });
const notice = container.querySelector('[data-testid="task-execution-waiting"]');
expect(notice?.textContent).toContain("Couldn’t finish this attempt. Your message is saved.");
expect(notice?.textContent).toContain("waiting for the budget to allow new work");
// The saved Retry starts by itself; a second Retry would only duplicate it.
expect(container.querySelector("button")).toBeNull();
});
it("does not report a failed attempt for a task the budget held before its first run", async () => {
await render({ ...failed, responsibility: "user", state: "waiting_for_user", userAction: "budget", canRetry: false,
sourceRunIds: [], observedRunId: null });
const notice = container.querySelector('[data-testid="task-execution-waiting"]');
expect(notice?.textContent).toContain("This task has not started.");
expect(notice?.textContent).not.toContain("Couldn’t finish this attempt");
});
it("shows persisted backoff with a usable Retry", async () => {
vi.useFakeTimers(); vi.setSystemTime(new Date("2026-10-20T00:00:00Z"));
await render({ ...failed, state: "retry_scheduled", nextRetryAt: "2026-10-20T00:00:30Z" });
expect(container.textContent).toContain("Trying again in 30s");
await act(async () => { await vi.advanceTimersByTimeAsync(5_000); });
expect(container.textContent).toContain("Trying again in 25s");
expect(container.querySelector("button")?.textContent).toBe("Retry");
});
it.each(["working", "resolved"] as const)("does not duplicate the thread indicator for %s", async state => {
await render({ ...failed, state }); expect(container.textContent).toBe("");
});
it("offers to move a waiting continuation forward in plain words, without reporting a failure", async () => {
await render({ ...failed, state: "working", retryAction: "move_forward" });
expect(container.textContent).toContain("Paperclip continues this task by itself.");
expect(container.textContent).not.toMatch(/Couldn’t finish|failed|continuation|queue|run\b/i);
const button = container.querySelector<HTMLButtonElement>('[data-testid="task-execution-move-forward"]');
expect(button?.textContent).toBe("Move it forward now");
expect(container.querySelectorAll("button")).toHaveLength(1);
await act(async () => button!.click());
expect(retry).toHaveBeenCalledOnce();
});
it("shows a waiting continuation without the button to a read-only user, or once the move was requested", async () => {
await act(async () => root.render(<ExecutionBlockerNotice presentation={{ ...failed, state: "working", retryAction: "move_forward" }}
canRetry={false} onRetry={retry} />));
expect(container.textContent).toContain("Paperclip continues this task by itself.");
expect(container.querySelector("button")).toBeNull();
await render({ ...failed, state: "working", canRetry: false });
expect(container.textContent).toBe("");
});
it("names the admission hold a task that has not started waits for", async () => {
await render({ ...failed, state: "working", canRetry: false, sourceRunIds: [], observedRunId: null,
retryWait: { reason: "budget.blocked", message: "Waiting for the budget to allow new work. The task starts automatically when it does." } });
expect(container.textContent).toBe("Waiting for the budget to allow new work. The task starts automatically when it does.");
expect(container.querySelector("button")).toBeNull();
});
it("names and links the readable blockers a saved Retry waits on, with no second Retry (restart chaos t05)", async () => {
const message = "Retry is waiting on a blocked task this one depends on. Retry or unblock it; this task continues when it is done. Your Retry is saved.";
const summary = (id: string, identifier: string, title: string, status: string) =>
({ id, identifier, title, status, priority: "medium", assigneeAgentId: null, assigneeUserId: null }) as never;
await act(async () => root.render(<ExecutionBlockerNotice presentation={{ ...failed, state: "working", canRetry: false,
retryWait: { reason: "dependency_blocked", message } }} canRetry onRetry={retry}
blockers={[summary("child", "CHA-10", "Part 2", "blocked"), summary("gone", "CHA-11", "Part 3", "cancelled"),
summary("done", "CHA-9", "Part 1", "done")]} />));
expect(container.textContent).toContain(message);
const links = [...container.querySelectorAll<HTMLAnchorElement>("[data-testid='retry-waiting-on'] a")].map(link => link.getAttribute("href"));
expect(links).toHaveLength(2);
expect(links[0]).toContain("CHA-10");
expect(container.textContent).toContain("Blocked: open it to Retry");
expect(container.textContent).toContain("Cancelled: remove or replace it");
expect(container.textContent).not.toContain("Part 1");
expect(container.querySelector("button")).toBeNull();
});
it("shows a locked blocker without reading its status, and a finished blocker still saving files", async () => {
const message = "Retry is waiting for a finished task this one depends on to save its files. Your Retry is saved.";
await act(async () => root.render(<ExecutionBlockerNotice presentation={{ ...failed, state: "working", canRetry: false,
retryWait: { reason: "dependency_blocked", message } }} canRetry onRetry={retry}
blockers={[{ id: "secret", identifier: "CHA-12", locked: true } as never]} />));
expect(container.querySelector("[data-testid='locked-issue-chip']")?.textContent).toContain("CHA-12");
await act(async () => root.render(<ExecutionBlockerNotice presentation={{ ...failed, state: "working", canRetry: false,
retryWait: { reason: "dependency_blocked", message } }} canRetry onRetry={retry}
blockers={[{ id: "done", identifier: "CHA-9", title: "Part 1", status: "done", priority: "medium",
assigneeAgentId: null, assigneeUserId: null } as never]} />));
expect(container.querySelector("[data-testid='retry-waiting-on'] a")?.getAttribute("href")).toContain("CHA-9");
expect(container.textContent).toContain("Saving its files");
});
it("names the saved-work recovery step instead of a bare queue", async () => {
await render({ ...failed, state: "working", canRetry: false, recoveryStep: "saving_previous_files" });
expect(container.textContent).toBe("Saving files from the previous attempt…");
expect(container.querySelector("button")).toBeNull();
});
it("names the step a scheduled recovery will retry", async () => {
vi.useFakeTimers(); vi.setSystemTime(new Date("2026-10-20T00:00:00Z"));
await render({ ...failed, state: "retry_scheduled", nextRetryAt: "2026-10-20T00:00:30Z", recoveryStep: "checking_previous_run" });
expect(container.textContent).toContain("Checking that the previous attempt stopped. Trying again in 30s…");
expect(container.querySelector("button")?.textContent).toBe("Retry");
});
it("names the recovery step inside a provider failure notice", async () => {
vi.useFakeTimers(); vi.setSystemTime(new Date("2026-10-20T00:00:00Z"));
await render({ ...failed, state: "retry_scheduled", nextRetryAt: "2026-10-20T00:00:30Z", recoveryStep: "checking_previous_run",
providerFailure: { schema: "paperclip.provider-failure.v1", provider: "openai", phase: "startup", category: "overloaded",
retryability: "unknown", message: "Try later." } });
expect(container.textContent).toContain("Checking that the previous attempt stopped. Trying again in 30s…");
expect(container.textContent).not.toContain("Paperclip will retry automatically.");
});
it("leaves genuine user decisions to their specific action surface", async () => {
await render({ ...failed, responsibility: "user", state: "waiting_for_user", userAction: "approval", canRetry: false });
expect(container.textContent).toBe("");
});
it("does not give read-only users a mutation", async () => {
await render(failed, { canRetry: false }); expect(container.querySelector("button")).toBeNull();
});
it("removes the stale failure immediately while admission is pending", async () => {
await render(failed, { optimistic: true }); expect(container.textContent).toBe("");
await render(failed, { optimistic: true, takingLonger: true });
expect(container.textContent).toContain("Taking longer than usual…");
});
it("shows a definitive admission rejection instead of silently dropping Retry", async () => {
await render(failed, { error: new Error("Your task access changed. Refresh the task.") });
expect(container.querySelector('[role="alert"]')?.textContent).toContain("Your task access changed.");
expect(container.querySelectorAll("button")).toHaveLength(1);
});
it("shows workspace preparation failures as plain text while keeping retry permissions", async () => {
const workspaceFailure = { message: 'Could not prepare the project folder <img src=x onerror=alert(1)>.' };
await render({ ...failed, workspaceFailure }, { canRetry: false });
expect(container.textContent).toContain("Couldn’t prepare the task folders.");
expect(container.textContent).toContain(workspaceFailure.message);
expect(container.querySelector("img, button")).toBeNull();
await render({ ...failed, workspaceFailure });
await act(async () => container.querySelector<HTMLButtonElement>("button")!.click());
expect(retry).toHaveBeenCalledOnce();
await render({ ...failed, workspaceFailure, state: "working" });
expect(container.textContent).toBe("");
});
it("names a failed workspace setup command and what to change, keeping Retry", async () => {
const setupFailure = { step: "workspace_provision" as const, command: "bash ./scripts/provision-worktree.sh", exitCode: 127,
output: "bash: ./scripts/provision-worktree.sh: No such file or directory",
message: "The project's workspace provision command \"bash ./scripts/provision-worktree.sh\" failed with exit code 127: bash: ./scripts/provision-worktree.sh: No such file or directory" };
await render({ ...failed, setupFailure });
expect(container.textContent).toContain("Couldn’t set up the task workspace.");
expect(container.textContent).toContain(setupFailure.message);
expect(container.textContent).toContain("Fix the command in the project’s workspace settings");
expect(container.textContent).not.toContain("Couldn’t finish this attempt.");
await act(async () => container.querySelector<HTMLButtonElement>("button")!.click());
expect(retry).toHaveBeenCalledOnce();
});
it("shows why an accepted Retry is waiting and keeps another attempt available", async () => {
const retryWait = { reason: "remote_cleanup", message: "Retry is waiting for the previous environment to stop. Your message is saved." };
await render({ ...failed, retryWait });
expect(container.textContent).toContain(retryWait.message);
expect(container.textContent).not.toContain("Couldn’t finish this attempt.");
await act(async () => container.querySelector<HTMLButtonElement>("button")!.click());
expect(retry).toHaveBeenCalledOnce();
await render({ ...failed, retryWait }, { canRetry: false });
expect(container.textContent).toContain(retryWait.message);
expect(container.querySelector("button")).toBeNull();
});
it("names the budget wait alongside a provider failure while a saved Retry is held", async () => {
const providerFailure = { schema: "paperclip.provider-failure.v1" as const, provider: "openai", phase: "startup" as const,
category: "overloaded" as const, retryability: "transient" as const, message: "Provider overloaded" };
await render({ ...failed, providerFailure, responsibility: "user", state: "waiting_for_user", userAction: "budget", canRetry: false });
expect(container.textContent).toContain("Provider overloaded");
expect(container.querySelector('[data-testid="task-execution-waiting"]')?.textContent).toContain("waiting for the budget to allow new work");
expect(container.querySelector("button")).toBeNull();
});
it("shows an unknown provider's original explanation as text and preserves read-only access", async () => {
const providerFailure = { schema: "paperclip.provider-failure.v1" as const, provider: "new-provider", phase: "startup" as const,
category: "unknown" as const, retryability: "unknown" as const, httpStatus: 429,
message: "Upstream failure <img src=x onerror=alert(1)>" };
await render({ ...failed, providerFailure }, { canRetry: false });
expect(container.textContent).toContain(providerFailure.message);
expect(container.textContent).toContain("Failed before work started");
expect(container.textContent).toContain("HTTP 429");
expect(container.querySelector("img, button")).toBeNull();
await render({ ...failed, providerFailure, state: "resolved" });
expect(container.textContent).toBe("");
});
});