Build routine revision history tab and conflict-aware save flow

Adds the History tab on routine detail (PAP-3584) on top of the revision API
shipped in PAP-3583. Board users can now inspect every routine revision,
preview historical content, compare against current with structured
field-changes plus a description line diff, and restore an older revision —
which always appends a new latest revision so history stays append-only.

Behavior:

- New API client methods listRevisions / restoreRevision plus a routines
  revisions queryKey.
- Routine save now sends the current latestRevisionId as baseRevisionId; a
  409 from the server flips an "Out of date" banner on the editor and
  invalidates the detail query so the user can reload before retrying.
- Historical-preview banner spells out the append-only semantics and
  shows the next revision number.
- Restore confirmation dialog enumerates side effects, including a per-
  trigger callout for any webhook trigger that will be re-created with a
  fresh secret. Recreated webhook secret material is mounted in the
  existing routine secret banner so the user can copy URL + secret once.
- Conflict path: when the routine editor has unsaved local edits, the
  History tab blocks historical previews and surfaces an itemized
  "Unsaved routine edits" banner with Discard / Save and continue.
- Loading, empty (only revision 1), and error states are covered.
- Restored success state highlights the new revision row, auto-selects
  it, and surfaces a success toast naming both rev numbers.

Tests:

- ui/src/lib/line-diff.test.ts covers the lifted diff helper.
- ui/src/components/RoutineHistoryTab.test.tsx covers empty state,
  list rendering, historical-preview banner copy, dirty-edit conflict
  blocking, and the restore mutation success path.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

ui/src/api/routines.ts

@@ -3,6 +3,7 @@ import type {
   Routine,
   RoutineDetail,
   RoutineListItem,
+  RoutineRevision,
   RoutineRun,
   RoutineRunSummary,
   RoutineTrigger,
@@ -21,6 +22,18 @@ export interface RotateRoutineTriggerResponse {
   secretMaterial: RoutineTriggerSecretMaterial;
 }
 
+export interface RestoreRoutineRevisionSecretMaterial extends RoutineTriggerSecretMaterial {
+  triggerId: string;
+}
+
+export interface RestoreRoutineRevisionResponse {
+  routine: Routine;
+  revision: RoutineRevision;
+  restoredFromRevisionId: string;
+  restoredFromRevisionNumber: number;
+  secretMaterials: RestoreRoutineRevisionSecretMaterial[];
+}
+
 export const routinesApi = {
   list: (companyId: string, filters?: { projectId?: string | null }) => {
     const params = new URLSearchParams();
@@ -32,6 +45,16 @@ export const routinesApi = {
     api.post<Routine>(`/companies/${companyId}/routines`, data),
   get: (id: string) => api.get<RoutineDetail>(`/routines/${id}`),
   update: (id: string, data: Record<string, unknown>) => api.patch<Routine>(`/routines/${id}`, data),
+  listRevisions: (id: string) => api.get<RoutineRevision[]>(`/routines/${id}/revisions`),
+  restoreRevision: (
+    id: string,
+    revisionId: string,
+    body: { changeSummary?: string | null } = {},
+  ) =>
+    api.post<RestoreRoutineRevisionResponse>(
+      `/routines/${id}/revisions/${revisionId}/restore`,
+      body,
+    ),
   listRuns: (id: string, limit: number = 50) => api.get<RoutineRunSummary[]>(`/routines/${id}/runs?limit=${limit}`),
   createTrigger: (id: string, data: Record<string, unknown>) =>
     api.post<RoutineTriggerResponse>(`/routines/${id}/triggers`, data),

ui/src/components/RoutineHistoryTab.test.tsx

@@ -0,0 +1,320 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import type { ComponentProps } from "react";
+import { createRoot } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type {
+  Routine,
+  RoutineRevision,
+  RoutineRevisionSnapshotV1,
+} from "@paperclipai/shared";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { RoutineHistoryTab } from "./RoutineHistoryTab";
+
+const mockRoutinesApi = vi.hoisted(() => ({
+  listRevisions: vi.fn(),
+  restoreRevision: vi.fn(),
+}));
+
+vi.mock("../api/routines", async () => {
+  const actual = await vi.importActual<Record<string, unknown>>("../api/routines");
+  return {
+    ...actual,
+    routinesApi: {
+      ...((actual as { routinesApi?: Record<string, unknown> }).routinesApi ?? {}),
+      ...mockRoutinesApi,
+    },
+  };
+});
+
+vi.mock("./MarkdownBody", () => ({
+  MarkdownBody: ({ children }: { children: string }) => <div>{children}</div>,
+}));
+
+vi.mock("@/components/ui/dialog", () => ({
+  Dialog: ({ open, children }: { open: boolean; children: React.ReactNode }) =>
+    open ? <div data-testid="dialog">{children}</div> : null,
+  DialogContent: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  DialogHeader: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  DialogTitle: ({ children }: { children: React.ReactNode }) => <h2>{children}</h2>,
+  DialogDescription: ({ children }: { children: React.ReactNode }) => <p>{children}</p>,
+  DialogFooter: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+}));
+
+vi.mock("@/components/ui/button", () => ({
+  Button: ({ children, onClick, type = "button", disabled, ...props }: ComponentProps<"button">) => (
+    <button type={type} onClick={onClick} disabled={disabled} {...props}>
+      {children}
+    </button>
+  ),
+}));
+
+vi.mock("@/components/ui/input", () => ({
+  Input: (props: ComponentProps<"input">) => <input {...props} />,
+}));
+
+vi.mock("@/components/ui/label", () => ({
+  Label: ({ children, htmlFor }: { children: React.ReactNode; htmlFor?: string }) => (
+    <label htmlFor={htmlFor}>{children}</label>
+  ),
+}));
+
+vi.mock("@/components/ui/skeleton", () => ({
+  Skeleton: (props: ComponentProps<"div">) => <div data-testid="skeleton" {...props} />,
+}));
+
+const toastSpy = vi.fn();
+vi.mock("../context/ToastContext", () => ({
+  useToastActions: () => ({ pushToast: toastSpy }),
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+async function flush() {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+function snapshotV1(overrides?: Partial<RoutineRevisionSnapshotV1["routine"]>): RoutineRevisionSnapshotV1 {
+  return {
+    version: 1,
+    routine: {
+      id: "routine-1",
+      companyId: "company-1",
+      projectId: null,
+      goalId: null,
+      parentIssueId: null,
+      title: "Daily standup digest",
+      description: "Summarize standup notes",
+      assigneeAgentId: null,
+      priority: "medium",
+      status: "active",
+      concurrencyPolicy: "coalesce_if_active",
+      catchUpPolicy: "skip_missed",
+      variables: [],
+      ...overrides,
+    },
+    triggers: [],
+  };
+}
+
+function createRevision(overrides: Partial<RoutineRevision> = {}): RoutineRevision {
+  return {
+    id: overrides.id ?? "revision-1",
+    companyId: "company-1",
+    routineId: "routine-1",
+    revisionNumber: overrides.revisionNumber ?? 1,
+    title: "Daily standup digest",
+    description: "Summarize standup notes",
+    snapshot: overrides.snapshot ?? snapshotV1(),
+    changeSummary: null,
+    restoredFromRevisionId: null,
+    createdByAgentId: null,
+    createdByUserId: "user-1",
+    createdByRunId: null,
+    createdAt: new Date("2026-05-01T12:00:00.000Z"),
+    ...overrides,
+  };
+}
+
+function createRoutine(overrides: Partial<Routine> = {}): Routine {
+  return {
+    id: "routine-1",
+    companyId: "company-1",
+    projectId: null,
+    goalId: null,
+    parentIssueId: null,
+    title: "Daily standup digest",
+    description: "Summarize standup notes",
+    assigneeAgentId: null,
+    priority: "medium",
+    status: "active",
+    concurrencyPolicy: "coalesce_if_active",
+    catchUpPolicy: "skip_missed",
+    variables: [],
+    latestRevisionId: "revision-2",
+    latestRevisionNumber: 2,
+    createdByAgentId: null,
+    createdByUserId: "user-1",
+    updatedByAgentId: null,
+    updatedByUserId: "user-1",
+    lastTriggeredAt: null,
+    lastEnqueuedAt: null,
+    createdAt: new Date("2026-05-01T11:00:00.000Z"),
+    updatedAt: new Date("2026-05-04T12:00:00.000Z"),
+    ...overrides,
+  };
+}
+
+function makeQueryClient() {
+  return new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+}
+
+describe("RoutineHistoryTab", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    vi.clearAllMocks();
+    toastSpy.mockReset();
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  async function render(props: Partial<Parameters<typeof RoutineHistoryTab>[0]> = {}) {
+    const root = createRoot(container);
+    const queryClient = makeQueryClient();
+    const routine = props.routine ?? createRoutine();
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <RoutineHistoryTab
+            routine={routine}
+            isEditDirty={false}
+            dirtyFields={[]}
+            onDiscardEdits={() => {}}
+            onSaveEdits={() => {}}
+            agents={new Map()}
+            projects={new Map()}
+            onRestoreSecretMaterials={() => {}}
+            {...props}
+          />
+        </QueryClientProvider>,
+      );
+    });
+    await flush();
+    return root;
+  }
+
+  it("shows the empty state when only the bootstrap revision exists", async () => {
+    mockRoutinesApi.listRevisions.mockResolvedValue([
+      createRevision({ id: "revision-1", revisionNumber: 1 }),
+    ]);
+    await render({
+      routine: createRoutine({ latestRevisionId: "revision-1", latestRevisionNumber: 1 }),
+    });
+    expect(container.textContent).toContain("No edits yet");
+    expect(container.textContent).toContain("Revision 1 is the only history");
+  });
+
+  it("renders the revision list with current and historical pills", async () => {
+    const current = createRevision({
+      id: "revision-2",
+      revisionNumber: 2,
+      changeSummary: "Updated routine",
+    });
+    const old = createRevision({
+      id: "revision-1",
+      revisionNumber: 1,
+      changeSummary: "Created routine",
+    });
+    mockRoutinesApi.listRevisions.mockResolvedValue([current, old]);
+    await render();
+    expect(container.textContent).toContain("rev 2");
+    expect(container.textContent).toContain("rev 1");
+    expect(container.textContent).toContain("Current");
+  });
+
+  it("shows the historical-preview banner with append-only copy when previewing an old revision", async () => {
+    const current = createRevision({
+      id: "revision-2",
+      revisionNumber: 2,
+      changeSummary: "Updated routine",
+    });
+    const old = createRevision({
+      id: "revision-1",
+      revisionNumber: 1,
+      changeSummary: "Created routine",
+    });
+    mockRoutinesApi.listRevisions.mockResolvedValue([current, old]);
+    await render();
+    const oldRow = container.querySelector(
+      "[data-testid='revision-row-1']",
+    ) as HTMLButtonElement | null;
+    expect(oldRow).not.toBeNull();
+    await act(async () => {
+      oldRow?.click();
+    });
+    await flush();
+    expect(container.textContent).toContain("Viewing revision 1 (read-only)");
+    expect(container.textContent).toContain(
+      "Restoring this revision creates a new revision 3 with the same content. History stays append-only.",
+    );
+    expect(container.textContent).toContain("Restore as new revision");
+  });
+
+  it("blocks historical preview and surfaces the conflict banner when local edits are dirty", async () => {
+    const current = createRevision({ id: "revision-2", revisionNumber: 2 });
+    const old = createRevision({ id: "revision-1", revisionNumber: 1 });
+    mockRoutinesApi.listRevisions.mockResolvedValue([current, old]);
+    await render({
+      isEditDirty: true,
+      dirtyFields: [{ key: "description", label: "the description" }],
+    });
+    expect(container.textContent).toContain("Unsaved routine edits");
+    const oldRow = container.querySelector(
+      "[data-testid='revision-row-1']",
+    ) as HTMLButtonElement | null;
+    expect(oldRow?.disabled).toBe(true);
+  });
+
+  it("calls restoreRevision and surfaces a success toast after confirming restore", async () => {
+    const current = createRevision({ id: "revision-2", revisionNumber: 2 });
+    const old = createRevision({ id: "revision-1", revisionNumber: 1 });
+    mockRoutinesApi.listRevisions.mockResolvedValue([current, old]);
+    mockRoutinesApi.restoreRevision.mockResolvedValue({
+      routine: createRoutine({ latestRevisionId: "revision-3", latestRevisionNumber: 3 }),
+      revision: createRevision({
+        id: "revision-3",
+        revisionNumber: 3,
+        restoredFromRevisionId: "revision-1",
+      }),
+      restoredFromRevisionId: "revision-1",
+      restoredFromRevisionNumber: 1,
+      secretMaterials: [],
+    });
+    await render();
+    const oldRow = container.querySelector(
+      "[data-testid='revision-row-1']",
+    ) as HTMLButtonElement | null;
+    await act(async () => {
+      oldRow?.click();
+    });
+    await flush();
+    const restoreButtons = Array.from(container.querySelectorAll("button")).filter(
+      (button) => button.textContent === "Restore as new revision",
+    );
+    expect(restoreButtons.length).toBeGreaterThan(0);
+    await act(async () => {
+      restoreButtons[0].click();
+    });
+    await flush();
+    expect(container.querySelector("[data-testid='dialog']")).not.toBeNull();
+    const confirmButtons = Array.from(container.querySelectorAll("button")).filter((b) =>
+      (b.textContent ?? "").includes("Restore as revision 3"),
+    );
+    expect(confirmButtons.length).toBeGreaterThan(0);
+    await act(async () => {
+      confirmButtons[0].click();
+    });
+    await flush();
+    expect(mockRoutinesApi.restoreRevision).toHaveBeenCalledWith(
+      "routine-1",
+      "revision-1",
+      { changeSummary: null },
+    );
+    expect(toastSpy).toHaveBeenCalled();
+    const successCall = toastSpy.mock.calls.find(
+      (call) => call[0]?.title === "Restored revision 1 as revision 3",
+    );
+    expect(successCall).toBeTruthy();
+  });
+});

ui/src/lib/queryKeys.ts

@@ -70,6 +70,7 @@ export const queryKeys = {
       ["routines", companyId, filters?.projectId ?? "__all-projects__"] as const,
     detail: (id: string) => ["routines", "detail", id] as const,
     runs: (id: string) => ["routines", "runs", id] as const,
+    revisions: (id: string) => ["routines", "revisions", id] as const,
     activity: (companyId: string, id: string) => ["routines", "activity", companyId, id] as const,
   },
   executionWorkspaces: {

ui/src/pages/RoutineDetail.tsx

@@ -7,6 +7,7 @@ import {
   ChevronRight,
   Clock3,
   Copy,
+  History as HistoryIcon,
   Play,
   RefreshCw,
   Repeat,
@@ -15,7 +16,12 @@ import {
   Webhook,
   Zap,
 } from "lucide-react";
-import { routinesApi, type RoutineTriggerResponse, type RotateRoutineTriggerResponse } from "../api/routines";
+import { ApiError } from "../api/client";
+import { routinesApi, type RoutineTriggerResponse, type RotateRoutineTriggerResponse, type RestoreRoutineRevisionResponse } from "../api/routines";
+import {
+  RoutineHistoryTab,
+  type RoutineHistoryDirtyFieldDescriptor,
+} from "../components/RoutineHistoryTab";
 import { heartbeatsApi } from "../api/heartbeats";
 import { LiveRunWidget } from "../components/LiveRunWidget";
 import { agentsApi } from "../api/agents";
@@ -63,7 +69,7 @@ const concurrencyPolicies = ["coalesce_if_active", "always_enqueue", "skip_if_ac
 const catchUpPolicies = ["skip_missed", "enqueue_missed_with_cap"];
 const triggerKinds = ["schedule", "webhook"];
 const signingModes = ["bearer", "hmac_sha256", "github_hmac", "none"];
-const routineTabs = ["triggers", "runs", "activity"] as const;
+const routineTabs = ["triggers", "runs", "activity", "history"] as const;
 const concurrencyPolicyDescriptions: Record<string, string> = {
   coalesce_if_active: "Keep one follow-up run queued while an active run is still working.",
   always_enqueue: "Queue every trigger occurrence, even if several runs stack up.",
@@ -279,6 +285,7 @@ export function RoutineDetail() {
   const projectSelectorRef = useRef<HTMLButtonElement | null>(null);
   const [secretMessage, setSecretMessage] = useState<SecretMessage | null>(null);
   const [advancedOpen, setAdvancedOpen] = useState(false);
+  const [saveConflict, setSaveConflict] = useState(false);
   const [runVariablesOpen, setRunVariablesOpen] = useState(false);
   const [newTrigger, setNewTrigger] = useState({
     kind: "schedule",
@@ -374,19 +381,34 @@ export function RoutineDetail() {
         : null,
     [routine],
   );
-  const isEditDirty = useMemo(() => {
-    if (!routineDefaults) return false;
-    return (
-      editDraft.title !== routineDefaults.title ||
-      editDraft.description !== routineDefaults.description ||
-      editDraft.projectId !== routineDefaults.projectId ||
-      editDraft.assigneeAgentId !== routineDefaults.assigneeAgentId ||
-      editDraft.priority !== routineDefaults.priority ||
-      editDraft.concurrencyPolicy !== routineDefaults.concurrencyPolicy ||
-      editDraft.catchUpPolicy !== routineDefaults.catchUpPolicy ||
-      JSON.stringify(editDraft.variables) !== JSON.stringify(routineDefaults.variables)
-    );
+  const dirtyFields = useMemo<RoutineHistoryDirtyFieldDescriptor[]>(() => {
+    if (!routineDefaults) return [];
+    const result: RoutineHistoryDirtyFieldDescriptor[] = [];
+    if (editDraft.title !== routineDefaults.title) result.push({ key: "title", label: "the title" });
+    if (editDraft.description !== routineDefaults.description) {
+      result.push({ key: "description", label: "the description" });
+    }
+    if (editDraft.projectId !== routineDefaults.projectId) {
+      result.push({ key: "projectId", label: "the project" });
+    }
+    if (editDraft.assigneeAgentId !== routineDefaults.assigneeAgentId) {
+      result.push({ key: "assigneeAgentId", label: "the default agent" });
+    }
+    if (editDraft.priority !== routineDefaults.priority) {
+      result.push({ key: "priority", label: "the priority" });
+    }
+    if (editDraft.concurrencyPolicy !== routineDefaults.concurrencyPolicy) {
+      result.push({ key: "concurrencyPolicy", label: "the concurrency policy" });
+    }
+    if (editDraft.catchUpPolicy !== routineDefaults.catchUpPolicy) {
+      result.push({ key: "catchUpPolicy", label: "the catch-up policy" });
+    }
+    if (JSON.stringify(editDraft.variables) !== JSON.stringify(routineDefaults.variables)) {
+      result.push({ key: "variables", label: "the variables" });
+    }
+    return result;
   }, [editDraft, routineDefaults]);
+  const isEditDirty = dirtyFields.length > 0;
 
   useEffect(() => {
     if (!routine) return;
@@ -437,16 +459,32 @@ export function RoutineDetail() {
 
   const saveRoutine = useMutation({
     mutationFn: () => {
-      return routinesApi.update(routineId!, buildRoutineMutationPayload(editDraft));
+      const payload = buildRoutineMutationPayload(editDraft);
+      const baseRevisionId = routine?.latestRevisionId ?? null;
+      return routinesApi.update(routineId!, {
+        ...payload,
+        ...(baseRevisionId ? { baseRevisionId } : {}),
+      });
     },
     onSuccess: async () => {
+      setSaveConflict(false);
       await Promise.all([
         queryClient.invalidateQueries({ queryKey: queryKeys.routines.detail(routineId!) }),
         queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) }),
         queryClient.invalidateQueries({ queryKey: queryKeys.routines.activity(selectedCompanyId!, routineId!) }),
+        queryClient.invalidateQueries({ queryKey: queryKeys.routines.revisions(routineId!) }),
       ]);
     },
     onError: (error) => {
+      if (error instanceof ApiError && error.status === 409) {
+        setSaveConflict(true);
+        pushToast({
+          title: "Routine changed",
+          body: "Someone else updated this routine. Reload to see the latest revision.",
+          tone: "warn",
+        });
+        return;
+      }
       pushToast({
         title: "Failed to save routine",
         body: error instanceof Error ? error.message : "Paperclip could not save the routine.",
@@ -796,6 +834,36 @@ export function RoutineDetail() {
         </div>
       )}
 
+      {/* Save conflict banner */}
+      {saveConflict && (
+        <div className="rounded-md border border-amber-500/30 bg-amber-500/5 px-4 py-3 text-sm">
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+            <div className="space-y-1">
+              <p className="font-medium text-amber-200">Out of date</p>
+              <p className="text-xs text-muted-foreground">
+                This routine changed while you were editing. Reload to merge the latest revision before
+                saving again.
+              </p>
+            </div>
+            <div className="flex flex-wrap items-center gap-2">
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => {
+                  setSaveConflict(false);
+                  if (routineDefaults) {
+                    setEditDraft(routineDefaults);
+                  }
+                  queryClient.invalidateQueries({ queryKey: queryKeys.routines.detail(routineId!) });
+                }}
+              >
+                Reload latest
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+
       {!routine.assigneeAgentId ? (
         <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 p-4 text-sm text-amber-900 dark:text-amber-200">
           Default agent required. This routine can stay as a draft and still run manually, but automation stays paused until you assign a default agent.
@@ -999,6 +1067,10 @@ export function RoutineDetail() {
             <ActivityIcon className="h-3.5 w-3.5" />
             Activity
           </TabsTrigger>
+          <TabsTrigger value="history" className="gap-1.5">
+            <HistoryIcon className="h-3.5 w-3.5" />
+            History
+          </TabsTrigger>
         </TabsList>
 
         <TabsContent value="triggers" className="space-y-4">
@@ -1138,6 +1210,34 @@ export function RoutineDetail() {
             </div>
           )}
         </TabsContent>
+
+        <TabsContent value="history">
+          <RoutineHistoryTab
+            routine={routine}
+            isEditDirty={isEditDirty}
+            dirtyFields={dirtyFields}
+            onDiscardEdits={() => {
+              if (routineDefaults) setEditDraft(routineDefaults);
+            }}
+            onSaveEdits={() => {
+              if (!saveRoutine.isPending && editDraft.title.trim()) {
+                saveRoutine.mutate();
+              }
+            }}
+            agents={agentById}
+            projects={projectById}
+            onRestoreSecretMaterials={(response: RestoreRoutineRevisionResponse) => {
+              const recreated = response.secretMaterials[0];
+              if (recreated) {
+                setSecretMessage({
+                  title: "Webhook trigger restored",
+                  webhookUrl: recreated.webhookUrl,
+                  webhookSecret: recreated.webhookSecret,
+                });
+              }
+            }}
+          />
+        </TabsContent>
       </Tabs>
 
       <RoutineRunVariablesDialog