[codex] Add clear-error agent action (#7695)

## Thinking Path

> - Paperclip is the open source control plane people use to manage AI
agents for work.
> - Agent runtime state is surfaced in both the server API and the board
UI so operators can tell whether an agent is idle, running, paused, or
in error.
> - When an agent is already in `error`, the existing pause/resume
action slot is not useful because there is no running work to pause.
> - Operators need a direct, audited recovery path that clears the stale
error state only for agents in the same company.
> - This pull request adds a company-scoped clear-error mutation,
exposes the shared API contract, and wires the board action cluster to
show Clear error in the pause/resume slot for errored agents.
> - The benefit is that operators can recover CEO/CTO-style errored
agents without resorting to database edits or unrelated session reset
actions.

## Linked Issues or Issue Description

Refs #4021

Paperclip issue: PAP-10515 — right now the CEO and CTO agents are in
error state, but there is no way to clear the error; they appear
otherwise fine.

## What Changed

- Added shared constants, API path, and agent status type support for a
company-scoped clear-error action.
- Added the server service and route to clear an agent from `error` back
to `idle`, with company access enforcement and activity logging.
- Added OpenAPI/docs coverage for the clear-error endpoint.
- Added backend coverage for service behavior and cross-tenant
authorization.
- Updated the board agent action cluster to show a red-tinted Clear
error button only when `agent.status === "error"`.
- Updated agent properties to show a red active last-error indicator
only while the agent is currently errored.
- Added UI component tests for the error-state action and the non-error
pause/resume behavior.

## Verification

Local:

- `pnpm exec vitest run
server/src/__tests__/agents-service-clear-error.test.ts
server/src/__tests__/agent-cross-tenant-authz-routes.test.ts
ui/src/components/AgentActionButtons.test.tsx`
- `pnpm --filter @paperclipai/ui typecheck`
- `pnpm exec vitest run server/src/__tests__/openapi-routes.test.ts`

PR checks:

- Main Paperclip workflow is green on
`a7378e584d50594e7bd507a1a02985bfaaa5abf8`.
- Greptile is 5/5 with no files requiring special attention and no new
comments on the latest review.
- `commitperclip PR Review` is still red because its security-gate step
canceled after filing a draft advisory; the linked `security-review`
check is neutral and says the draft advisory is not a merge block.

Visual artifact:

- ![Clear error visual
comparison](https://gist.githubusercontent.com/cryppadotta/59378c59869b971e92d3edf7b7073aa8/raw/clear-error-visual-comparison.svg)

## Risks

Low to medium risk. The mutation is intentionally narrow, but reviewers
should check that clearing `lastError`/`lastRunError` and returning to
`idle` is the desired recovery semantics for every adapter state. The
remaining red check is from the external commitperclip security-review
workflow, not from the code/test workflow for this PR.

> 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

OpenAI Codex, GPT-5-family coding model, tool-assisted with local shell,
git, GitHub CLI, and targeted Vitest execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [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
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

ui/src/components/AgentActionButtons.tsx

@@ -10,6 +10,7 @@ import {
   Copy,
   RotateCcw,
   Trash2,
+  CheckCircle2,
 } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import {
@@ -85,6 +86,30 @@ export function PauseResumeButton({
   );
 }
 
+export function ClearErrorButton({
+  onClick,
+  disabled,
+  size = "sm",
+}: {
+  onClick: () => void;
+  disabled?: boolean;
+  size?: "sm" | "default";
+}) {
+  return (
+    <Button
+      variant="outline"
+      size={size}
+      onClick={onClick}
+      disabled={disabled}
+      className="border-destructive/60 text-destructive hover:bg-destructive/10 hover:text-destructive dark:border-destructive/50"
+      aria-label="Clear error and return agent to idle"
+    >
+      <CheckCircle2 className="h-3.5 w-3.5 sm:mr-1" />
+      <span className="hidden sm:inline">Clear error</span>
+    </Button>
+  );
+}
+
 function duplicateInstructionFilePath(
   _bundle: AgentInstructionsBundle,
   summary: AgentInstructionsFileSummary,
@@ -162,6 +187,7 @@ export function AgentActionButtons({
   const resolvedCompanyId = companyId ?? agent.companyId;
   const canonicalAgentRef = agentRouteRef(agent);
   const isPaused = agent.status === "paused";
+  const isError = agent.status === "error";
 
   const reportError = useCallback(
     (message: string) => {
@@ -187,11 +213,12 @@ export function AgentActionButtons({
   }, [agent.id, canonicalAgentRef, queryClient, resolvedCompanyId]);
 
   const agentAction = useMutation({
-    mutationFn: async (action: "invoke" | "pause" | "resume" | "approve" | "terminate") => {
+    mutationFn: async (action: "invoke" | "pause" | "resume" | "clear_error" | "approve" | "terminate") => {
       switch (action) {
         case "invoke": return agentsApi.invoke(agent.id, resolvedCompanyId ?? undefined);
         case "pause": return agentsApi.pause(agent.id, resolvedCompanyId ?? undefined);
         case "resume": return agentsApi.resume(agent.id, resolvedCompanyId ?? undefined);
+        case "clear_error": return agentsApi.clearError(agent.id, resolvedCompanyId ?? undefined);
         case "approve": return agentsApi.approve(agent.id, resolvedCompanyId ?? undefined);
         case "terminate": return agentsApi.terminate(agent.id, resolvedCompanyId ?? undefined);
       }
@@ -265,6 +292,7 @@ export function AgentActionButtons({
   const disabled = actionsDisabled || agentAction.isPending;
   const assignAndRunDisabled = disabled || isPendingApproval || workActionsDisabled;
   const pauseResumeDisabled = disabled || isPendingApproval || (isPaused && workActionsDisabled);
+  const clearErrorDisabled = disabled;
 
   return (
     <div className={className ?? "flex items-center gap-1 sm:gap-2 shrink-0"}>
@@ -284,13 +312,21 @@ export function AgentActionButtons({
         label={runLabel}
         size={size}
       />
-      <PauseResumeButton
-        isPaused={isPaused}
-        onPause={() => agentAction.mutate("pause")}
-        onResume={() => agentAction.mutate("resume")}
-        disabled={pauseResumeDisabled}
-        size={size}
-      />
+      {isError ? (
+        <ClearErrorButton
+          onClick={() => agentAction.mutate("clear_error")}
+          disabled={clearErrorDisabled}
+          size={size}
+        />
+      ) : (
+        <PauseResumeButton
+          isPaused={isPaused}
+          onPause={() => agentAction.mutate("pause")}
+          onResume={() => agentAction.mutate("resume")}
+          disabled={pauseResumeDisabled}
+          size={size}
+        />
+      )}
       {showStatus && (
         <span className="hidden sm:inline">
           <AgentStatusBadge status={agent.status} />