feat: version history for timeline sequences (#4712)

Author: georgi

CLAUDE.md

@@ -647,6 +647,26 @@ the verdict is ok. Validation and report rules live in
 `@nodetool-ai/execution/timeline-debug`; the CLI keeps target resolution, the
 interaction script, and the bundle.
 
+`timeline versions` reads and writes a sequence's snapshot history against the
+local database — manual saves, the autosaves `timeline.update` writes at most
+every five minutes, and the pre-restore snapshot that makes a restore undoable.
+All five subcommands take `--json`.
+
+```bash
+npm run dev:nodetool -- timeline versions list <timeline_id> --save-type manual --limit 10
+npm run dev:nodetool -- timeline versions show <timeline_id> 3 --json
+npm run dev:nodetool -- timeline versions create <timeline_id> --name "before the recut"
+npm run dev:nodetool -- timeline versions restore <timeline_id> 3
+npm run dev:nodetool -- timeline versions delete <timeline_id> 3 --yes
+```
+
+`restore` mirrors the tRPC router: it snapshots the current state as a
+`restore` version, CAS-writes the old document and its render settings back
+onto the sequence, then runs the same static check `timeline validate` runs. An
+old document is restored against today's schema, so what it used to pass is not
+what it passes now — a restore whose document no longer validates exits
+non-zero and prints the issues.
+
 ### Script voicing tools (no workflow, no browser)
 
 An agent voices a script and cuts it without authoring a workflow:

packages/cli/src/commands/timeline-validation-output.ts

@@ -0,0 +1,39 @@
+/**
+ * Human-readable rendering of a `TimelineValidation`, shared by
+ * `timeline validate` and `timeline versions restore` — a restored document is
+ * checked and reported exactly the way a validated one is.
+ */
+import type {
+  TimelineDebugIssue,
+  TimelineValidation
+} from "@nodetool-ai/execution/timeline-debug";
+
+/** Headline, then one line per issue — errors before warnings. */
+export function renderTimelineValidation(
+  validation: TimelineValidation
+): string[] {
+  const errors = validation.errors.length;
+  const warnings = validation.warnings.length;
+  const mark = validation.ok ? (warnings ? "⚠️" : "✅") : "❌";
+  const lines = ["", `${mark} ${errors} error(s), ${warnings} warning(s)`];
+  if (errors + warnings === 0) return lines;
+
+  lines.push("");
+  for (const issue of [...validation.errors, ...validation.warnings]) {
+    lines.push(`  ${formatTimelineIssue(issue)}`);
+  }
+  return lines;
+}
+
+function formatTimelineIssue(issue: TimelineDebugIssue): string {
+  const tag = issue.severity === "error" ? "error" : "warn ";
+  const where =
+    issue.clipId != null
+      ? ` [clip ${issue.clipId}]`
+      : issue.trackId != null
+        ? ` [track ${issue.trackId}]`
+        : issue.path != null
+          ? ` [${issue.path}]`
+          : "";
+  return `${tag} ${issue.message}${where} (${issue.code})`;
+}