Add routine revision history and restore flow (#5285)

## Thinking Path

> - Paperclip is the control plane for autonomous AI companies.
> - Routines are the scheduled/recurring work surface that keeps a
company operating without manual kicks.
> - Operators need routine edits to be auditable and recoverable,
especially when routines control assignments, prompts, triggers, and
webhook secrets.
> - Documents already have revision-style safety, but routines did not
have equivalent history or restore semantics.
> - This pull request adds append-only routine revisions across the
database, shared contracts, server routes, and board UI.
> - The benefit is safer routine iteration: users can inspect history,
compare changes, restore older definitions, and avoid overwriting newer
edits.

## What Changed

- Added `routine_revisions` storage, latest revision pointers on
routines, shared types, validators, and API docs for routine revision
history.
- Added server service/route support for listing routine revisions,
conflict-aware routine saves, and append-only restore operations.
- Added a History tab on routine detail with revision preview,
structured change summaries, description line diffs, dirty-edit
blocking, restore confirmation, and restored webhook secret surfacing.
- Extracted the line diff helper from `DocumentDiffModal` into
`ui/src/lib/line-diff.ts` for reuse.
- Rebased the branch onto current `public-gh/master` and renumbered the
routine revision migration to `0077_unusual_karnak` after upstream
`0076_useful_elektra`.
- Made the `0077` routine revision migration idempotent so installs that
already applied the branch-local `0076_unusual_karnak` can safely
advance.
- Updated the plugin SDK test harness routine fixture with the new
revision fields required by the shared `Routine` contract.

## Verification

- `pnpm --filter @paperclipai/db run check:migrations` passed.
- `pnpm exec vitest run --project @paperclipai/shared
packages/shared/src/validators/routine.test.ts` passed.
- `pnpm exec vitest run --project @paperclipai/ui
ui/src/lib/line-diff.test.ts
ui/src/components/RoutineHistoryTab.test.tsx
ui/src/lib/workspace-routines.test.ts ui/src/pages/Routines.test.tsx`
passed.
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/routines-service.test.ts --pool=forks
--poolOptions.forks.isolate=true` passed.
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/routines-routes.test.ts --pool=forks
--poolOptions.forks.isolate=true` passed.
- `pnpm --filter @paperclipai/plugin-sdk typecheck` passed after
updating the SDK test harness fixture.
- `pnpm --filter @paperclipai/plugin-sdk build` passed; this refreshed
local generated SDK output needed by plugin example typechecks.
- `pnpm -r typecheck` passed.

## Risks

- Medium migration risk: this adds routine revision storage and
backfills existing routines. The migration is ordered after upstream
`0076` and uses `IF NOT EXISTS` / duplicate-object guards to tolerate
earlier branch-local migration application.
- Restore behavior intentionally appends a new revision instead of
mutating history; callers expecting an in-place rollback need to follow
the new latest revision pointer.
- Restoring webhook triggers recreates webhook secret material, so users
must copy newly surfaced secrets after restore.
- Conflict-aware saves now reject stale routine edits when the client
sends an older `baseRevisionId`.

> 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-based coding agent, with shell/tool use in a local
git worktree. Exact context-window size is not exposed in this 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

Screenshots: not attached in this draft PR; the new UI flow is covered
by component tests listed above.

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

packages/shared/src/index.ts

@@ -501,6 +501,11 @@ export type {
   RoutineManagedByPlugin,
   RoutineVariable,
   RoutineVariableDefaultValue,
+  RoutineRevisionSnapshotRoutineV1,
+  RoutineRevisionSnapshotTriggerV1,
+  RoutineRevisionSnapshotV1,
+  RoutineRevisionSnapshot,
+  RoutineRevision,
   RoutineTrigger,
   RoutineRun,
   RoutineTriggerSecretMaterial,
@@ -781,6 +786,10 @@ export {
   routineVariableSchema,
   runRoutineSchema,
   rotateRoutineTriggerSecretSchema,
+  routineRevisionSnapshotRoutineV1Schema,
+  routineRevisionSnapshotTriggerV1Schema,
+  routineRevisionSnapshotV1Schema,
+  routineRevisionSnapshotSchema,
   type CreateSecret,
   type RotateSecret,
   type UpdateSecret,

packages/shared/src/types/index.ts

@@ -224,6 +224,11 @@ export type {
   RoutineManagedByPlugin,
   RoutineVariable,
   RoutineVariableDefaultValue,
+  RoutineRevisionSnapshotRoutineV1,
+  RoutineRevisionSnapshotTriggerV1,
+  RoutineRevisionSnapshotV1,
+  RoutineRevisionSnapshot,
+  RoutineRevision,
   RoutineTrigger,
   RoutineRun,
   RoutineTriggerSecretMaterial,

packages/shared/src/types/routine.ts

@@ -1,4 +1,13 @@
-import type { IssueOriginKind, RoutineVariableType } from "../constants.js";
+import type {
+  IssueOriginKind,
+  IssuePriority,
+  RoutineCatchUpPolicy,
+  RoutineConcurrencyPolicy,
+  RoutineStatus,
+  RoutineTriggerKind,
+  RoutineTriggerSigningMode,
+  RoutineVariableType,
+} from "../constants.js";
 
 export interface RoutineProjectSummary {
   id: string;
@@ -50,6 +59,8 @@ export interface Routine {
   concurrencyPolicy: string;
   catchUpPolicy: string;
   variables: RoutineVariable[];
+  latestRevisionId: string | null;
+  latestRevisionNumber: number;
   createdByAgentId: string | null;
   createdByUserId: string | null;
   updatedByAgentId: string | null;
@@ -73,6 +84,58 @@ export interface RoutineManagedByPlugin {
   updatedAt: Date;
 }
 
+export interface RoutineRevisionSnapshotRoutineV1 {
+  id: string;
+  companyId: string;
+  projectId: string | null;
+  goalId: string | null;
+  parentIssueId: string | null;
+  title: string;
+  description: string | null;
+  assigneeAgentId: string | null;
+  priority: IssuePriority;
+  status: RoutineStatus;
+  concurrencyPolicy: RoutineConcurrencyPolicy;
+  catchUpPolicy: RoutineCatchUpPolicy;
+  variables: RoutineVariable[];
+}
+
+export interface RoutineRevisionSnapshotTriggerV1 {
+  id: string;
+  kind: RoutineTriggerKind;
+  label: string | null;
+  enabled: boolean;
+  cronExpression: string | null;
+  timezone: string | null;
+  publicId: string | null;
+  signingMode: RoutineTriggerSigningMode | null;
+  replayWindowSec: number | null;
+}
+
+export interface RoutineRevisionSnapshotV1 {
+  version: 1;
+  routine: RoutineRevisionSnapshotRoutineV1;
+  triggers: RoutineRevisionSnapshotTriggerV1[];
+}
+
+export type RoutineRevisionSnapshot = RoutineRevisionSnapshotV1;
+
+export interface RoutineRevision {
+  id: string;
+  companyId: string;
+  routineId: string;
+  revisionNumber: number;
+  title: string;
+  description: string | null;
+  snapshot: RoutineRevisionSnapshot;
+  changeSummary: string | null;
+  restoredFromRevisionId: string | null;
+  createdByAgentId: string | null;
+  createdByUserId: string | null;
+  createdByRunId: string | null;
+  createdAt: Date;
+}
+
 export interface RoutineTrigger {
   id: string;
   companyId: string;

packages/shared/src/validators/index.ts

@@ -278,6 +278,10 @@ export {
   createRoutineTriggerSchema,
   updateRoutineTriggerSchema,
   routineVariableSchema,
+  routineRevisionSnapshotRoutineV1Schema,
+  routineRevisionSnapshotTriggerV1Schema,
+  routineRevisionSnapshotV1Schema,
+  routineRevisionSnapshotSchema,
   runRoutineSchema,
   rotateRoutineTriggerSecretSchema,
   type CreateRoutine,

packages/shared/src/validators/routine.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import {
+  routineRevisionSnapshotV1Schema,
+  updateRoutineSchema,
+} from "./routine.js";
+
+const routineId = "11111111-1111-4111-8111-111111111111";
+const companyId = "22222222-2222-4222-8222-222222222222";
+const triggerId = "33333333-3333-4333-8333-333333333333";
+const baseRevisionId = "44444444-4444-4444-8444-444444444444";
+
+describe("routine validators", () => {
+  it("accepts versioned routine revision snapshots with safe trigger metadata", () => {
+    const parsed = routineRevisionSnapshotV1Schema.parse({
+      version: 1,
+      routine: {
+        id: routineId,
+        companyId,
+        projectId: null,
+        goalId: null,
+        parentIssueId: null,
+        title: "Daily triage",
+        description: null,
+        assigneeAgentId: null,
+        priority: "medium",
+        status: "active",
+        concurrencyPolicy: "coalesce_if_active",
+        catchUpPolicy: "skip_missed",
+        variables: [],
+      },
+      triggers: [{
+        id: triggerId,
+        kind: "webhook",
+        label: "Inbound",
+        enabled: true,
+        cronExpression: null,
+        timezone: null,
+        publicId: "routine_webhook_123",
+        signingMode: "bearer",
+        replayWindowSec: 300,
+      }],
+    });
+
+    expect(parsed.triggers[0]?.publicId).toBe("routine_webhook_123");
+  });
+
+  it("rejects secret-bearing trigger fields in routine revision snapshots", () => {
+    expect(() => routineRevisionSnapshotV1Schema.parse({
+      version: 1,
+      routine: {
+        id: routineId,
+        companyId,
+        projectId: null,
+        goalId: null,
+        parentIssueId: null,
+        title: "Daily triage",
+        description: null,
+        assigneeAgentId: null,
+        priority: "medium",
+        status: "active",
+        concurrencyPolicy: "coalesce_if_active",
+        catchUpPolicy: "skip_missed",
+        variables: [],
+      },
+      triggers: [{
+        id: triggerId,
+        kind: "webhook",
+        label: "Inbound",
+        enabled: true,
+        cronExpression: null,
+        timezone: null,
+        publicId: "routine_webhook_123",
+        signingMode: "bearer",
+        replayWindowSec: 300,
+        secretId: "55555555-5555-4555-8555-555555555555",
+      }],
+    })).toThrow();
+  });
+
+  it("accepts optional base revision ids on routine updates", () => {
+    expect(updateRoutineSchema.parse({
+      title: "Daily triage",
+      baseRevisionId,
+    }).baseRevisionId).toBe(baseRevisionId);
+  });
+});

packages/shared/src/validators/routine.ts

@@ -4,6 +4,7 @@ import {
   ROUTINE_CATCH_UP_POLICIES,
   ROUTINE_CONCURRENCY_POLICIES,
   ROUTINE_STATUSES,
+  ROUTINE_TRIGGER_KINDS,
   ROUTINE_TRIGGER_SIGNING_MODES,
   ROUTINE_VARIABLE_TYPES,
 } from "../constants.js";
@@ -63,9 +64,49 @@ export const createRoutineSchema = z.object({
 
 export type CreateRoutine = z.infer<typeof createRoutineSchema>;
 
-export const updateRoutineSchema = createRoutineSchema.partial();
+export const updateRoutineSchema = createRoutineSchema.partial().extend({
+  baseRevisionId: z.string().uuid().optional().nullable(),
+});
 export type UpdateRoutine = z.infer<typeof updateRoutineSchema>;
 
+export const routineRevisionSnapshotRoutineV1Schema = z.object({
+  id: z.string().uuid(),
+  companyId: z.string().uuid(),
+  projectId: z.string().uuid().nullable(),
+  goalId: z.string().uuid().nullable(),
+  parentIssueId: z.string().uuid().nullable(),
+  title: z.string().trim().min(1).max(200),
+  description: z.string().nullable(),
+  assigneeAgentId: z.string().uuid().nullable(),
+  priority: z.enum(ISSUE_PRIORITIES),
+  status: z.enum(ROUTINE_STATUSES),
+  concurrencyPolicy: z.enum(ROUTINE_CONCURRENCY_POLICIES),
+  catchUpPolicy: z.enum(ROUTINE_CATCH_UP_POLICIES),
+  variables: z.array(routineVariableSchema),
+}).strict();
+
+export const routineRevisionSnapshotTriggerV1Schema = z.object({
+  id: z.string().uuid(),
+  kind: z.enum(ROUTINE_TRIGGER_KINDS),
+  label: z.string().nullable(),
+  enabled: z.boolean(),
+  cronExpression: z.string().nullable(),
+  timezone: z.string().nullable(),
+  publicId: z.string().nullable(),
+  signingMode: z.enum(ROUTINE_TRIGGER_SIGNING_MODES).nullable(),
+  replayWindowSec: z.number().int().min(30).max(86_400).nullable(),
+}).strict();
+
+export const routineRevisionSnapshotV1Schema = z.object({
+  version: z.literal(1),
+  routine: routineRevisionSnapshotRoutineV1Schema,
+  triggers: z.array(routineRevisionSnapshotTriggerV1Schema),
+}).strict();
+
+export const routineRevisionSnapshotSchema = routineRevisionSnapshotV1Schema;
+export type RoutineRevisionSnapshotV1 = z.infer<typeof routineRevisionSnapshotV1Schema>;
+export type RoutineRevisionSnapshot = z.infer<typeof routineRevisionSnapshotSchema>;
+
 const baseTriggerSchema = z.object({
   label: z.string().trim().max(120).optional().nullable(),
   enabled: z.boolean().optional().default(true),