fix(issues): make every Retry start work or say why (#20283)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - When a task's run fails, the board recovers it with a Retry button,
so that button must either start work or say why it did not
> - An audit of every Retry-type button found three gaps. The task Retry
shown during a scheduled retry's countdown returned "accepted" but
changed nothing. A stale Retry looked like success in the Inbox. "Retry
now" skipped the task's read and change checks, so a member who cannot
see a private task could start its retry
> - This pull request makes the task Retry start a scheduled retry
immediately, makes every Retry that did not start work say why, and
gives "Retry now" the same authorization as the task Retry
> - The benefit is that no Retry click silently does nothing

## Linked Issues or Issue Description

Refs #19831. The board reported a dead Retry button. A read-only audit
of every Retry button confirmed:
- **Task Retry during a scheduled retry was a no-op.**
`TaskInterruptionPresentation.canRetry` is true in `retry_scheduled`, so
`ExecutionBlockerNotice` shows Retry. `requestTaskRetry` treats
`scheduled_retry` as busy and inserts a `coalesced` wake pointing at
that run. `resumeTaskRetry` reads only `deferred_issue_execution`, and
dispatch uses coalesced user wakes only to carry comments. Nothing
promoted the run: the API answered 202 `accepted: true` and the
countdown did not change.
- **A stale Retry looked like success.** `accepted: false, stale: true`
comes back as HTTP 200. The Inbox ignored `accepted` and opened the task
as if work had started. The task page showed no reason.
- **"Retry now" checked less than the task Retry.** It ran only
`assertBoard` and `getAccessibleResource`, skipping
`assertIssueReadAllowed` and `issue:mutate`. A company member who cannot
read a private task could promote that task's scheduled retry.
- **"Retry now" said nothing for some outcomes.** It toasted only
`promoted` and `gate_suppressed`.

## What Changed

- `server/src/services/task-retry.ts`: when the Retry coalesces into the
task's latest run and that run is `scheduled_retry` (with no other Retry
already active), the receipt returns `scheduledRetryRunId`.
- `server/src/routes/issues.ts`:
- `POST /issues/:id/retry` then promotes that run through the existing
`retryScheduledRetryNow`, the same path "Retry now" uses. It logs
`issue.scheduled_retry_retry_now` with `source: "task_retry"` and
returns `scheduledRetry: { outcome, message }`.
- `POST /issues/:id/scheduled-retry/retry-now` now runs
`assertIssueReadAllowed` and `decideIssueAccess("issue:mutate")`,
matching `/retry`. A private task the member cannot read now answers
404.
- `ui/src/hooks/useTaskRetry.ts`: new `taskRetryNotStartedReason`. When
a Retry did not start work (stale, or a scheduled retry that is
gate-suppressed, waiting, or gone), the hook returns that reason as its
error. `ExecutionBlockerNotice` and `StalledDependencyNotice` already
display it.
- `ui/src/pages/Inbox.tsx`: a task Retry that did not start work shows
the reason in the error toast and does not navigate.
- `ui/src/hooks/useRetryNowMutation.ts` and
`IssueScheduledRetryCard.tsx`: every "Retry now" outcome now shows its
headline and message, including `no_scheduled_retry` on the card.
- `ui/src/api/issues.ts`: `retryTask`'s response type includes
`scheduledRetry`.

## Verification

Red/green (each new test fails against master and passes with this PR):
- `server/src/__tests__/issue-scheduled-retry-routes.test.ts`:
- "starts a scheduled retry now when the task Retry is clicked during
its countdown": 202 with `scheduledRetry.outcome: "promoted"`, the same
run becomes `queued`, and no second retry run is created.
- "refuses Retry now on a private task the member cannot see, like the
task Retry": on master "Retry now" answers 200 `promoted`; now both
routes answer 404 and the run stays `scheduled_retry`.
- The seed now adds the board user's membership, which the stricter
route needs. All 33 tests pass.
- `ui/src/hooks/useTaskRetry.test.tsx`: a replaced attempt, a gate-held
scheduled retry and a waiting scheduled retry each show their reason; a
promoted one shows nothing extra.
- `ui/src/pages/Inbox.test.tsx`: an Inbox Retry that did not start work
(stale, or gate-held) toasts the reason and does not navigate.
- `ui/src/components/IssueScheduledRetryCard.test.tsx`: "explains when
there was no scheduled retry left to start".

Other Retry buttons: the chat failed-run Retry already reports stopped
and failed retries (`agents.test.ts`). Agent lifecycle "Retry now" and
cost "Retry accounting" start no task work and already surface their API
errors.

Regression and static checks:
- UI: 7 files, 168 passed. Server: task-retry and scheduled-retry
suites, 149 passed. `issue-agent-mutation-ownership-routes.test.ts`
passed.
- `maintenance-server-routes.test.ts` "assembled maintenance server
production wiring" fails identically on master on this Mac
(`ensure-build-deps`).
- `tsc --noEmit` passes for `server` and `ui/src`. `pnpm
check:token-gates` is clean.

## Risks

- A task Retry during a scheduled retry now starts the run immediately,
through the existing "Retry now" promotion gates (pause, budget, cleanup
waits). A gate that holds it is reported, not bypassed.
- "Retry now" is stricter: a member without read or change access to the
task gets 404 or 403, as on `/retry`.
- No schema change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file edits).

## 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>

server/src/__tests__/issue-scheduled-retry-routes.test.ts

@@ -139,6 +139,8 @@ describeEmbeddedPostgres("issue scheduled retry routes", () => {
       issuePrefix,
       requireBoardApprovalForNewAgents: false,
     });
+    await db.insert(companyMemberships).values({ companyId, principalType: "user", principalId: "board-user",
+      status: "active", membershipRole: "admin" });
     await db.insert(agents).values({
       id: agentId,
       companyId,
@@ -664,10 +666,6 @@ describeEmbeddedPostgres("issue scheduled retry routes", () => {
 
   it.each(["post", "patch"] as const)("keeps a retry's live process and saved work owner when a %s comment arrives", async method => {
     const f = await seedIssueWithRetry({ retryStatus: "running" });
-    await db.insert(companyMemberships).values({
-      companyId: f.companyId, principalType: "user", principalId: "board-user",
-      membershipRole: "admin", status: "active",
-    });
     const child = spawn(process.execPath, ["-e", `
       process.on('message', message => {
         if (message === 'continue-work') process.send('work-continues');
@@ -781,6 +779,60 @@ describeEmbeddedPostgres("issue scheduled retry routes", () => {
     });
   });
 
+  it("starts a scheduled retry now when the task Retry is clicked during its countdown", async () => {
+    const f = await seedIssueWithRetry();
+    await db.update(heartbeatRuns).set({ createdAt: new Date("2026-05-06T18:00:01.000Z") })
+      .where(eq(heartbeatRuns.id, f.retryRunId));
+    const app = createApp(boardActor(f.companyId));
+
+    const res = await request(app).post(`/api/issues/${f.issueId}/retry`)
+      .send({ idempotencyKey: randomUUID(), observedRunId: f.retryRunId });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(202);
+    expect(res.body).toMatchObject({ accepted: true, scheduledRetry: { outcome: "promoted" } });
+    const [run] = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, f.retryRunId));
+    expect(run!.status).toBe("queued");
+    expect(await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.retryOfRunId, f.sourceRunId))).toHaveLength(1);
+  });
+
+  it("starts the scheduled retry when a saved task Retry is replayed after its promotion was lost", async () => {
+    const f = await seedIssueWithRetry();
+    await db.update(heartbeatRuns).set({ createdAt: new Date("2026-05-06T18:00:01.000Z") })
+      .where(eq(heartbeatRuns.id, f.retryRunId));
+    const app = createApp(boardActor(f.companyId));
+    const body = { idempotencyKey: randomUUID(), observedRunId: f.retryRunId };
+    const first = await request(app).post(`/api/issues/${f.issueId}/retry`).send(body);
+    expect(first.status, JSON.stringify(first.body)).toBe(202);
+    await db.update(heartbeatRuns).set({ status: "scheduled_retry", scheduledRetryAt: new Date(Date.now() + 60 * 60_000) })
+      .where(eq(heartbeatRuns.id, f.retryRunId));
+
+    const replay = await request(app).post(`/api/issues/${f.issueId}/retry`).send(body);
+
+    expect(replay.status, JSON.stringify(replay.body)).toBe(202);
+    expect(replay.body).toMatchObject({ accepted: true, requestId: first.body.requestId, scheduledRetry: { outcome: "promoted" } });
+    const [run] = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, f.retryRunId));
+    expect(run!.status).toBe("queued");
+  });
+
+  it("refuses Retry now on a private task the member cannot see, like the task Retry", async () => {
+    const f = await seedIssueWithRetry();
+    await db.update(issues).set({ visibility: "private", createdByUserId: "task-owner", responsibleUserId: "task-owner" })
+      .where(eq(issues.id, f.issueId));
+    await db.insert(companyMemberships).values({ companyId: f.companyId, principalType: "user", principalId: "other-member",
+      status: "active", membershipRole: "member" });
+    const app = createApp({ ...boardActor(f.companyId), userId: "other-member",
+      memberships: [{ companyId: f.companyId, membershipRole: "member", status: "active" }] });
+
+    const retry = await request(app).post(`/api/issues/${f.issueId}/retry`)
+      .send({ idempotencyKey: randomUUID(), observedRunId: f.retryRunId });
+    const retryNow = await request(app).post(`/api/issues/${f.issueId}/scheduled-retry/retry-now`).send({});
+
+    expect(retry.status, JSON.stringify(retry.body)).toBe(404);
+    expect(retryNow.status, JSON.stringify(retryNow.body)).toBe(404);
+    const [run] = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, f.retryRunId));
+    expect(run!.status).toBe("scheduled_retry");
+  });
+
   it("promotes the existing scheduled retry and treats duplicate clicks as idempotent", async () => {
     const { companyId, issueId, retryRunId } = await seedIssueWithRetry();
     const app = createApp(boardActor(companyId));
@@ -855,6 +907,8 @@ describeEmbeddedPostgres("issue scheduled retry routes", () => {
       issuePrefix: "NONE",
       requireBoardApprovalForNewAgents: false,
     });
+    await db.insert(companyMemberships).values({ companyId, principalType: "user", principalId: "board-user",
+      status: "active", membershipRole: "admin" });
     await db.insert(issues).values({
       id: issueId,
       companyId,

server/src/routes/issues.ts

@@ -10107,10 +10107,25 @@ export function issueRoutes(
     const receipt = await requestTaskRetry({ db, companyId: issue.companyId, issueId: issue.id,
       ...req.body, actorId: getActorInfo(req).actorId, actorSource: req.actor.source,
       prepareChatRetry: opts.chatRunRetries?.prepareFailedChatRunRetry });
-    res.status(receipt.accepted ? 202 : 200).json({ ...receipt, presentation: await taskInterruptionPresentation(db, issue) });
+    const actor = getActorInfo(req);
+    const scheduledRetryRunId = "scheduledRetryRunId" in receipt ? receipt.scheduledRetryRunId : undefined;
+    const scheduledRetry = scheduledRetryRunId
+      ? await heartbeat.retryScheduledRetryNow({ issueId: issue.id, actor: { actorType: actor.actorType, actorId: actor.actorId } })
+      : null;
+    if (scheduledRetry) {
+      await logActivity(db, { companyId: issue.companyId, actorType: actor.actorType, actorId: actor.actorId,
+        action: "issue.scheduled_retry_retry_now", entityType: "issue", entityId: issue.id,
+        agentId: scheduledRetry.scheduledRetry?.agentId ?? issue.assigneeAgentId ?? null,
+        runId: scheduledRetry.scheduledRetry?.runId ?? scheduledRetryRunId ?? null,
+        details: { outcome: scheduledRetry.outcome, message: scheduledRetry.message, source: "task_retry" } });
+    }
+    res.status(receipt.accepted ? 202 : 200).json({ ...receipt,
+      ...(scheduledRetry ? { scheduledRetry: { outcome: scheduledRetry.outcome, message: scheduledRetry.message } } : {}),
+      presentation: await taskInterruptionPresentation(db, issue) });
     // The receipt commits before dispatch. Maintenance redelivers it after a
     // crash or a lost response; this nudge only reduces perceived latency.
-    if (receipt.chatActionId) void opts.chatRunRetries?.processFailedChatRunRetry(receipt.chatActionId).catch(err =>
+    const chatActionId = "chatActionId" in receipt ? receipt.chatActionId : undefined;
+    if (chatActionId) void opts.chatRunRetries?.processFailedChatRunRetry(chatActionId).catch(err =>
       logger.warn({ err, issueId: issue.id }, "Connected task Retry remains queued"));
     else if (receipt.accepted && receipt.requestId) void heartbeat.resumeTaskRetry(issue.companyId, receipt.requestId).catch(err =>
       logger.warn({ err, issueId: issue.id }, "Task Retry remains queued"));
@@ -14012,7 +14027,9 @@ export function issueRoutes(
       svc.getById(id),
       "Issue not found",
     );
-    if (!issue) return;
+    if (!issue || !(await assertIssueReadAllowed(req, res, issue))) return;
+    const decision = await decideIssueAccess(req, issue, "issue:mutate");
+    if (!decision.allowed) throw forbidden(decision.explanation, authorizationDeniedDetails(decision));
 
     const actor = getActorInfo(req);
     const result = await heartbeat.retryScheduledRetryNow({

server/src/services/task-retry.ts

@@ -268,8 +268,13 @@ function admitTaskRetry(input: TaskRetryRequest) {
       if (sameRequest.payload?.issueId !== issue.id || sameRequest.requestedByActorId !== input.actorId)
         throw conflict("This retry request belongs to a different task or user.");
       const intent = readTaskRetryIntent(sameRequest.payload);
+      const [coalescedRun] = sameRequest.status === "coalesced" && sameRequest.runId
+        ? await tx.select({ id: heartbeatRuns.id, status: heartbeatRuns.status }).from(heartbeatRuns)
+          .where(and(eq(heartbeatRuns.companyId, issue.companyId), eq(heartbeatRuns.id, sameRequest.runId)))
+        : [];
       return { requestId: intent?.canonicalIntentId ?? sameRequest.id, accepted: true, stale: false,
-        observedRunId: intent?.sourceRunId ?? null, chatActionId: intent?.chatActionId };
+        observedRunId: intent?.sourceRunId ?? null, chatActionId: intent?.chatActionId,
+        ...(coalescedRun?.status === "scheduled_retry" ? { scheduledRetryRunId: coalescedRun.id } : {}) };
     }
     const [latest] = await tx.select().from(heartbeatRuns).where(and(eq(heartbeatRuns.companyId, issue.companyId),
       or(eq(heartbeatRuns.issueId, issue.id), eq(heartbeatRuns.nativeIssueId, issue.id),
@@ -277,7 +282,7 @@ function admitTaskRetry(input: TaskRetryRequest) {
       .orderBy(desc(heartbeatRuns.createdAt), desc(heartbeatRuns.id)).limit(1);
     if (["done", "cancelled"].includes(issue.status) || !issue.assigneeAgentId || !latest ||
         latest.agentId !== issue.assigneeAgentId || input.observedRunId !== latest.id) {
-      return { requestId: null, accepted: false, stale: true, observedRunId: latest?.id ?? null };
+      return { requestId: null, accepted: false, stale: true, observedRunId: latest?.id ?? null, chatActionId: undefined };
     }
     let active = (await tx.select().from(agentWakeupRequests).where(and(
       eq(agentWakeupRequests.companyId, issue.companyId), eq(agentWakeupRequests.agentId, issue.assigneeAgentId),
@@ -430,7 +435,8 @@ function admitTaskRetry(input: TaskRetryRequest) {
         ...(replacedRequestId ? { replacedRequestId } : {}),
         ...(restartRecovery ? { initiatedBy: "restart_recovery", onBehalfOfUserId: input.actorId } : {}) } });
     return { requestId: active?.id ?? id, accepted: true, stale: false, observedRunId: latest.id,
-      chatActionId: intent.chatActionId };
+      chatActionId: intent.chatActionId,
+      ...(!active && latest.status === "scheduled_retry" ? { scheduledRetryRunId: latest.id } : {}) };
   }, { companyId: input.companyId });
 }
 

ui/src/api/issues.ts

@@ -429,7 +429,9 @@ export const issuesApi = {
   retryWorkspaceExport: (id: string, data: { actionId: string; runId: string; repairNote: string }) =>
     api.post<{ runId: string; resultId: string; leaseId: string; status: "queued" }>(`/issues/${id}/recovery-actions/retry-workspace-export`, data),
   retryTask: (issueId: string, body: { idempotencyKey: string; observedRunId: string | null }) =>
-    api.post<{ requestId: string | null; accepted: boolean; stale: boolean; presentation: import("@paperclipai/shared").TaskInterruptionPresentation | null }>(`/issues/${issueId}/retry`, body),
+    api.post<{ requestId: string | null; accepted: boolean; stale: boolean;
+      scheduledRetry?: { outcome: "promoted" | "already_promoted" | "gate_suppressed" | "waiting" | "no_scheduled_retry"; message: string };
+      presentation: import("@paperclipai/shared").TaskInterruptionPresentation | null }>(`/issues/${issueId}/retry`, body),
   recoverWorkspace: (id: string, data: { actionId: string; runId: string; idempotencyKey: string }) =>
     api.post<{ actionId: string; status: string }>(`/issues/${id}/recovery-actions/recover-workspace`, data),
   reconstructWorkspace: (id: string, data: { actionId: string; runId: string; expectedStatusVersion: number; attachmentIds: string[];

ui/src/components/IssueScheduledRetryCard.test.tsx

@@ -232,6 +232,17 @@ describe("IssueScheduledRetryCard", () => {
     });
   });
 
+  it("explains when there was no scheduled retry left to start", async () => {
+    const message = "No scheduled retry is waiting for this task.";
+    retryNowMock.mockResolvedValue({ outcome: "no_scheduled_retry", message, scheduledRetry: null });
+    renderWithProviders(<IssueScheduledRetryCard issueId="issue-1" scheduledRetry={baseRetry} />);
+    act(() => { getRetryNowButton()!.click(); });
+    await waitForUi(() => {
+      expect(getCard()?.textContent).toContain(message);
+      expect(getCard()?.textContent).not.toContain("run starting");
+    });
+  });
+
   it("renders an inline error band on backend failure", async () => {
     retryNowMock.mockRejectedValue(new Error("Server error"));
     renderWithProviders(

ui/src/components/IssueScheduledRetryCard.tsx

@@ -159,7 +159,8 @@ export function IssueScheduledRetryCard({
                 ? retryNow.data?.outcome === "already_promoted"
                   ? "Already promoted — run starting"
                   : "Promoted — run starting"
-                : retryNow.data?.outcome === "waiting" && retryNow.data.scheduledRetry?.runId === scheduledRetry.runId
+                : (retryNow.data?.outcome === "waiting" && retryNow.data.scheduledRetry?.runId === scheduledRetry.runId)
+                    || retryNow.data?.outcome === "no_scheduled_retry"
                   ? retryNow.data.message
                   : helperIdle}
           </span>

ui/src/hooks/useRetryNowMutation.ts

@@ -50,19 +50,12 @@ export function useRetryNowMutation(
         queryClient.invalidateQueries({ queryKey: queryKeys.issues.liveRuns(issueId) });
         queryClient.invalidateQueries({ queryKey: queryKeys.issues.activeRun(issueId) });
       }
-      if (response.outcome === "promoted") {
-        pushToast({
-          title: RETRY_NOW_OUTCOME_HEADLINE.promoted,
-          body: response.message,
-          tone: "success",
-        });
-      } else if (response.outcome === "gate_suppressed") {
-        pushToast({
-          title: RETRY_NOW_OUTCOME_HEADLINE.gate_suppressed,
-          body: response.message,
-          tone: "error",
-        });
-      }
+      pushToast({
+        title: RETRY_NOW_OUTCOME_HEADLINE[response.outcome],
+        body: response.message,
+        tone: response.outcome === "promoted" || response.outcome === "already_promoted" ? "success"
+          : response.outcome === "gate_suppressed" ? "error" : "info",
+      });
     },
     onError: (error) => {
       pushToast({

ui/src/hooks/useTaskRetry.test.tsx

@@ -39,6 +39,31 @@ describe("optimistic task Retry", () => {
     expect(container.textContent).not.toContain("Thinking");
     expect(container.textContent).not.toContain("Taking longer");
   });
+  it.each([
+    ["a replaced attempt", { requestId: null, accepted: false, stale: true }, "already replaced, so Retry did not start new work"],
+    ["a scheduled retry held by a gate", { requestId: "retry", accepted: true, stale: false,
+      scheduledRetry: { outcome: "gate_suppressed" as const, message: "The company budget is paused." } }, "The company budget is paused."],
+    ["a scheduled retry still waiting", { requestId: "retry", accepted: true, stale: false,
+      scheduledRetry: { outcome: "waiting" as const, message: "The retry is waiting for the workspace." } }, "waiting for the workspace"],
+  ])("shows why Retry did not start work for %s", async (_label, result, reason) => {
+    const presentation = { intentId: "intent", responsibility: "system" as const, state: "retry_scheduled" as const,
+      canRetry: true, nextRetryAt: null, userAction: null, sourceRunIds: ["failed-run"], observedRunId: "failed-run" };
+    vi.mocked(issuesApi.retryTask).mockResolvedValue({ ...result, presentation } as Awaited<ReturnType<typeof issuesApi.retryTask>>);
+    const waiting = { ...issue, interruption: presentation } as Issue;
+    await render(waiting);
+    await act(async () => container.querySelector("button")!.click());
+    expect(container.querySelector('[role="alert"]')?.textContent).toContain(reason);
+    expect(container.textContent).not.toContain("Thinking");
+    await render({ ...waiting, interruption: { ...presentation, state: "working", canRetry: false } } as Issue);
+    expect(container.querySelector('[role="alert"]')).toBeNull();
+  });
+  it("shows nothing extra when Retry promoted the scheduled run", async () => {
+    vi.mocked(issuesApi.retryTask).mockResolvedValue({ requestId: "retry", accepted: true, stale: false,
+      scheduledRetry: { outcome: "promoted", message: "Retry promoted" }, presentation: null });
+    await render();
+    await act(async () => container.querySelector("button")!.click());
+    expect(container.querySelector('[role="alert"]')).toBeNull();
+  });
   it("refreshes the inspected file recovery after an accepted Retry", async () => {
     vi.mocked(issuesApi.retryTask).mockResolvedValue({ requestId: "retry", accepted: true, stale: false,
       observedRunId: "failed-run", presentation: null } as Awaited<ReturnType<typeof issuesApi.retryTask>>);

ui/src/hooks/useTaskRetry.ts

@@ -7,6 +7,16 @@ import { queryKeys } from "../lib/queryKeys";
 import { createUuid } from "../lib/uuid";
 
 type RetryRequest = { issueId: string; identifier?: string | null; idempotencyKey: string; observedRunId: string | null };
+type RetryResult = Awaited<ReturnType<typeof issuesApi.retryTask>>;
+
+export const STALE_TASK_RETRY_MESSAGE = "This attempt was already replaced, so Retry did not start new work. The task now shows its current state.";
+
+export function taskRetryNotStartedReason(result: RetryResult): string | null {
+  if (!result.accepted) return STALE_TASK_RETRY_MESSAGE;
+  const outcome = result.scheduledRetry?.outcome;
+  if (outcome && outcome !== "promoted" && outcome !== "already_promoted") return result.scheduledRetry!.message;
+  return null;
+}
 
 export function useTaskRetry(issue: Issue | undefined) {
   const queryClient = useQueryClient();
@@ -14,6 +24,7 @@ export function useTaskRetry(issue: Issue | undefined) {
   const [optimistic, setOptimistic] = useState(false);
   const [takingLonger, setTakingLonger] = useState(false);
   const [reconcile, setReconcile] = useState<{ refs: string[]; sourceRunId: string | null } | null>(null);
+  const [notStarted, setNotStarted] = useState<{ error: Error; state: string | null; observedRunId: string | null } | null>(null);
   const mutation = useMutation({
     mutationFn: ({ issueId, identifier: _identifier, ...body }: RetryRequest) =>
       issuesApi.retryTask(issueId, body),
@@ -22,6 +33,11 @@ export function useTaskRetry(issue: Issue | undefined) {
       if (isCurrent) request.current = null;
       const refs = [...new Set([variables.issueId, variables.identifier].filter((ref): ref is string => Boolean(ref)))];
       if (isCurrent && result.accepted) setReconcile({ refs, sourceRunId: variables.observedRunId });
+      if (isCurrent) {
+        const reason = taskRetryNotStartedReason(result);
+        setNotStarted(reason ? { error: new Error(reason), state: result.presentation?.state ?? null,
+          observedRunId: result.presentation?.observedRunId ?? null } : null);
+      }
       {
         for (const ref of refs) queryClient.setQueryData<Issue>(queryKeys.issues.detail(ref), current =>
           current ? { ...current, interruption: result.presentation } : current);
@@ -70,16 +86,20 @@ export function useTaskRetry(issue: Issue | undefined) {
     setOptimistic(false);
     setTakingLonger(false);
     setReconcile(null);
+    setNotStarted(null);
     mutation.reset();
   }, [issue?.id]);
   return { retry: () => {
     if (!issue) return;
     setReconcile(null);
+    setNotStarted(null);
     mutation.reset();
     request.current ??= { issueId: issue.id, identifier: issue.identifier, idempotencyKey: createUuid(),
       observedRunId: issue.interruption?.observedRunId ?? issue.executionBlocker?.runId ?? null };
     setOptimistic(true);
     setTakingLonger(false);
     mutation.mutate(request.current);
-  }, optimistic, takingLonger, error: mutation.error };
+  }, optimistic, takingLonger, error: mutation.error ?? (notStarted
+    && (issue?.interruption?.state ?? null) === notStarted.state
+    && (issue?.interruption?.observedRunId ?? null) === notStarted.observedRunId ? notStarted.error : null) };
 }

ui/src/pages/Inbox.test.tsx

@@ -118,8 +118,10 @@ vi.mock("../context/BreadcrumbContext", () => ({
   useBreadcrumbs: () => ({ setBreadcrumbs: vi.fn() }),
 }));
 
+const toastMocks = vi.hoisted(() => ({ pushToast: vi.fn() }));
+
 vi.mock("../context/ToastContext", () => ({
-  useToastActions: () => ({ pushToast: vi.fn() }),
+  useToastActions: () => ({ pushToast: toastMocks.pushToast }),
 }));
 
 vi.mock("../context/DialogContext", () => ({
@@ -1326,6 +1328,36 @@ describe("Inbox toolbar", () => {
     } finally { await act(() => root.unmount()); client.clear(); }
   });
 
+  it.each([
+    ["a replaced attempt", { accepted: false, stale: true, requestId: null }, "already replaced"],
+    ["a held scheduled retry", { accepted: true, stale: false, requestId: "retry",
+      scheduledRetry: { outcome: "gate_suppressed", message: "The company budget is paused." } }, "The company budget is paused."],
+  ])("shows why an Inbox Retry did not start work for %s and does not open the task as if it did", async (_label, result, reason) => {
+    routerMock.location.pathname = "/inbox/recent";
+    const task = createIssue({ id: "task-1", title: "Failed task" });
+    const failure = createFailedRun({ issueId: task.id, responsibleUserId: "local-board" });
+    setFailureRuns([failure]);
+    apiMocks.issuesList.mockResolvedValue([{ ...task, interruption: { intentId: "intent", responsibility: "system",
+      state: "failed", nextRetryAt: null, canRetry: true, userAction: null, sourceRunIds: [failure.id], observedRunId: failure.id } }]);
+    apiMocks.retryTask.mockResolvedValue({ ...result, presentation: null });
+    toastMocks.pushToast.mockClear();
+    const client = new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: 0 }, mutations: { retry: false } } });
+    const root = createRoot(container);
+    try {
+      await act(() => root.render(<QueryClientProvider client={client}><Inbox /></QueryClientProvider>));
+      const retry = await vi.waitFor(() => {
+        const button = Array.from(container.querySelectorAll("button")).find(candidate => candidate.textContent === "Retry");
+        expect(button).toBeTruthy();
+        return button!;
+      });
+      await act(async () => retry.click());
+      await vi.waitFor(() => expect(toastMocks.pushToast).toHaveBeenCalledWith(expect.objectContaining({
+        tone: "error", body: expect.stringContaining(reason) })));
+      expect(apiMocks.retryTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ observedRunId: failure.id }));
+      expect(routerMock.navigate).not.toHaveBeenCalled();
+    } finally { await act(() => root.unmount()); client.clear(); }
+  });
+
   it("upgrades cached parent metadata when the same task becomes a failure context", async () => {
     routerMock.location.pathname = "/inbox/recent";
     const parent = createIssue({ id: "parent", title: "Parent metadata", listProjection: "index" });

ui/src/pages/Inbox.tsx

@@ -18,6 +18,7 @@ import { dashboardApi } from "../api/dashboard";
 import { executionWorkspacesApi } from "../api/execution-workspaces";
 import { issuesApi } from "../api/issues";
 import { useSecondTick } from "../hooks/useSecondTick";
+import { taskRetryNotStartedReason } from "../hooks/useTaskRetry";
 import { agentsApi } from "../api/agents";
 import { heartbeatsApi } from "../api/heartbeats";
 import { instanceSettingsApi } from "../api/instanceSettings";
@@ -1952,6 +1953,13 @@ function StreamlinedInbox({
         });
         queryClient.setQueryData<Issue>(queryKeys.issues.detail(issueId), current =>
           current ? { ...current, interruption: result.presentation } : current);
+        const notStarted = taskRetryNotStartedReason(result);
+        if (notStarted) {
+          retryRequestKeys.current.delete(run.id);
+          await Promise.all([queryKeys.issues.listMineByMe(run.companyId), queryKeys.heartbeats(run.companyId),
+            queryKeys.heartbeats(run.companyId, run.agentId)].map(queryKey => queryClient.invalidateQueries({ queryKey })));
+          throw new Error(notStarted);
+        }
         return { newRun: { runId: null, issueId }, originalRun: run };
       }
       const result = await agentsApi.retryFailedRun(