Files
PaperClipAI/ui/src/components/IssueRecoveryActionCard.tsx
T
DottaandClaude Opus 5.5 5ede64f247 fix(recovery): settle an older run's saved-work hold, fold a waiting Retry into the isolated continuation, and plain recovery wording (#21348)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - When a run is interrupted, a saved-work hold protects the files it
left. The fresh-continuation fallback then continues the task in a new
run, or asks a person to press Retry.
> - Staging found that an older run's saved-work hold made the dispatch
gate cancel every new run of the task. The hold was never settled, so
the task could not run again, and no person could act on the reason.
> - Recovery notices also showed internal codes and words such as
"board", "inspect", "repair" and "no live execution path". People cannot
act on these.
> - A person's Retry pressed while an isolated continuation was waiting
for delivery was saved, and then ran a second time after the
continuation.
> - This pull request settles an older run's hold through the fallback's
existing machinery, uses plain wording in every remaining recovery
notice (server and UI together), and folds a waiting Retry into the
isolated continuation that answers it.
> - The benefit is that a task held by an older run continues by itself,
or on one Retry, in a fresh isolated workspace. People read only what
happened and the one thing they can do, and a Retry never starts a
redundant second run.

## Linked Issues or Issue Description

**What happened?**
1. An earlier run's saved-work hold (for example "Automatic recovery of
saved work failed … Retry to try again") made the dispatch gate cancel
every new run of the task with `execution_reconciliation_required`. The
fresh-continuation fallback only took holds of the task's latest run.
Each refused run looked like a newer run, so the hold was never settled.
2. Recovery notices and recovery-task comments showed internal codes,
raw IDs, "board", "inspect", "repair" and "no live execution path". The
hold for remote files that could not be restored asked a person to
"verify its exact stop receipt" and to "record workspaceRepairEvidence".
3. On a projectless task whose old legacy writer might still be alive, a
person's Retry pressed after the isolated continuation was recorded, but
before it was delivered, stayed deferred. When the continuation run
ended, task release promoted that Retry into a second, sequential run.
Concurrent writers were already impossible on this path, because the
Retry waited behind the continuation. The second run was redundant: the
continuation was the answer to the person's Retry.

**Expected behavior**
An older run's hold does not block new runs indefinitely. The task
continues in an isolated workspace, by itself while the interruption is
recent, or on a person's Retry. Notices say what happened and the one
thing to do. A person's Retry answered by the continuation never starts
another run.

**Steps to reproduce**
1. Leave a hold from an older run whose saved-work recovery gave up,
then start a new run of the task. Before this change, the run is
cancelled at dispatch every time and the hold stays.
2. Open a task whose run was cut off and its retries exhausted. Before
this change, the notice reads "No live execution path … visible for
intervention".
3. On a projectless task with an isolated continuation recorded, press
Retry before delivery, then let the continuation end. Before this
change, a second run follows it.

## What Changed

- Older-run holds (`fresh-continuation-fallback.ts`,
`modules/run-dispatch/adapters/postgres.ts`):
- A run that was cancelled at dispatch (status `cancelled`, never
started, `execution_reconciliation_required`) never ran and follows no
run. The held-run listing and the fallback's successor check now ignore
it.
- The older run's hold goes through the fallback's existing machinery. A
saved-work recovery that is still in progress keeps its bounded wait.
Holds that a person owns stay. Past the bound, the hold is settled and
the task continues in a new isolated workspace. Held files are kept,
recorded as `kept_not_applied`, and never applied.
- One recency rule, `interruptionEligibility` (the #21222 rule), judges
recency by the newest run that the hold refused at dispatch. It no
longer uses the end time of the hold's own run. If the last attempt is
older than 24 hours, no automatic continuation starts. A person's Retry
always continues the task.
- After the dispatch gate refuses a run for another run's hold, it hands
that hold to the fallback in the same transaction. The normal dispatch
path is not changed.
- A person's Retry and the isolated continuation (`heartbeat/queue.ts`,
`execution-recovery-resolution.ts`, new
`fresh-continuation-retry-fold.ts`):
- The wake-admission transaction that inserts an isolated continuation
run (context `freshContinuationIsolation`) also coalesces the person's
waiting `task_retry` wake for that task, under the task row lock. This
applies only to a Retry with no message attached. The wake gets `status:
coalesced` and `runId` set to the continuation. A server stop after the
commit cannot leave the Retry unfolded.
- The delivery pass is idempotent about this. An action whose own
continuation is already queued is no longer hidden from the pass. When
the pass finds that continuation, it marks the action delivered and
folds any Retry that is still waiting.
- Before this change, the fold covered only a Retry that was already
waiting when the continuation was recorded. A Retry that carries a
person's message is not folded. Only a Retry whose source run is the
continuation's own source run is folded, and only while the continuation
is queued or running. A Retry for the continuation's own failure gets
its own run.
- Plain wording (server and UI together):
- "No live execution path" is now "Task could not continue". One seed
(`buildNoRunningExecutionNoticeSeed`) builds it for every producer.
- Exhausted saved-work recovery: "Paperclip could not recover the
agent's saved files … Press Retry to try again".
- The non-retryable continuation notice no longer shows the error code.
Recovery-task comments no longer show `stranded_issue_recovery`, raw IDs
or retry reason codes.
- `legacy-execution-recovery.ts` uses plain text for remote files that
could not be restored.
- `IssueRecoveryActionCard`: "Board decision required" is now "Waiting
for you".
- The UI still recognizes notices saved with the old text
(`adjacent-errors.ts`, `system-notice-humanizer.ts`).
  - The precise codes stay in the evidence and in the notice details.
- Merge with current master: `recovery/service.ts` keeps master's
three-way choice (retry exhausted / continuation refused /
non-retryable). The non-retryable branch now uses the plain notice
without the code.
- Code comments that the original commits added are removed
(CONTRIBUTING).

## Verification

Red-to-green tests:
- `server/src/services/fresh-continuation-fallback.test.ts`:
- "continues a task held by an older run's saved-work hold in a new
isolated workspace…"
  - "keeps the wait of a saved-work recovery that is still advancing…"
  - "keeps a hold a person owns blocking…"
- "leaves an old hold for a person's Retry, and that Retry runs
isolated" (refused run and waiting Retry)
- "continues a recent restart-stopped run whose prepared remote
workspace could not be restored…" (red on the wording)
- "leaves an older restart-stopped remote restore failure for a person's
Retry, which then runs isolated"
- Same file, "consumes a person's Retry exactly once when the server
stops right after admitting the isolated continuation": the test runs
the admission and nothing after it. The Retry is already coalesced. The
test then resets it to unfolded, as an older release would leave it, and
runs the next delivery pass. The result is exactly one run and the Retry
consumed. Red without the in-transaction fold, and red without the
delivery-pass fold.
- Same file, "never folds a Retry for the admitted continuation's own
failure into that ended continuation": the continuation ends (real
`cancelRun`), then the person presses Retry on it. The Retry gets its
own run. Red without the source-run and liveness guard.
- Same file, "runs a person's Retry pressed before delivery as the
recorded isolated continuation, never in the shared directory": a
projectless task, an old legacy writer that may still be alive, and an
isolated continuation pending. Delivery starts exactly one run, which
carries `freshContinuationIsolation` in a `fresh_isolated_workspace`.
Extended here: after the continuation run ends (real `cancelRun` release
path, then `resumeQueuedRuns` and delivery), no run comes from the
person's Retry. The Retry wake stays `coalesced` into the continuation.
Red without the delivery fold (the Retry became a second run), green
with it.

Local runs on this branch (based on master 566843820c, independent of
#21347), one file at a time:
- `fresh-continuation-fallback.test.ts`: 72 passed
- `__tests__/recovery-wake-herd.test.ts` 18,
`__tests__/issue-recovery-actions.test.ts` 112,
`workspace-recovery-fallback.test.ts` 19,
`__tests__/execution-control-work.test.ts` 27, `heartbeat/queue.test.ts`
101: all passed
- `recovery/stranded-notice.test.ts`: 32 passed
- `system-recovery-state.test.ts`: 11 passed
- `workspace-recovery-warm-handoff.test.ts`: 44 passed
- `modules/run-dispatch/adapters/postgres.test.ts`: 88 passed
- `__tests__/legacy-workspace-restore-recovery.test.ts`: 73 passed
- `__tests__/heartbeat-process-recovery.test.ts`: 457 passed
- UI: `IssueRecoveryActionCard.test.tsx` 70,
`task-chat/adjacent-errors.test.ts` 26,
`lib/system-notice-humanizer.test.ts` 10,
`task-chat/TaskChatSystemNotice.test.tsx` 14, all passed
- `server` `pnpm run typecheck` (CI's layered typecheck, including
tests) and `ui` `tsc --noEmit`: clean

Test expectations changed on purpose, because they asserted the old
wording or behavior:
- `stranded-notice.test.ts`: seed title "No live execution path" is now
"Task could not continue". "retried dispatch/continuation" is now "tried
to start/continue this task again". A new test covers the plain wording.
- `system-recovery-state.test.ts`: the exact exhausted text is now
"Paperclip could not recover the agent's saved files. Press Retry to try
again; …". "stopped after 6 attempts" is now "after 6 tries". The
refusal text no longer contains "(allocation_ownership_ambiguous)".
"names the last failure and its cause" is replaced by "keeps the failure
code and cause in the evidence".
- `workspace-recovery-warm-handoff.test.ts`: `/stopped after 6
attempts/` is now `/after 6 tries/`.
- `heartbeat-process-recovery.test.ts`: new wording replaces "bounded
retry budget" / "no live execution path" (x2), "retried continuation"
(x2), "retried dispatch" and "3x attempts". "non-retryable failure" +
"`budget_blocked`" is now "retrying alone would not fix", with no code
in the body. The recovery-task comment lines are now plain.
- UI: humanizer "Task paused - waiting on a recovery owner" is now "Task
could not continue". `IssueRecoveryActionCard` "Board decision required"
is now "Waiting for you".
- `fresh-continuation-fallback.test.ts` "runs a person's Retry pressed
before delivery…": it asserted that the Retry's wake stays
`deferred_issue_execution` after delivery. It now asserts that the wake
is `coalesced` into the continuation run.

## Risks

- An older run's hold is now settled automatically while the
interruption is recent. The continuation always runs in a new isolated
workspace, and the held files are never applied, so the old run's files
cannot be overwritten or reused.
- A person's Retry without a message, pressed while an isolated
continuation waits for delivery, does not start a run of its own. The
continuation is the answer to that Retry. A Retry that carries a message
still runs. Concurrent writers were already impossible on this path (the
Retry waited behind the continuation); this change removes the redundant
second run.
- Wording only changes what a person reads. The UI still recognizes
notices that older releases saved.
- No migration. No schema change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Claude Code agent with tool use
(shell, file edit, 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
- [ ] I have updated relevant documentation to reflect my changes (no
documented behavior or command 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-13 05:59:52 -06:00

1571 lines
66 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.
import { useMutation } from "@tanstack/react-query";
import { issuesApi } from "../api/issues";
import { describeError } from "../api/errors";
import { Checkbox } from "./ui/checkbox";
import { NativeSelect } from "./ui/select";
import type { Issue } from "@paperclipai/shared";
import { isNativeWorkspaceExportRepairCause } from "@paperclipai/shared";
import { useWorkspaceIsolationControls } from "@/hooks/useWorkspaceIsolationControls";
import { requiresExecutionReconciliation } from "@paperclipai/shared";
import { useMemo, useState } from "react";
import type {
Agent,
GitWorktreeBranchAncestryVerdict,
IssueRecoveryAction,
IssueRecoveryActionKind,
IssueRecoveryActionOutcome,
IssueRecoveryActionStatus,
IssueScheduledRetry,
} from "@paperclipai/shared";
import {
Eye,
GitBranch,
GitBranchPlus,
Loader2,
Lock,
OctagonAlert,
RefreshCw,
Sparkles,
TriangleAlert,
Wrench,
} from "lucide-react";
import { Link } from "@/lib/router";
import { Button } from "@/components/ui/button";
import { Label } from "@/components/ui/label";
import {
Popover,
PopoverContent,
PopoverTrigger,
} from "@/components/ui/popover";
import { Textarea } from "@/components/ui/textarea";
import { agentUrl } from "@/lib/utils";
import { cn } from "@/lib/utils";
import { Badge } from "@/components/ui/badge";
import {
deriveRecoveryDisplayState,
type RecoveryDisplayState,
} from "@/lib/recovery-display";
import {
formatRecoveryAttemptLabel,
formatRecoveryRetryOffset,
readRecoveryRetryLineage,
type RecoveryRetryLineage,
} from "@/lib/recovery-lineage";
export type RecoveryCardCardState = RecoveryDisplayState;
export const deriveRecoveryCardState = deriveRecoveryDisplayState;
export type RecoveryResolveOutcome =
| "todo"
| "done"
| "in_review"
| "false_positive_done"
| "false_positive_in_review";
/**
* Payload for the "Re-issue on isolated workspace" action (workspace_validation only).
* The caller composes an isolated-workspace re-issue whose git worktree bases off `baseRef`
* — the live (checked-out) branch that diverged, or its HEAD sha when the branch is detached.
*/
export interface RecoveryReissueRequest {
baseRef: string;
liveBranch: string | null;
liveHeadSha: string | null;
expectedBranch: string | null;
}
export interface IssueRecoveryActionCardProps {
action: IssueRecoveryAction;
agentMap?: ReadonlyMap<string, Agent>;
/**
* The source issue's scheduled retry. It is the only signal that can confirm the run the
* wake policy parked is genuinely in flight, which is what separates a retry the scheduler
* is running from one whose due time quietly passed.
*/
scheduledRetry?: IssueScheduledRetry | null;
/** Preferred state hint (e.g. observe_only when watchdog tone is requested). Falls back to derived state. */
forcedState?: RecoveryCardCardState;
/** Optional click handler for resolve menu actions. If omitted, the buttons are not rendered. */
onResolve?: (outcome: RecoveryResolveOutcome) => void;
/**
* Optional handler for the workspace_validation "Re-issue on isolated workspace" action.
* Rendered only for a git-worktree branch-incoherence divergence with a resolvable live ref.
* If omitted, the re-issue button is not shown.
*/
onReissueIsolated?: (request: RecoveryReissueRequest) => void;
/** Whether an isolated re-issue is currently in flight (disables the action + shows a spinner). */
reissuePending?: boolean;
/**
* Handler for action 1 — "Reconcile forward & continue" (workspace_validation only). Rendered
* only for an ancestry-proven (`ancestor`) git-worktree divergence; the caller invokes the S4
* reconcile op in `forward` mode, which re-verifies ancestry server-side (the client hint is
* never trusted). If omitted, the button is not shown.
*/
onReconcileForward?: () => void;
/**
* Handler for action 2 — the audited break-glass override (workspace_validation only). Receives
* the operator's required, non-empty reason and invokes the S4 reconcile op in `override` mode.
* Rendered only when `canBreakGlass` is true AND this handler is provided; the server independently
* rejects agent actors and re-checks runtime-manage permission, so UI hiding is defense-in-depth.
*/
onBreakGlassOverride?: (reason: string) => void;
/**
* Whether the viewer may run the permission-gated break-glass override. When false, action 2 is
* not rendered at all — a non-permitted user never sees the "reconcile anyway" affordance.
*/
canBreakGlass?: boolean;
/**
* Handler for the lossless repair — "Repair workspace — quarantine changes & restore branch"
* (workspace_validation only). Rendered only for a *dirty* divergence; the caller invokes the S4
* reconcile op in `quarantine_restore` mode, which quarantines the dirty worktree onto a rescue
* branch and restores the recorded branch. If omitted, the repair action is not shown.
*/
onQuarantineRestore?: () => void;
/** Whether a quarantine-restore repair is currently in flight (shares the reconcile spinner). */
quarantineRestorePending?: boolean;
/** Whether a reconcile (forward, override, or quarantine-restore) is currently in flight. */
reconcilePending?: boolean;
/** Whether the viewer can run destructive board-only actions (e.g. false-positive dismissal). */
canFalsePositive?: boolean;
/**
* Rendering density. `full` (default) shows the complete metadata table; `compact` drops the
* metadata rows for embedding beside a run on the agent run page, keeping the header, divergence
* diagnosis, and action footer.
*/
variant?: "full" | "compact";
className?: string;
}
const KIND_LABEL: Record<IssueRecoveryActionKind, string> = {
missing_disposition: "Missing Disposition",
deliberate_wait_without_target: "Wait Without A Target",
stranded_assigned_issue: "Stranded Task",
workspace_validation: "Workspace Validation",
configuration_validation: "Configuration Validation",
active_run_watchdog: "Active Watchdog",
issue_graph_liveness: "Task Needs Next Step",
};
const KIND_HEADLINE: Record<IssueRecoveryActionKind, string> = {
missing_disposition:
"This task's run finished, but no next step was chosen. Choose what happens next — try the task again, mark it done, or send it for review.",
deliberate_wait_without_target:
"This task's last run stopped to wait, but there is no reviewer, blocker, monitor, or approval to wait for. Paperclip is repairing the next step; the task stays with its owner.",
stranded_assigned_issue:
"Paperclip retried this task's last run, but there is still no queued run, reviewer, blocker, or other next owner. To get it moving, choose what happens next — try the task again, mark it done, or send it for review.",
workspace_validation:
"Paperclip stopped this run because the task's git workspace could not be validated.",
configuration_validation:
"Paperclip stopped before dispatching this run because required secret/env bindings are missing.",
active_run_watchdog:
"The active run has been silent. Recovery is observing without interrupting it.",
issue_graph_liveness:
"Paperclip could not find a clear next step for this open task. Choose whether to continue work, send it for review, mark it done, or record what is blocking it.",
};
/** Shared shell for the retry-timing pill so every timing state reads as the same control. */
const RETRY_PILL_CLASS =
"rounded-md border border-border/50 bg-background/60 px-1.5 py-0.5 text-(length:--text-micro) text-muted-foreground";
const STATE_TONE: Record<RecoveryCardCardState, {
label: string;
containerClass: string;
iconWrapClass: string;
iconClass: string;
labelClass: string;
Icon: typeof TriangleAlert;
divider: string;
}> = {
needed: {
label: "RECOVERY NEEDED",
containerClass:
"border-amber-300/70 bg-amber-50/85 text-amber-950 dark:border-amber-500/40 dark:bg-amber-500/10 dark:text-amber-100",
iconWrapClass: "bg-amber-100 text-amber-800 dark:bg-amber-500/20 dark:text-amber-200",
iconClass: "text-amber-700 dark:text-amber-300",
labelClass: "text-amber-900 dark:text-amber-200",
Icon: TriangleAlert,
divider: "border-amber-300/60 dark:border-amber-500/30",
},
in_progress: {
label: "RECOVERY IN PROGRESS",
containerClass:
"border-sky-300/70 bg-sky-50/80 text-sky-950 dark:border-sky-500/40 dark:bg-sky-500/10 dark:text-sky-100",
iconWrapClass: "bg-sky-100 text-sky-800 dark:bg-sky-500/20 dark:text-sky-200",
iconClass: "text-sky-700 dark:text-sky-300",
labelClass: "text-sky-900 dark:text-sky-200",
Icon: RefreshCw,
divider: "border-sky-300/60 dark:border-sky-500/30",
},
observe_only: {
label: "OBSERVING ACTIVE RUN",
containerClass:
"border-border bg-muted/40 text-foreground dark:bg-muted/20",
iconWrapClass: "bg-muted text-foreground/70",
iconClass: "text-muted-foreground",
labelClass: "text-muted-foreground",
Icon: Eye,
divider: "border-border/70",
},
escalated: {
label: "RECOVERY ESCALATED",
containerClass:
"border-red-400/60 bg-red-50/85 text-red-950 dark:border-red-500/40 dark:bg-red-500/10 dark:text-red-100",
iconWrapClass: "bg-red-100 text-red-800 dark:bg-red-500/20 dark:text-red-200",
iconClass: "text-red-700 dark:text-red-300",
labelClass: "text-red-900 dark:text-red-200",
Icon: OctagonAlert,
divider: "border-red-400/50 dark:border-red-500/30",
},
resolved: {
label: "RECOVERY RESOLVED",
containerClass:
"border-emerald-300/70 bg-emerald-50/80 text-emerald-950 dark:border-emerald-500/40 dark:bg-emerald-500/10 dark:text-emerald-100",
iconWrapClass: "bg-emerald-100 text-emerald-800 dark:bg-emerald-500/20 dark:text-emerald-200",
iconClass: "text-emerald-700 dark:text-emerald-300",
labelClass: "text-emerald-900 dark:text-emerald-200",
Icon: Sparkles,
divider: "border-emerald-300/60 dark:border-emerald-500/30",
},
};
const OUTCOME_LABEL: Record<IssueRecoveryActionOutcome, string> = {
restored: "restored",
handed_back: "handed back to original owner",
owner_completed: "completed by recovery owner",
delegated: "delegated to follow-up",
false_positive: "false positive",
blocked: "blocked",
escalated: "escalated",
cancelled: "cancelled",
};
function readEvidenceString(value: unknown): string | null {
if (typeof value !== "string") return null;
const trimmed = value.trim();
if (!trimmed) return null;
return trimmed.length > 240 ? `${trimmed.slice(0, 237)}…` : trimmed;
}
// Human-sentence evidence sources render as prose; code-shaped sources
// (error codes, statuses) stay in the mono treatment used for run ids.
const PROSE_EVIDENCE_KEYS = ["summary", "detectedProgressSummary", "missingDisposition", "retryReason"] as const;
const CODE_EVIDENCE_KEYS = ["latestRunErrorCode", "latestRunStatus", "latestIssueStatus"] as const;
function pickEvidenceSummary(action: IssueRecoveryAction): { text: string; isCode: boolean } | null {
const evidence = action.evidence ?? {};
for (const key of PROSE_EVIDENCE_KEYS) {
const next = readEvidenceString(evidence[key]);
if (next) return { text: next, isCode: false };
}
for (const key of CODE_EVIDENCE_KEYS) {
const next = readEvidenceString(evidence[key]);
if (next) return { text: next, isCode: true };
}
return null;
}
function readEvidenceRunId(action: IssueRecoveryAction, key: "sourceRunId" | "correctiveRunId" | "latestRunId") {
const evidence = action.evidence ?? {};
const next = readEvidenceString(evidence[key]);
return next;
}
function asRecord(value: unknown): Record<string, unknown> | null {
return value && typeof value === "object" && !Array.isArray(value)
? (value as Record<string, unknown>)
: null;
}
function asNonEmptyString(value: unknown): string | null {
if (typeof value !== "string") return null;
const trimmed = value.trim();
return trimmed.length > 0 ? trimmed : null;
}
function asAncestryVerdict(value: unknown): GitWorktreeBranchAncestryVerdict | null {
return value === "ancestor" || value === "diverged" || value === "unknown" ? value : null;
}
function formatShortSha(sha: string | null): string | null {
if (!sha) return null;
return sha.length > 10 ? sha.slice(0, 10) : sha;
}
/**
* Diagnosis derived from a workspace_validation recovery action whose underlying failure is a
* git-worktree branch incoherence. The evidence carries the recorded ("expected") branch, the
* live ("actual"/checked-out) branch, both HEAD shas, and a server-computed ancestry verdict +
* plain-language explanation of why the run was declined.
*/
interface WorkspaceContention {
claimedByIssueId: string | null;
claimedByIssueIdentifier: string | null;
/** True when the claiming workspace has a queued/running run (not just a stale claim). */
hasActiveRun: boolean;
}
interface WorkspaceDivergence {
expectedBranch: string | null;
liveBranch: string | null;
expectedHeadSha: string | null;
liveHeadSha: string | null;
ancestryVerdict: GitWorktreeBranchAncestryVerdict | null;
plainLanguageReason: string | null;
cleanliness: "clean" | "dirty" | "unknown" | null;
/** Number of dirty (uncommitted) status entries in the live worktree, when known. */
dirtyFileCount: number | null;
/** Sample of dirty paths (already truncated server-side) for the confirm step. */
dirtyPathSample: string[];
/**
* Another workspace is holding the live branch. When present, the lossless quarantine repair is
* refused server-side — re-issuing on an isolated workspace is the recommended path instead.
*/
contention: WorkspaceContention | null;
/**
* Preview of the rescue branch the quarantine repair will create. The server appends a UTC
* timestamp at repair time, so this is the stable prefix only (rendered with a trailing marker).
*/
rescueBranchPreview: string;
/** Ref a re-issue should base off — the live branch when known, else the live HEAD sha. */
reissueBaseRef: string | null;
}
/** Mirrors the server's `sanitizeBranchName` for a faithful rescue-branch preview. */
function sanitizeBranchComponent(value: string): string {
return (
value
.trim()
.replace(/[^A-Za-z0-9._/-]+/g, "-")
.replace(/-+/g, "-")
.replace(/^[-/.]+|[-/.]+$/g, "")
.slice(0, 120) || "issue"
);
}
function buildRescueBranchPreview(sourceIdentifier: string | null): string {
return `paperclip/rescue/${sanitizeBranchComponent(sourceIdentifier ?? "issue")}/`;
}
function asStringArray(value: unknown): string[] {
if (!Array.isArray(value)) return [];
return value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
}
function asNonNegativeInt(value: unknown): number | null {
return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : null;
}
function readContention(value: unknown): WorkspaceContention | null {
const record = asRecord(value);
if (!record) return null;
const activeRun = asRecord(record.activeRun);
return {
claimedByIssueId: asNonEmptyString(record.claimedByIssueId),
claimedByIssueIdentifier: asNonEmptyString(record.claimedByIssueIdentifier),
hasActiveRun: activeRun !== null,
};
}
function readWorkspaceDivergence(action: IssueRecoveryAction): WorkspaceDivergence | null {
if (action.kind !== "workspace_validation") return null;
const workspaceValidation = asRecord(action.evidence?.workspaceValidation);
if (!workspaceValidation) return null;
if (workspaceValidation.reason !== "git_worktree_branch_incoherence") return null;
const provenance = asRecord(workspaceValidation.provenance) ?? {};
const expectedBranch = asNonEmptyString(workspaceValidation.expectedBranch);
const liveBranch = asNonEmptyString(workspaceValidation.actualBranch);
const expectedHeadSha = asNonEmptyString(provenance.expectedHeadSha);
const liveHeadSha = asNonEmptyString(provenance.actualHeadSha);
const cleanlinessRaw = workspaceValidation.cleanliness;
const cleanliness =
cleanlinessRaw === "clean" || cleanlinessRaw === "dirty" || cleanlinessRaw === "unknown"
? cleanlinessRaw
: null;
const sourceIdentifier = asNonEmptyString(workspaceValidation.sourceIdentifier);
return {
expectedBranch,
liveBranch,
expectedHeadSha,
liveHeadSha,
ancestryVerdict: asAncestryVerdict(provenance.ancestryVerdict),
plainLanguageReason: asNonEmptyString(provenance.plainLanguageReason),
cleanliness,
dirtyFileCount: asNonNegativeInt(workspaceValidation.statusEntryCount),
dirtyPathSample: asStringArray(workspaceValidation.dirtyPathSample),
contention: readContention(workspaceValidation.contention),
rescueBranchPreview: buildRescueBranchPreview(sourceIdentifier),
reissueBaseRef: liveBranch ?? liveHeadSha,
};
}
const ANCESTRY_BADGE: Record<
GitWorktreeBranchAncestryVerdict,
{ label: string; className: string }
> = {
ancestor: {
label: "Forward-only",
className: "border-emerald-400/50 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300",
},
diverged: {
label: "Diverged",
className: "border-red-400/50 bg-red-500/10 text-red-700 dark:text-red-300",
},
unknown: {
label: "Ancestry unknown",
className: "border-border bg-muted/60 text-muted-foreground",
},
};
function BranchFacet({
label,
branch,
sha,
}: {
label: string;
branch: string | null;
sha: string | null;
}) {
const shortSha = formatShortSha(sha);
return (
<div className="min-w-0 rounded-md border border-border/70 bg-background/60 px-2.5 py-2">
<div className="text-(length:--text-nano) font-medium uppercase tracking-(--tracking-label) text-muted-foreground">
{label}
</div>
<div className="mt-1 flex items-center gap-1.5">
<GitBranch className="h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden />
{branch ? (
<code className="truncate font-mono text-xs text-foreground/90">{branch}</code>
) : (
<span className="text-xs italic text-muted-foreground">detached / unknown</span>
)}
</div>
<div className="mt-0.5 pl-5 font-mono text-(length:--text-micro) text-muted-foreground">
{shortSha ? `@ ${shortSha}` : "@ —"}
</div>
</div>
);
}
function DivergenceDiagnosis({
divergence,
dividerClass,
}: {
divergence: WorkspaceDivergence;
dividerClass: string;
}) {
const badge = ANCESTRY_BADGE[divergence.ancestryVerdict ?? "unknown"];
return (
<div
data-testid="recovery-divergence-diagnosis"
className={cn(
"space-y-2.5 border-t bg-background/40 px-3 py-3 dark:bg-background/20 sm:px-4",
dividerClass,
)}
>
<div className="flex flex-wrap items-center gap-2">
<span className="text-(length:--text-micro) font-semibold uppercase tracking-(--tracking-eyebrow) text-muted-foreground">
Divergence diagnosis
</span>
<Badge variant="outline"
data-testid="recovery-ancestry-verdict"
className={cn(
"text-(length:--text-nano) font-semibold uppercase tracking-(--tracking-label)",
badge.className,
)}
>
{badge.label}
</Badge>
</div>
<div className="grid gap-2 sm:grid-cols-2">
<BranchFacet
label="Expected · recorded"
branch={divergence.expectedBranch}
sha={divergence.expectedHeadSha}
/>
<BranchFacet
label="Live · checked out"
branch={divergence.liveBranch}
sha={divergence.liveHeadSha}
/>
</div>
{divergence.plainLanguageReason ? (
<p className="text-xs leading-5 text-foreground/80">{divergence.plainLanguageReason}</p>
) : null}
{divergence.contention ? (
<p
data-testid="recovery-contention-notice"
className="flex items-start gap-1.5 rounded-md border border-amber-400/40 bg-amber-500/5 px-2.5 py-1.5 text-xs leading-5 text-amber-900 dark:text-amber-200"
>
<Lock className="mt-0.5 h-3.5 w-3.5 shrink-0" aria-hidden />
<span>
Worktree claimed by{" "}
<code className="font-mono text-foreground/90">{contentionLabel(divergence.contention)}</code>{" "}
{divergence.contention.hasActiveRun ? "(active run)" : "(claim held)"} — the lossless repair
can&apos;t run while another workspace holds the live branch.
</span>
</p>
) : null}
</div>
);
}
function contentionLabel(contention: WorkspaceContention): string {
return (
contention.claimedByIssueIdentifier ??
(contention.claimedByIssueId ? `issue ${contention.claimedByIssueId.slice(0, 8)}` : "another task")
);
}
/**
* Action 2 — the audited break-glass override. Gated by an explicit confirm step that *restates the
* divergence* (both branches + short SHAs + ancestry verdict) and a required, non-empty reason: the
* confirm button stays disabled until the operator records why. The server re-checks the actor and
* permission and appends the reason to the audit log — this UI gate is the operator-facing guardrail,
* not the security boundary.
*/
function BreakGlassOverride({
divergence,
onConfirm,
pending,
}: {
divergence: WorkspaceDivergence;
onConfirm: (reason: string) => void;
pending: boolean;
}) {
const [reason, setReason] = useState("");
const trimmedReason = reason.trim();
const canSubmit = trimmedReason.length > 0 && !pending;
const verdictBadge = ANCESTRY_BADGE[divergence.ancestryVerdict ?? "unknown"];
const expectedSha = formatShortSha(divergence.expectedHeadSha);
const liveSha = formatShortSha(divergence.liveHeadSha);
return (
<Popover>
<PopoverTrigger asChild>
<Button
type="button"
size="sm"
variant="outline"
disabled={pending}
data-testid="recovery-action-breakglass-trigger"
className="border-red-400/60 text-red-700 hover:bg-red-500/10 dark:border-red-500/40 dark:text-red-300"
>
<OctagonAlert className="h-3.5 w-3.5" aria-hidden />
I&apos;ve verified this — reconcile anyway
</Button>
</PopoverTrigger>
<PopoverContent
align="start"
sideOffset={6}
aria-labelledby="recovery-breakglass-title"
className="w-96 max-w-(--sz-calc-4) space-y-3 p-3"
>
<div className="space-y-1">
<div
id="recovery-breakglass-title"
className="flex items-center gap-1.5 text-(length:--text-micro) font-semibold uppercase tracking-(--tracking-eyebrow) text-red-700 dark:text-red-300"
>
<OctagonAlert className="h-3.5 w-3.5" aria-hidden />
Break-glass reconciliation
</div>
<p className="text-xs leading-5 text-muted-foreground">
This overrides Paperclip&apos;s safety check and points the recorded workspace at the live
branch{" "}
<span className="font-medium text-foreground/80">without an ancestry proof</span>. Confirm
the divergence below and record why before continuing.
</p>
</div>
<dl
data-testid="recovery-breakglass-restated-divergence"
className="space-y-1.5 rounded-md border border-red-400/40 bg-red-500/5 px-2.5 py-2 text-(length:--text-micro)"
>
<div className="flex items-center justify-between gap-2">
<dt className="shrink-0 text-muted-foreground">Recorded · expected</dt>
<dd className="min-w-0 truncate font-mono text-foreground/90">
{divergence.expectedBranch ?? "detached"}
{expectedSha ? ` @ ${expectedSha}` : ""}
</dd>
</div>
<div className="flex items-center justify-between gap-2">
<dt className="shrink-0 text-muted-foreground">Live · checked out</dt>
<dd className="min-w-0 truncate font-mono text-foreground/90">
{divergence.liveBranch ?? "detached"}
{liveSha ? ` @ ${liveSha}` : ""}
</dd>
</div>
<div className="flex items-center justify-between gap-2">
<dt className="shrink-0 text-muted-foreground">Ancestry verdict</dt>
<dd className="font-medium">{verdictBadge.label}</dd>
</div>
</dl>
<div className="space-y-1">
<Label htmlFor="recovery-breakglass-reason" className="text-(length:--text-micro) text-muted-foreground">
Reason <span className="text-red-600 dark:text-red-400">(required — recorded in the audit log)</span>
</Label>
<Textarea
id="recovery-breakglass-reason"
value={reason}
onChange={(event) => setReason(event.target.value)}
placeholder="e.g. Verified the live branch carries only the intended follow-up commits; safe to adopt."
className="min-h-20 text-xs"
data-testid="recovery-breakglass-reason"
aria-required="true"
/>
</div>
<Button
type="button"
size="sm"
variant="destructive"
className="w-full"
disabled={!canSubmit}
data-testid="recovery-action-breakglass-confirm"
onClick={() => {
if (!canSubmit) return;
onConfirm(trimmedReason);
}}
>
{pending ? "Reconciling…" : "Reconcile anyway (break-glass)"}
</Button>
</PopoverContent>
</Popover>
);
}
/**
* The lossless repair — quarantine the dirty worktree onto a rescue branch, then restore the
* recorded branch. Unlike break-glass, this is *non-destructive* (no work is lost, so no reason is
* required): the confirm popover simply restates what will happen — the dirty file count, that the
* live branch is left untouched, the rescue branch that will hold the changes, and the recorded
* branch to be restored. Disabled (with an inline explanation, no popover) when the live branch is
* contended by another workspace, since the server refuses the repair in that case.
*/
function RepairWorkspace({
divergence,
onConfirm,
pending,
disabled,
disabledReason,
}: {
divergence: WorkspaceDivergence;
onConfirm: () => void;
pending: boolean;
disabled: boolean;
disabledReason: string | null;
}) {
const dirtyCount = divergence.dirtyFileCount;
const dirtyLabel =
dirtyCount === null
? "Uncommitted changes"
: `${dirtyCount} uncommitted ${dirtyCount === 1 ? "change" : "changes"}`;
const trigger = (
<Button
type="button"
size="sm"
variant="outline"
disabled={pending || disabled}
data-testid="recovery-action-repair-trigger"
className="border-sky-400/50 text-sky-700 hover:bg-sky-500/10 dark:border-sky-500/40 dark:text-sky-300"
>
{pending ? (
<Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden />
) : (
<Wrench className="h-3.5 w-3.5" aria-hidden />
)}
Repair workspace — quarantine changes &amp; restore branch
</Button>
);
if (disabled) {
// Contended: the server refuses the repair, so render a plainly disabled control with the reason
// inline rather than a popover the operator can't act on.
return (
<div className="flex flex-col gap-1" data-testid="recovery-action-repair-disabled">
{trigger}
{disabledReason ? (
<span className="text-(length:--text-nano) leading-4 text-muted-foreground">
{disabledReason}
</span>
) : null}
</div>
);
}
return (
<Popover>
<PopoverTrigger asChild>{trigger}</PopoverTrigger>
<PopoverContent
align="start"
sideOffset={6}
aria-labelledby="recovery-repair-title"
className="w-96 max-w-(--sz-calc-4) space-y-3 p-3"
>
<div className="space-y-1">
<div
id="recovery-repair-title"
className="flex items-center gap-1.5 text-(length:--text-micro) font-semibold uppercase tracking-(--tracking-eyebrow) text-sky-700 dark:text-sky-300"
>
<Wrench className="h-3.5 w-3.5" aria-hidden />
Repair workspace
</div>
<p className="text-xs leading-5 text-muted-foreground">
This is lossless — no reason required. Your uncommitted changes are committed onto a fresh
rescue branch, then the recorded branch is restored so the task can resume. The live branch
is left exactly as it is.
</p>
</div>
<dl
data-testid="recovery-repair-restated"
className="space-y-1.5 rounded-md border border-sky-400/30 bg-sky-500/5 px-2.5 py-2 text-(length:--text-micro)"
>
<div className="flex items-center justify-between gap-2">
<dt className="shrink-0 text-muted-foreground">Dirty changes</dt>
<dd data-testid="recovery-repair-dirty-count" className="font-medium text-foreground/90">
{dirtyLabel}
</dd>
</div>
<div className="flex items-center justify-between gap-2">
<dt className="shrink-0 text-muted-foreground">Live branch</dt>
<dd className="min-w-0 truncate font-mono text-foreground/90">
{divergence.liveBranch ?? "detached"}
<span className="ml-1 font-sans text-muted-foreground">(left untouched)</span>
</dd>
</div>
<div className="flex items-center justify-between gap-2">
<dt className="shrink-0 text-muted-foreground">Rescue branch</dt>
<dd
data-testid="recovery-repair-rescue-branch"
className="min-w-0 truncate font-mono text-foreground/90"
>
{divergence.rescueBranchPreview}
<span className="text-muted-foreground">&lt;timestamp&gt;</span>
</dd>
</div>
<div className="flex items-center justify-between gap-2">
<dt className="shrink-0 text-muted-foreground">Restore to</dt>
<dd className="min-w-0 truncate font-mono text-foreground/90">
{divergence.expectedBranch ?? "recorded branch"}
</dd>
</div>
</dl>
<Button
type="button"
size="sm"
className="w-full"
disabled={pending}
data-testid="recovery-action-repair-confirm"
onClick={() => {
if (pending) return;
onConfirm();
}}
>
{pending ? "Repairing…" : "Quarantine changes & restore branch"}
</Button>
</PopoverContent>
</Popover>
);
}
function readWakePolicySummary(action: IssueRecoveryAction): string | null {
const policy = action.wakePolicy;
if (!policy) return null;
const type = readEvidenceString(policy.type);
if (!type) return null;
if (type === "wake_owner") return "An agent will be asked to choose the next step";
if (type === "bounded_owner_disposition_repair") {
return "Paperclip is retrying the original owner";
}
if (type === "bounded_recovery_owner") return "An agent is choosing the next step";
if (type === "board_escalation") return "Waiting for you";
if (type === "manual") return "Manual follow-up needed";
if (type === "manual_repair_required") return "Needs a fix before Retry";
if (type === "monitor") {
const interval = readEvidenceString(policy.intervalLabel);
return interval ? `Check scheduled · ${interval}` : "Check scheduled";
}
return type.replaceAll("_", " ");
}
function formatTimeShort(value: string | Date | null | undefined): string | null {
if (!value) return null;
try {
const date = value instanceof Date ? value : new Date(value);
if (Number.isNaN(date.getTime())) return null;
const now = Date.now();
const diffMs = date.getTime() - now;
const absMin = Math.round(Math.abs(diffMs) / 60_000);
if (absMin < 60) {
return diffMs >= 0 ? `in ${absMin}m` : `${absMin}m ago`;
}
return date.toLocaleString(undefined, {
month: "short",
day: "numeric",
hour: "numeric",
minute: "2-digit",
});
} catch {
return null;
}
}
function shortenRunId(runId: string | null | undefined) {
if (!runId) return null;
if (runId.length <= 12) return runId;
return runId.slice(0, 8);
}
function MetadataRow({
label,
children,
}: {
label: string;
children: React.ReactNode;
}) {
return (
<div className="grid grid-cols-(--gtc-8) gap-x-3 gap-y-0 px-3 py-1.5 text-xs sm:px-4">
<dt className="truncate text-(length:--text-micro) font-medium uppercase tracking-(--tracking-label) text-muted-foreground">
{label}
</dt>
<dd className="min-w-0 break-words text-foreground/90">{children}</dd>
</div>
);
}
function MissingValue() {
return <span className="text-muted-foreground">—</span>;
}
function AgentLink({
agentId,
agentMap,
fallback,
}: {
agentId: string | null | undefined;
agentMap?: ReadonlyMap<string, Agent>;
fallback?: string | null;
}) {
if (!agentId) {
return fallback ? <span>{fallback}</span> : <MissingValue />;
}
const agent = agentMap?.get(agentId);
const label = agent?.name ?? `agent ${agentId.slice(0, 8)}`;
if (agent) {
return (
<Link
to={agentUrl(agent)}
className="rounded-sm font-medium underline-offset-2 hover:underline"
>
{label}
</Link>
);
}
return <span className="font-medium">{label}</span>;
}
function RunChip({
runId,
agentId,
status,
}: {
runId: string | null;
agentId: string | null | undefined;
status?: string | null;
}) {
if (!runId) return <MissingValue />;
const short = shortenRunId(runId);
const inner = (
<>
<code className="rounded bg-background/80 px-1.5 py-0.5 font-mono text-(length:--text-micro) text-foreground/80">
run {short}
</code>
{status ? (
<span className="font-sans text-(length:--text-micro) text-muted-foreground">{status}</span>
) : null}
</>
);
if (agentId) {
return (
<Link
to={`/agents/${agentId}/runs/${runId}`}
className="inline-flex items-center gap-2 rounded-sm underline-offset-2 hover:underline"
>
{inner}
</Link>
);
}
return <span className="inline-flex items-center gap-2">{inner}</span>;
}
function formatTimeAbsolute(value: string | Date | null | undefined): string | null {
if (!value) return null;
const date = value instanceof Date ? value : new Date(value);
if (Number.isNaN(date.getTime())) return null;
return date.toLocaleString(undefined, {
month: "short",
day: "numeric",
hour: "numeric",
minute: "2-digit",
});
}
/**
* Headline for an action carrying a bounded retry lineage. It describes the recovery
* state and next step without implying that a repair owner owns the deliverable.
*/
function lineageHeadline(lineage: RecoveryRetryLineage): string {
if (lineage.lane === "native_run") {
if (lineage.liveRunId) return "Paperclip is recovering the existing run.";
if (lineage.exhausted) return "Paperclip could not recover the existing run within its retry budget. Review the recorded failure before retrying.";
if (lineage.retryExpired) return "The retry for the existing run came due and did not start. Review the recorded failure and retry when ready.";
if (lineage.nextRetryAt) return "Paperclip has scheduled another attempt to resume the existing run.";
return "The existing run still needs recovery. Review the recorded failure before retrying.";
}
// An attempt that came due and never ran leaves nobody working on this task, even though
// attempts remain on paper. Say so before any lane wording that ends in "no action needed".
if (lineage.retryExpired) {
return "This task's automatic retry came due and did not run, so nothing is moving it forward right now. Someone must retry it or record the next step.";
}
if (lineage.lane === "source_owner") {
return lineage.exhausted
? "This task's last run stopped to wait, but nothing was waiting for it. The original owner has used every automatic repair attempt, so the next step needs a decision. The task stays with its owner."
: "This task's last run stopped to wait, but nothing was waiting for it. Paperclip is retrying the original owner to record a real next step. The task stays with its owner, and no action is needed yet.";
}
if (lineage.lane === "recovery_owner") {
return "The original owner could not record a next step within its retry budget. A recovery owner is now repairing the path only — the task itself still belongs to its original owner.";
}
return "Automatic recovery is exhausted, so the board must choose the next step. The task itself still belongs to its original owner.";
}
/** Spent/remaining attempts as pips. The readable count lives beside it in text. */
function AttemptMeter({ lineage }: { lineage: RecoveryRetryLineage }) {
if (lineage.maxAttempts === null || lineage.maxAttempts > 12) return null;
const spent = Math.min(lineage.attempt, lineage.maxAttempts);
return (
<span className="inline-flex items-center gap-1" aria-hidden>
{Array.from({ length: lineage.maxAttempts }, (_, index) => (
<span
key={index}
className={cn(
"size-1.5 rounded-full",
index < spent ? "bg-current opacity-80" : "bg-current opacity-25",
)}
/>
))}
</span>
);
}
const RESOLVE_OPTIONS: Array<{
outcome: RecoveryResolveOutcome;
label: string;
description: string;
destructive?: boolean;
boardOnly?: boolean;
}> = [
{
outcome: "todo",
label: "Try again",
description: "Dismiss recovery and return the source task to todo.",
},
{
outcome: "done",
label: "Mark task done",
description: "Restore by recording the requested work as complete.",
},
{
outcome: "in_review",
label: "Send for review",
description: "Hand off to a reviewer with a real review path.",
},
{
outcome: "false_positive_done",
label: "False positive, done",
description: "Dismiss recovery and mark the source task complete.",
destructive: true,
boardOnly: true,
},
{
outcome: "false_positive_in_review",
label: "False positive, review",
description: "Dismiss recovery and send the source task for review.",
destructive: true,
boardOnly: true,
},
];
export function IssueRecoveryActionCard({
action,
agentMap,
scheduledRetry = null,
forcedState,
onResolve,
onReissueIsolated,
reissuePending = false,
onReconcileForward,
onBreakGlassOverride,
onQuarantineRestore,
quarantineRestorePending = false,
canBreakGlass = false,
reconcilePending = false,
canFalsePositive = false,
variant = "full",
className,
}: IssueRecoveryActionCardProps) {
const { visible: workspaceIsolationControlsVisible } = useWorkspaceIsolationControls();
const liveness = useMemo(() => ({ scheduledRetry }), [scheduledRetry]);
const cardState: RecoveryCardCardState = forcedState ?? deriveRecoveryCardState(action, liveness);
const tone = STATE_TONE[cardState];
const ToneIcon = tone.Icon;
const divergence = useMemo(() => readWorkspaceDivergence(action), [action]);
const lineage = useMemo(() => readRecoveryRetryLineage(action, liveness), [action, liveness]);
const headline = useMemo(() => {
if (cardState === "resolved" && action.outcome) {
return `Recovery resolved as ${OUTCOME_LABEL[action.outcome] ?? action.outcome}.`;
}
if (
(cardState === "needed" || cardState === "escalated") &&
action.kind === "active_run_watchdog" &&
action.ownerType === "board"
) {
return "This recovery needs a human decision. Review the recorded failure and choose the next step.";
}
if (lineage) return lineageHeadline(lineage);
return KIND_HEADLINE[action.kind] ?? KIND_HEADLINE.missing_disposition;
}, [action.kind, action.outcome, action.ownerType, cardState, lineage]);
// A lane with no path left must not keep advertising a retry that will never run — whether
// the budget ran out or the scheduled attempt simply never fired.
const wakeSummary = lineage?.retryExpired
? "The scheduled retry did not run — a retry or a decision is needed"
: lineage?.exhausted && !lineage.liveRunId && lineage.lane !== "board"
? "Automatic retries are finished — a decision is needed"
: readWakePolicySummary(action);
const evidenceSummary = pickEvidenceSummary(action);
const sourceRunId = readEvidenceRunId(action, "sourceRunId") ?? readEvidenceRunId(action, "latestRunId");
const correctiveRunId = readEvidenceRunId(action, "correctiveRunId");
// The lineage rows below already carry the attempt budget, so the generic chip only
// covers actions without one.
const showAttempt = !lineage && action.attemptCount > 1 && action.maxAttempts !== null;
const sourceOwnerAgentId = action.returnOwnerAgentId ?? action.previousOwnerAgentId;
const recoveryOwnerIsSourceOwner =
action.ownerType === "agent" &&
action.ownerAgentId !== null &&
action.ownerAgentId === sourceOwnerAgentId;
const retryOffset = lineage ? formatRecoveryRetryOffset(lineage) : null;
const attemptLabel = lineage ? formatRecoveryAttemptLabel(lineage) : null;
const showTimeoutInline = (() => {
// The retry-progress row is the single place a lineage reports its timing.
if (lineage) return false;
if (!action.timeoutAt) return false;
try {
const date = action.timeoutAt instanceof Date ? action.timeoutAt : new Date(action.timeoutAt);
const diffMs = date.getTime() - Date.now();
return diffMs > 0 && diffMs < 60 * 60 * 1000;
} catch {
return false;
}
})();
const updatedAtLabel = formatTimeShort(action.updatedAt);
const ariaState = ({
needed: "needed",
in_progress: "in progress",
observe_only: "observing active run",
escalated: "escalated",
resolved: "resolved",
} satisfies Record<RecoveryCardCardState, string>)[cardState];
const visibleResolveOptions = RESOLVE_OPTIONS.filter((option) => {
if (action.cause === "native_workspace_finalization_owner_unverified") return false;
if (isNativeWorkspaceExportRepairCause(action.cause) && ["todo", "done", "in_review"].includes(option.outcome)) return false;
if (option.outcome === "todo" && requiresExecutionReconciliation(action.cause)) return false;
if (option.boardOnly && !canFalsePositive) return false;
return true;
});
const showResolveActions = onResolve !== undefined && cardState !== "resolved" && visibleResolveOptions.length > 0;
const reissueBaseRef = divergence?.reissueBaseRef ?? null;
const showReissueAction =
workspaceIsolationControlsVisible &&
onReissueIsolated !== undefined &&
cardState !== "resolved" &&
divergence !== null &&
reissueBaseRef !== null;
const reissueVerdictBadge = divergence
? ANCESTRY_BADGE[divergence.ancestryVerdict ?? "unknown"]
: null;
// Action 1 — the ancestry-proven safe path. Only offered when the server-computed verdict is
// "ancestor"; the server re-verifies before mutating, so this gate mirrors (not replaces) it.
const showReconcileForward =
onReconcileForward !== undefined &&
cardState !== "resolved" &&
divergence !== null &&
divergence.ancestryVerdict === "ancestor";
// Action 2 — the break-glass override. Permission-hidden: absent entirely unless the viewer is a
// permitted operator. The confirm step (restated divergence + required reason) lives in the popover.
const showBreakGlass =
onBreakGlassOverride !== undefined &&
cardState !== "resolved" &&
divergence !== null &&
canBreakGlass;
// The lossless repair — offered only for a *dirty* divergence (a clean one reconciles forward or
// via break-glass, with nothing to quarantine). Disabled when the live branch is contended by an
// active claimant, since the server refuses `quarantine_restore` in that case.
const repairContention = divergence?.contention ?? null;
const showRepairAction =
onQuarantineRestore !== undefined &&
cardState !== "resolved" &&
divergence !== null &&
divergence.cleanliness === "dirty";
const repairDisabledReason = repairContention
? `Held by ${contentionLabel(repairContention)}${showReissueAction ? " — re-issue on an isolated workspace instead." : "."}`
: null;
// When contended, the re-issue is the recommended path, so it takes the primary emphasis and a
// "Recommended" hint while the repair button is disabled.
const reissueRecommended = showRepairAction && repairContention !== null;
const showFooter =
showResolveActions ||
showReissueAction ||
showReconcileForward ||
showBreakGlass ||
showRepairAction;
if (requiresExecutionReconciliation(action.cause) || action.cause === "native_workspace_sync_out_unsafe_archive") return null;
return (
<section
role="status"
aria-label={`Recovery action: ${ariaState}`}
data-recovery-state={cardState}
data-recovery-kind={action.kind}
data-recovery-lane={lineage?.lane}
className={cn(
"relative w-full overflow-hidden rounded-lg border text-sm shadow-(--shadow-extract-8)",
tone.containerClass,
className,
)}
>
<header className="flex items-start gap-3 px-3 py-2.5 sm:px-4">
<span
className={cn(
"mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-md",
tone.iconWrapClass,
)}
aria-hidden
>
<ToneIcon className={cn("h-4 w-4", tone.iconClass)} />
</span>
<div className="min-w-0 flex-1">
<div className="flex flex-wrap items-center gap-x-2 gap-y-0.5 text-(length:--text-micro) font-semibold uppercase tracking-(--tracking-eyebrow)">
<span className={tone.labelClass}>{tone.label}</span>
<span className="text-muted-foreground/60" aria-hidden>·</span>
<code className="rounded bg-background/70 px-1.5 py-0.5 font-mono text-(length:--text-micro) tracking-normal text-muted-foreground">
{KIND_LABEL[action.kind] ?? action.kind}
</code>
{updatedAtLabel ? (
<>
<span className="text-muted-foreground/60" aria-hidden>·</span>
<span className="font-medium normal-case tracking-normal text-muted-foreground">
{updatedAtLabel}
</span>
</>
) : null}
</div>
<p className="mt-1 text-sm leading-6">{headline}</p>
</div>
</header>
{variant === "compact" ? null : (
<dl className={cn("border-t bg-background/40 dark:bg-background/20", tone.divider)}>
{lineage ? (
<>
<MetadataRow label="Task owner">
<span
className="inline-flex flex-wrap items-center gap-1.5"
data-testid="recovery-source-owner"
>
<AgentLink
agentId={sourceOwnerAgentId}
agentMap={agentMap}
fallback="unassigned"
/>
<span className="text-muted-foreground">keeps this task</span>
</span>
</MetadataRow>
<MetadataRow label="Recovery owner">
<span
className="inline-flex flex-wrap items-center gap-1.5"
data-testid="recovery-recovery-owner"
>
{lineage.lane === "native_run" && (action.ownerType !== "board" || Boolean(lineage.liveRunId)) ? (
<>
<span className="font-medium">Paperclip</span>
<span className="text-muted-foreground">recovers the existing run</span>
</>
) : recoveryOwnerIsSourceOwner ? (
<span className="font-medium">Original owner — retrying itself</span>
) : action.ownerType === "agent" && action.ownerAgentId ? (
<>
<AgentLink agentId={action.ownerAgentId} agentMap={agentMap} />
<span className="text-muted-foreground">repairs the next step only</span>
</>
) : action.ownerType === "board" ? (
<>
<span className="font-medium">Board</span>
<span className="text-muted-foreground">decides the next step only</span>
</>
) : action.ownerType === "user" && action.ownerUserId ? (
<span className="font-medium">user {action.ownerUserId.slice(0, 6)}</span>
) : (
<span className="text-muted-foreground">unassigned — pick one to wake them</span>
)}
</span>
</MetadataRow>
<MetadataRow label="Retry progress">
<span
className="inline-flex flex-wrap items-center gap-x-2 gap-y-1"
data-testid="recovery-retry-progress"
data-recovery-lane={lineage.lane}
data-recovery-attempt={lineage.attempt}
data-recovery-max-attempts={lineage.maxAttempts ?? undefined}
>
<AttemptMeter lineage={lineage} />
<span>{attemptLabel ?? "Attempts not bounded"}</span>
{lineage.liveRunId ? (
<span
className={RETRY_PILL_CLASS}
title={formatTimeAbsolute(lineage.nextRetryAt) ?? undefined}
data-testid="recovery-next-retry"
>
Attempt running now
</span>
) : lineage.retryExpired ? (
// The due time is stated plainly as missed. Rendering it as "Next try 5m
// ago" is what made an abandoned lane read as healthy recovery.
<span
className={cn(RETRY_PILL_CLASS, "border-destructive/50 bg-destructive/10 text-destructive")}
title={formatTimeAbsolute(lineage.nextRetryAt) ?? undefined}
data-testid="recovery-next-retry"
data-recovery-retry-expired="true"
>
{retryOffset ? `Retry missed ${retryOffset}` : "Retry missed"}
</span>
) : retryOffset ? (
<span
className={RETRY_PILL_CLASS}
title={formatTimeAbsolute(lineage.nextRetryAt) ?? undefined}
data-testid="recovery-next-retry"
>
{retryOffset === "now" ? "Next try now" : `Next try ${retryOffset}`}
</span>
) : lineage.exhausted ? (
<span className={RETRY_PILL_CLASS} data-testid="recovery-next-retry">
Automatic retries used up
</span>
) : null}
</span>
</MetadataRow>
{lineage.lane !== "source_owner" && lineage.sourceMaxAttempts !== null ? (
<MetadataRow label="Owner retries">
<span data-testid="recovery-source-attempts">
The original owner used {lineage.sourceAttempt ?? lineage.sourceMaxAttempts} of{" "}
{lineage.sourceMaxAttempts} automatic attempts.
</span>
</MetadataRow>
) : null}
</>
) : (
<MetadataRow label="Owner">
<span className="inline-flex flex-wrap items-center gap-1.5">
{action.ownerType === "agent" && action.ownerAgentId ? (
<>
<span className="text-muted-foreground">Recovery:</span>
<AgentLink agentId={action.ownerAgentId} agentMap={agentMap} />
</>
) : action.ownerType === "board" ? (
<span className="font-medium">Board</span>
) : action.ownerType === "user" && action.ownerUserId ? (
<span className="font-medium">user {action.ownerUserId.slice(0, 6)}</span>
) : action.ownerType === "system" ? (
<span className="font-medium">System</span>
) : (
<span className="text-muted-foreground">unassigned — pick one to wake them</span>
)}
{action.returnOwnerAgentId ? (
<>
<span className="text-muted-foreground">→ Returns to:</span>
<AgentLink agentId={action.returnOwnerAgentId} agentMap={agentMap} />
</>
) : null}
</span>
</MetadataRow>
)}
<MetadataRow label="Source run">
<RunChip runId={sourceRunId} agentId={action.previousOwnerAgentId} />
</MetadataRow>
{correctiveRunId ? (
<MetadataRow label="Corrective run">
<RunChip runId={correctiveRunId} agentId={action.previousOwnerAgentId} />
</MetadataRow>
) : null}
<MetadataRow label="Evidence">
{evidenceSummary ? (
evidenceSummary.isCode ? (
<span className="break-words font-mono text-(length:--text-micro) text-foreground/80">
{evidenceSummary.text}
</span>
) : (
<span className="text-xs leading-5 text-foreground/80">{evidenceSummary.text}</span>
)
) : (
<MissingValue />
)}
</MetadataRow>
<MetadataRow label="Next action">
{action.nextAction ? <span>{action.nextAction}</span> : <MissingValue />}
</MetadataRow>
<MetadataRow label="Follow-up">
<span className="inline-flex flex-wrap items-center gap-1.5">
{wakeSummary ? <span>{wakeSummary}</span> : <MissingValue />}
{showAttempt ? (
<span className="rounded-md border border-border/50 bg-background/60 px-1.5 py-0.5 text-(length:--text-micro) text-muted-foreground">
attempt {action.attemptCount} of {action.maxAttempts}
</span>
) : null}
{showTimeoutInline ? (
<span className="rounded-md border border-border/50 bg-background/60 px-1.5 py-0.5 text-(length:--text-micro) text-muted-foreground">
Times out {formatTimeShort(action.timeoutAt) ?? "soon"}
</span>
) : null}
</span>
</MetadataRow>
{cardState === "resolved" && action.outcome ? (
<MetadataRow label="Resolution">
<span className={cn("font-medium", tone.labelClass)}>
Resolved as {OUTCOME_LABEL[action.outcome]}
{action.resolvedAt ? ` · ${formatTimeShort(action.resolvedAt) ?? ""}` : ""}
</span>
</MetadataRow>
) : null}
</dl>
)}
{divergence ? <DivergenceDiagnosis divergence={divergence} dividerClass={tone.divider} /> : null}
{showFooter ? (
<div className={cn("flex flex-wrap items-center gap-2 border-t px-3 py-2.5 sm:px-4", tone.divider)}>
{showResolveActions ? (
<Popover>
<PopoverTrigger asChild>
<Button
type="button"
size="sm"
variant="default"
data-testid="recovery-action-resolve-trigger"
aria-label="Resolve recovery"
>
Resolve…
</Button>
</PopoverTrigger>
<PopoverContent
align="start"
sideOffset={6}
className="w-72 p-1.5"
>
<div className="px-2 py-1 text-(length:--text-micro) font-semibold uppercase tracking-(--tracking-eyebrow) text-muted-foreground">
Resolve recovery
</div>
<div className="flex flex-col">
{visibleResolveOptions.map((option) => (
<button
key={option.outcome}
type="button"
onClick={() => onResolve?.(option.outcome)}
className={cn(
"flex flex-col items-start gap-0.5 rounded-md px-2 py-1.5 text-left text-sm transition-colors",
"hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50",
option.destructive ? "text-destructive" : null,
)}
>
<span className="font-medium leading-5">{option.label}</span>
<span className="text-(length:--text-micro) leading-4 text-muted-foreground">{option.description}</span>
</button>
))}
</div>
</PopoverContent>
</Popover>
) : null}
{showReconcileForward ? (
<Button
type="button"
size="sm"
variant="default"
disabled={reconcilePending}
data-testid="recovery-action-reconcile-forward"
onClick={() => onReconcileForward?.()}
>
{reconcilePending ? (
<Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden />
) : (
<RefreshCw className="h-3.5 w-3.5" aria-hidden />
)}
Reconcile forward &amp; continue
</Button>
) : null}
{showRepairAction && divergence ? (
<RepairWorkspace
divergence={divergence}
pending={quarantineRestorePending}
disabled={repairContention !== null}
disabledReason={repairDisabledReason}
onConfirm={() => onQuarantineRestore?.()}
/>
) : null}
{showReissueAction && divergence && reissueBaseRef ? (
<Popover>
<PopoverTrigger asChild>
<Button
type="button"
size="sm"
variant={reissueRecommended ? "default" : "outline"}
disabled={reissuePending}
data-testid="recovery-action-reissue-trigger"
data-recommended={reissueRecommended ? "true" : undefined}
>
{reissuePending ? (
<Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden />
) : (
<GitBranchPlus className="h-3.5 w-3.5" aria-hidden />
)}
Re-issue on isolated workspace
{reissueRecommended ? (
<span
data-testid="recovery-reissue-recommended"
className="ml-1 rounded-sm bg-background/25 px-1.5 py-0.5 text-(length:--text-nano) font-semibold uppercase tracking-(--tracking-label)"
>
Recommended
</span>
) : null}
</Button>
</PopoverTrigger>
<PopoverContent align="start" sideOffset={6} className="w-80 space-y-3 p-3">
<div className="space-y-1">
<div className="text-(length:--text-micro) font-semibold uppercase tracking-(--tracking-eyebrow) text-muted-foreground">
Re-issue on isolated workspace
</div>
<p className="text-xs leading-5 text-muted-foreground">
Creates a fresh copy of this task on an isolated git worktree based on the live
branch. Your current workspace and its commits are left untouched.
</p>
</div>
<dl className="space-y-1 rounded-md border border-border/70 bg-muted/30 px-2.5 py-2 text-(length:--text-micro)">
<div className="flex items-center justify-between gap-2">
<dt className="text-muted-foreground">Base ref</dt>
<dd className="min-w-0 truncate font-mono text-foreground/90">{reissueBaseRef}</dd>
</div>
<div className="flex items-center justify-between gap-2">
<dt className="text-muted-foreground">Recorded</dt>
<dd className="min-w-0 truncate font-mono text-foreground/80">
{divergence.expectedBranch ?? "—"}
</dd>
</div>
{reissueVerdictBadge ? (
<div className="flex items-center justify-between gap-2">
<dt className="text-muted-foreground">Ancestry</dt>
<dd className="font-medium">{reissueVerdictBadge.label}</dd>
</div>
) : null}
</dl>
<Button
type="button"
size="sm"
className="w-full"
disabled={reissuePending}
data-testid="recovery-action-reissue-confirm"
onClick={() =>
onReissueIsolated?.({
baseRef: reissueBaseRef,
liveBranch: divergence.liveBranch,
liveHeadSha: divergence.liveHeadSha,
expectedBranch: divergence.expectedBranch,
})
}
>
{reissuePending ? "Creating…" : "Create isolated re-issue"}
</Button>
</PopoverContent>
</Popover>
) : null}
{showBreakGlass && divergence ? (
<BreakGlassOverride
divergence={divergence}
pending={reconcilePending}
onConfirm={(reason) => onBreakGlassOverride?.(reason)}
/>
) : null}
{showResolveActions ? (
cardState === "observe_only" ? (
<span className="text-(length:--text-micro) text-muted-foreground">
Recovery is observing without interrupting the live run.
</span>
) : (
<span className="text-(length:--text-micro) text-muted-foreground">
The card stays open until an explicit decision is recorded.
</span>
)
) : null}
</div>
) : null}
</section>
);
}
export type { IssueRecoveryActionStatus };
export default IssueRecoveryActionCard;
/** Separate original-host confirmations: the opaque authority is supplied by
* the server snapshot, never entered or edited by the operator. */
export function NativeControllerContainmentRecovery({ issue, canManage, onRecorded }: {
issue: Pick<Issue, "id" | "status" | "activeRecoveryAction">; canManage: boolean; onRecorded: () => void;
}) {
const action = issue.activeRecoveryAction;
const [controllerStopped, setControllerStopped] = useState(false);
const [providerStopped, setProviderStopped] = useState(false);
const [outcome, setOutcome] = useState<"" | "completed" | "not_performed" | "mixed">("");
const [evidence, setEvidence] = useState("");
const authority = action?.evidence?.controllerAuthority;
const digest = authority && typeof authority === "object" && !Array.isArray(authority)
? (authority as Record<string, unknown>).digest : undefined;
const runId = action?.evidence?.runId;
const submit = useMutation({ mutationFn: async () => {
if (!action || typeof runId !== "string" || typeof digest !== "string" || !outcome
|| !controllerStopped || !providerStopped) throw new Error("Confirm both original-host stops and review the action outcomes.");
return issuesApi.resolveRecoveryAction(issue.id, { actionId: action.id, outcome: "restored", sourceIssueStatus: issue.status,
executionReconciliation: { runId, controllerStopped: true, providerStopped: true,
controllerAuthorityDigest: digest, actionOutcome: outcome, outcomeEvidence: evidence.trim() } });
}, onSuccess: onRecorded });
if (!action || action.kind !== "active_run_watchdog" || action.ownerType !== "board"
|| action.cause !== "native_restart_recovery_blocked" || action.evidence?.reason !== "controller_process_space_unverified"
|| !["active", "escalated"].includes(action.status) || typeof digest !== "string") return null;
return <section aria-label="Original controller recovery">
<h3>Verify the original execution stopped</h3>
<p>Paperclip cannot compare process IDs across hosts or kernel sessions. Stop both the controller and provider on the original host before recording evidence. The saved lease must also expire and environment/workspace cleanup must finish. Recording containment does not retry the task.</p>
{canManage ? <>
<Label><Checkbox checked={controllerStopped} onCheckedChange={value => setControllerStopped(value === true)} /> I verified the original controller stopped on its original host.</Label>
<Label><Checkbox checked={providerStopped} onCheckedChange={value => setProviderStopped(value === true)} /> I verified the original provider and its tools stopped on their original host.</Label>
<Label>Reviewed external action outcomes
<NativeSelect value={outcome} onChange={event => {
const value = event.target.value;
if (value === "completed" || value === "not_performed" || value === "mixed" || value === "") setOutcome(value);
}}>
<option value="">Select only after reviewing the effects</option>
<option value="completed">All completed</option>
<option value="not_performed">None performed</option>
<option value="mixed">Some completed and some not performed</option>
</NativeSelect>
</Label>
<Label>Original-host containment evidence and actions that must not be repeated
<Textarea maxLength={12000} value={evidence} onChange={event => setEvidence(event.target.value)} />
</Label>
<p>If any action outcome is still unknown, keep this hold. After evidence and cleanup settle, use the task’s ordinary Retry action separately.</p>
<Button disabled={submit.isPending || !controllerStopped || !providerStopped || !outcome || evidence.trim().length < 20}
onClick={() => submit.mutate()}>{submit.isPending ? "Recording…" : "Record containment"}</Button>
{submit.error && <p role="alert">{describeError(submit.error).body}</p>}
</> : <p>A company owner, company administrator, or instance administrator must review this original-host execution.</p>}
</section>;
}