forked from farhoodlabs/paperclip
[codex] Add source-scoped recovery actions (#5599)
## Thinking Path > - Paperclip is a control plane for autonomous AI companies, where work must end with a clear disposition rather than ambiguous agent liveness. > - Recovery currently detects stalled or missing-next-step issues, but source issue recovery can become split across child recovery issues, blockers, and comments. > - That makes it harder for operators and agents to see who owns recovery and what exact action is needed on the original issue. > - Source-scoped recovery actions give the original issue a first-class active recovery state with owner, evidence, wake policy, and resolution outcome. > - This pull request adds the recovery-action data model, backend reconciliation and resolution APIs, and board UI indicators/actions. > - The benefit is clearer stalled-work recovery without losing source issue context or relying on comments as the liveness path. ## What Changed - Added the `issue_recovery_actions` schema, shared types/constants/validators, and an idempotent `0084_issue_recovery_actions` migration ordered after current `master` migrations. - Updated stranded/missing-disposition recovery to create source-scoped recovery actions, wake the recovery owner on the source issue, and avoid locking the source issue for recovery-action wakes. - Added API support for reading active recovery actions on issue detail/list surfaces and resolving them with restored, blocked, cancelled, or false-positive outcomes. - Require blocked recovery resolutions to have an unresolved first-class blocker, and removed the UI shortcut that could mark recovery blocked without a blocker selection path. - Surfaced recovery indicators/actions in the issue UI, blocker notices, active run panels, issue rows, and Storybook coverage. - Updated docs and focused tests for recovery semantics, ownership, races, stale comments, and UI behavior. ## Verification - `pnpm exec vitest run server/src/__tests__/issue-recovery-actions.test.ts server/src/__tests__/heartbeat-process-recovery.test.ts ui/src/components/IssueRecoveryActionCard.test.tsx ui/src/components/IssueBlockedNotice.test.tsx ui/src/api/issues.test.ts` — 5 files, 72 tests passed. - `pnpm --filter @paperclipai/shared typecheck` — passed. - `pnpm --filter @paperclipai/db typecheck` — passed, including migration numbering check. - `pnpm --filter @paperclipai/server typecheck` — passed. - `pnpm --filter @paperclipai/ui typecheck` — passed. - Follow-up verification after blocker-resolution guard: `pnpm exec vitest run server/src/__tests__/issue-recovery-actions.test.ts ui/src/components/IssueRecoveryActionCard.test.tsx ui/src/api/issues.test.ts` — 3 files, 27 tests passed. - Follow-up `pnpm --filter @paperclipai/server typecheck` — passed. - Follow-up `pnpm --filter @paperclipai/ui typecheck` — passed. - UI states are available in `ui/storybook/stories/source-issue-recovery.stories.tsx`; screenshot capture helper is `scripts/screenshot-recovery-card.cjs`. ## Risks - Medium: recovery behavior changes from child recovery issue ownership toward source-scoped actions, so operators may see stalled-work state in new places. - Migration risk is mitigated by using the next migration slot after `master` and making the table/constraints/index creation idempotent for anyone who previously applied the old branch-local `0082_dizzy_master_mold` migration. - Existing child recovery issue paths are still guarded for already-created recovery issues, but new source-scoped flows should be watched in CI and Greptile review. > 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 coding agent, tool use enabled for shell, Git, GitHub, and local test execution. Context window not exposed by the runtime. ## 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
@@ -0,0 +1,218 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import { act } from "react";
|
||||
import { createRoot } from "react-dom/client";
|
||||
import type { AnchorHTMLAttributes, ReactElement } from "react";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import type { Agent, IssueRecoveryAction } from "@paperclipai/shared";
|
||||
import { IssueRecoveryActionCard, deriveRecoveryCardState } from "./IssueRecoveryActionCard";
|
||||
|
||||
vi.mock("@/lib/router", () => ({
|
||||
Link: ({ children, to, ...props }: AnchorHTMLAttributes<HTMLAnchorElement> & { to: string }) => (
|
||||
<a href={to} {...props}>{children}</a>
|
||||
),
|
||||
}));
|
||||
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
|
||||
|
||||
let root: ReturnType<typeof createRoot> | null = null;
|
||||
let container: HTMLDivElement | null = null;
|
||||
|
||||
afterEach(() => {
|
||||
if (root) {
|
||||
act(() => root?.unmount());
|
||||
}
|
||||
root = null;
|
||||
container?.remove();
|
||||
container = null;
|
||||
});
|
||||
|
||||
function render(element: ReactElement) {
|
||||
container = document.createElement("div");
|
||||
document.body.appendChild(container);
|
||||
root = createRoot(container);
|
||||
act(() => root?.render(element));
|
||||
return container;
|
||||
}
|
||||
|
||||
function click(element: Element | null) {
|
||||
if (!element) throw new Error("Expected element to exist");
|
||||
act(() => {
|
||||
element.dispatchEvent(new MouseEvent("click", { bubbles: true }));
|
||||
});
|
||||
}
|
||||
|
||||
const ownerAgent: Agent = {
|
||||
id: "11111111-1111-1111-1111-111111111111",
|
||||
companyId: "company-1",
|
||||
name: "ClaudeCoder",
|
||||
role: "engineer",
|
||||
status: "idle",
|
||||
adapterType: "claude_local",
|
||||
adapterConfig: {},
|
||||
runtimeConfig: {},
|
||||
permissions: {},
|
||||
urlKey: "claudecoder",
|
||||
} as unknown as Agent;
|
||||
|
||||
const returnAgent: Agent = {
|
||||
...ownerAgent,
|
||||
id: "22222222-2222-2222-2222-222222222222",
|
||||
name: "CodexCoder",
|
||||
urlKey: "codexcoder",
|
||||
} as Agent;
|
||||
|
||||
function buildAction(overrides: Partial<IssueRecoveryAction> = {}): IssueRecoveryAction {
|
||||
return {
|
||||
id: "00000000-0000-0000-0000-0000000000aa",
|
||||
companyId: "company-1",
|
||||
sourceIssueId: "00000000-0000-0000-0000-0000000000ff",
|
||||
recoveryIssueId: null,
|
||||
kind: "missing_disposition",
|
||||
status: "active",
|
||||
ownerType: "agent",
|
||||
ownerAgentId: ownerAgent.id,
|
||||
ownerUserId: null,
|
||||
previousOwnerAgentId: returnAgent.id,
|
||||
returnOwnerAgentId: returnAgent.id,
|
||||
cause: "missing_disposition",
|
||||
fingerprint: "fp",
|
||||
evidence: {
|
||||
summary: "Run finished but no disposition was chosen.",
|
||||
sourceRunId: "7accd7a4-c9ca-4db2-9233-3228a037cc09",
|
||||
},
|
||||
nextAction: "Choose and record a valid issue disposition.",
|
||||
wakePolicy: { type: "wake_owner" },
|
||||
monitorPolicy: null,
|
||||
attemptCount: 1,
|
||||
maxAttempts: 3,
|
||||
timeoutAt: null,
|
||||
lastAttemptAt: "2026-05-09T19:30:00.000Z",
|
||||
outcome: null,
|
||||
resolutionNote: null,
|
||||
resolvedAt: null,
|
||||
createdAt: "2026-05-09T19:30:00.000Z",
|
||||
updatedAt: "2026-05-09T19:30:00.000Z",
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("deriveRecoveryCardState", () => {
|
||||
it("maps active missing_disposition to needed", () => {
|
||||
expect(deriveRecoveryCardState(buildAction())).toBe("needed");
|
||||
});
|
||||
|
||||
it("maps active_run_watchdog to observe_only", () => {
|
||||
expect(deriveRecoveryCardState(buildAction({ kind: "active_run_watchdog" }))).toBe("observe_only");
|
||||
});
|
||||
|
||||
it("maps escalated status to escalated", () => {
|
||||
expect(deriveRecoveryCardState(buildAction({ status: "escalated" }))).toBe("escalated");
|
||||
});
|
||||
|
||||
it("maps resolved/cancelled to resolved", () => {
|
||||
expect(deriveRecoveryCardState(buildAction({ status: "resolved" }))).toBe("resolved");
|
||||
expect(deriveRecoveryCardState(buildAction({ status: "cancelled" }))).toBe("resolved");
|
||||
});
|
||||
});
|
||||
|
||||
describe("IssueRecoveryActionCard", () => {
|
||||
it("renders required fields and an aria-label naming the state", () => {
|
||||
const node = render(
|
||||
<IssueRecoveryActionCard
|
||||
action={buildAction()}
|
||||
agentMap={new Map([
|
||||
[ownerAgent.id, ownerAgent],
|
||||
[returnAgent.id, returnAgent],
|
||||
])}
|
||||
onResolve={() => {}}
|
||||
/>,
|
||||
);
|
||||
const section = node.querySelector("section[aria-label]");
|
||||
expect(section?.getAttribute("aria-label")).toBe("Recovery action: needed");
|
||||
expect(node.textContent).toContain("RECOVERY NEEDED");
|
||||
expect(node.textContent).toContain("Missing Disposition");
|
||||
expect(node.textContent).not.toContain("missing_disposition");
|
||||
expect(node.textContent).toContain("This issue's run finished, but no next step was chosen.");
|
||||
expect(node.textContent).toContain("ClaudeCoder");
|
||||
expect(node.textContent).toContain("CodexCoder");
|
||||
expect(node.textContent).toContain("Choose and record a valid issue disposition.");
|
||||
expect(node.textContent).toContain("Corrective wake queued");
|
||||
});
|
||||
|
||||
it("falls back to em dash when wake policy is absent", () => {
|
||||
const node = render(
|
||||
<IssueRecoveryActionCard action={buildAction({ wakePolicy: null })} />,
|
||||
);
|
||||
expect(node.textContent).toContain("—");
|
||||
});
|
||||
|
||||
it("renders observe_only tone for active_run_watchdog", () => {
|
||||
const node = render(
|
||||
<IssueRecoveryActionCard action={buildAction({ kind: "active_run_watchdog" })} />,
|
||||
);
|
||||
const section = node.querySelector("section[aria-label]");
|
||||
expect(section?.getAttribute("aria-label")).toBe("Recovery action: observing active run");
|
||||
expect(node.textContent).toContain("OBSERVING ACTIVE RUN");
|
||||
});
|
||||
|
||||
it("renders the resolved label and outcome when resolved", () => {
|
||||
const node = render(
|
||||
<IssueRecoveryActionCard action={buildAction({ status: "resolved", outcome: "restored", resolvedAt: "2026-05-09T19:35:00.000Z" })} />,
|
||||
);
|
||||
expect(node.textContent).toContain("RECOVERY RESOLVED");
|
||||
expect(node.textContent).toContain("Resolved as restored");
|
||||
});
|
||||
|
||||
it("calls resolve with done and does not offer delegated recovery", () => {
|
||||
const onResolve = vi.fn();
|
||||
const node = render(
|
||||
<IssueRecoveryActionCard action={buildAction()} onResolve={onResolve} />,
|
||||
);
|
||||
click(node.querySelector("[data-testid='recovery-action-resolve-trigger']"));
|
||||
|
||||
expect(document.body.textContent).toContain("Mark issue done");
|
||||
expect(document.body.textContent).not.toContain("Mark blocked");
|
||||
expect(document.body.textContent).not.toContain("Delegate follow-up issue");
|
||||
click([...document.body.querySelectorAll("button")].find((button) => button.textContent?.includes("Mark issue done")) ?? null);
|
||||
|
||||
expect(onResolve).toHaveBeenCalledWith("done");
|
||||
});
|
||||
|
||||
it("does not offer blocked recovery resolution without a blocker selection flow", () => {
|
||||
const node = render(
|
||||
<IssueRecoveryActionCard action={buildAction()} onResolve={() => {}} canFalsePositive />,
|
||||
);
|
||||
click(node.querySelector("[data-testid='recovery-action-resolve-trigger']"));
|
||||
|
||||
expect(document.body.textContent).toContain("Mark issue done");
|
||||
expect(document.body.textContent).toContain("Send for review");
|
||||
expect(document.body.textContent).toContain("False positive, done");
|
||||
expect(document.body.textContent).toContain("False positive, review");
|
||||
expect(document.body.textContent).not.toContain("Mark blocked");
|
||||
});
|
||||
|
||||
it("hides false-positive options unless canFalsePositive is set", () => {
|
||||
const first = render(
|
||||
<IssueRecoveryActionCard action={buildAction()} onResolve={() => {}} />,
|
||||
);
|
||||
click(first.querySelector("[data-testid='recovery-action-resolve-trigger']"));
|
||||
expect(document.body.textContent).not.toContain("False positive");
|
||||
|
||||
act(() => root?.unmount());
|
||||
root = null;
|
||||
container?.remove();
|
||||
container = null;
|
||||
|
||||
const onResolve = vi.fn();
|
||||
const second = render(
|
||||
<IssueRecoveryActionCard action={buildAction()} onResolve={onResolve} canFalsePositive />,
|
||||
);
|
||||
click(second.querySelector("[data-testid='recovery-action-resolve-trigger']"));
|
||||
expect(document.body.textContent).toContain("False positive, done");
|
||||
expect(document.body.textContent).toContain("False positive, review");
|
||||
click([...document.body.querySelectorAll("button")].find((button) => button.textContent?.includes("False positive, done")) ?? null);
|
||||
expect(onResolve).toHaveBeenCalledWith("false_positive_done");
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user